--- title: Publish the site description: Build the site for GitHub Pages, Netlify, or Cloudflare Pages with the base path and the origin, and use the sitemap and the 404 page each build writes. slug: /guides/publish-the-site order: 7 visibility: public redirects_from: [] --- # Publish the site Prompt: > Publish our docs on GitHub Pages under the repository's name. Also works: "Deploy the docs to Netlify." "Search engines can't find our docs pages." "A wrong address on our docs site shows the host's error page." ## What your tool does - Finds the address the host serves the site at, and passes its path as `--base` and its scheme and host as `--origin`. - Sets the host's build command to the tzdocs build and its published folder to the build's output folder. - Builds, serves the output folder locally, and opens a page, a missing address, and `sitemap.xml`. - Asks for the site's address where the project does not state it. ## What you need - The host, and the address the site will be served at. ## Before your AI starts This section is for your AI coding tool: what it checks and gathers before it begins. You don't need to do these steps yourself. - A corpus that passes the check and builds ([Getting started](/getting-started/)). ## Steps ### 1. Choose the base path and the origin Two flags describe where the site lives: - `--base` is the path the site is served under, such as `/docs`. Leave it out when the site has the whole host to itself. - `--origin` is the scheme and the host, such as `https://example.com`. With it, each page names its canonical address, and the build writes `sitemap.xml`. The pages link each other relatively, so they work under any base path. The base path goes into the machine files and into the 404 page, whose links are absolute paths. ### 2. Build for GitHub Pages GitHub Pages serves a project site at `https://.github.io//`. Build it with the repository's name as the base path. ```text tzdocs build --source docs --out site --base / --origin https://.github.io ``` Publish the `site` folder, for example from a workflow that uploads it as the Pages artifact. A user or organization site, or a site on a custom domain, is served at the root of its host. Leave out `--base` for it, and give its address as the origin. ### 3. Or build for Netlify or Cloudflare Pages Netlify and Cloudflare Pages build the site from your repository and serve it at the root of its host. ```text tzdocs build --source docs --out site --origin https://docs.example.com ``` Make that the project's build command, and `site` its output or publish folder. Add tzdocs to the project's development dependencies, so the host's build installs it ([Getting started](/getting-started/)). For drawn diagrams, add `mermaid` beside it ([Add callouts and diagrams](/guides/callouts-and-diagrams/)). ### 4. Offer the sitemap With `--origin`, the build writes `sitemap.xml` at the tree root, one address per page in the navigation order. It lists no redirect stub, and it carries no dates, so two builds of one source stay identical. Without `--origin` the build writes no sitemap, because a sitemap must give absolute addresses. Give the sitemap's address, such as `https://example.com/docs/sitemap.xml`, to a search engine's site tools. Or name it in the `robots.txt` at the root of the host, a file the tool does not write. ```text Sitemap: https://example.com/docs/sitemap.xml ``` ### 5. Rely on the 404 page Every build writes `404.html` at the tree root. GitHub Pages, Netlify, and Cloudflare Pages each show a site's root `404.html` for an address that matches no file. On Cloudflare Pages it also keeps a missing address from showing the home page instead. The page says that no page lives at the address and links to the home page. Its stylesheet and home links begin with the base path, so it displays correctly at any depth. It carries no navigation, and it tells search engines not to list it. Under `--shell` it renders into the shell, so it keeps the site's header and footer. ### 6. Look at the result Serve the output folder with any static server, for example `npx serve site`, and open a page. A browser that opens the files from disk does not resolve the folder links between pages ([Output](/reference/output/#the-tree)). ## Expected result The host serves the home page at the site's address, and each page's links and stylesheet resolve. A missing address shows the 404 page, styled. With `--origin`, `sitemap.xml` lists every page's absolute address. ## Refusals [Refusals and findings](/reference/refusals/) gives the exact text. | Message | Exit code | Cause | Remedy | | --- | --- | --- | --- | | `--base needs a path that starts with / and does not end with one, such as /docs, not ""` | 2 | The base path does not start with `/`, or still ends with one. | Write the path the site is served under, such as `/docs`. | | `--origin needs an http or https origin with no path, such as https://example.com, not ""` | 2 | The origin is not an `http` or `https` address, or has a path. | Give the scheme and host alone, and put the path in `--base`. | ## Related - [Getting started](/getting-started/) lists every flag of the build. - [Output](/reference/output/#machine-files) describes the sitemap beside the other machine files. - [Build for AI tools](/guides/build-for-ai-tools/) covers the files an AI tool reads.