Publish the site #

View this page as Markdown

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.

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://<user>.github.io/<repository>/. Build it with the repository's name as the base path.

tzdocs build --source docs --out site --base /<repository> --origin https://<user>.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.

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). For drawn diagrams, add mermaid beside it (Add 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.

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).

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 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 "<value>" 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 "<value>" 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.