shelldocs build

shelldocs build turns a ShellDocs project into a folder of static files that any static host can serve. It publishes the app, starts it locally, saves every page as HTML, and copies the assets next to them.

Synopsis

shelldocs build [--dir <dir>] [--output <path>] [--base-href <path>] [--spa-fallback] [--site-url <url>]

Default use

Run it from the docs project folder:

shelldocs build

The site is written to ./publish.

What it does

1. Publishes the project

   Runs dotnet publish -c Release into a scratch folder under obj/.

2. Makes sure the content is there

   Copies any file under content/ that publish left out. A project that copies meta.json but not the .md files would otherwise prerender every page as not found.

3. Finds every URL

   Reads the navigation graph from content/, hidden pages included, and adds the home page.

4. Prerenders each page

   Starts the published app on a local port, requests each URL, and saves the response as index.html in a folder named after the URL. A page that answers 404, or renders the not-found view, fails the build.

5. Writes redirect pages

   Asks the running app for its redirect map and writes a small redirect page at each source URL. See Redirects.

6. Writes the not-found page

   Requests a URL that doesn't exist and saves the site's not-found view as 404.html. See Not-found page.

7. Copies the search index

   Saves the app's search index as _shelldocs/search.json, which is what makes search work without a server.

8. Writes the llms.txt files

   On a site that calls EnableLlmsTxt, writes llms.txt, llms-full.txt, every page's .md and the agent files. Their links use --site-url, then SiteUrl. See AI agents (llms.txt).

9. Copies the assets

   Merges the published wwwroot into the output: framework scripts, shelldocs.js, stylesheets, your own static files. Prerendered pages are never overwritten.

10. Applies the optional flags

    Rewrites the base href, replaces 404.html with the home page, and adds the sitemap, robots file and social meta tags when asked.

The project stays a normal Blazor Web App. Nothing about it changes for the export.

Custom pages

Only pages under content/ and the home page are discovered. A page you add with its own @page directive is not prerendered. Keep such pages to a minimum on a site you export, or host on a .NET server instead.

Flags

--site-url

Give the address the site will be served from to get three things:

• sitemap.xml listing every page.
• robots.txt that allows crawling and points at the sitemap.
• og:title, og:description, og:url and og:type meta tags on every page, taken from each page's frontmatter, so shared links show a proper preview.

shelldocs build --site-url https://docs.example.com

Without the flag none of these are written, so a local build never produces a sitemap with the wrong address.

--base-href

For a site served from a subpath. Rewrites the base tag in every HTML file so assets resolve under the subpath. Include the leading and trailing slash.

shelldocs build --base-href /my-repo/

--spa-fallback

Replaces 404.html with a copy of the root index.html, so a host that serves 404.html for unknown URLs shows the home page instead of the not-found page.

Leave it off unless the site has pages of its own that are routed in the browser and never prerendered. Without the flag, 404.html is the site's not-found page, which tells the reader the address is wrong and links back to the docs.

--output and --dir

--output sets the output folder, relative to the project. The folder is emptied first. --dir points the command at a project in another folder.

Options

Exit codes

What a static site can't do

Search, the sidebar, tabs and the rest of the chrome work in the export: shelldocs.js drives them. Only what depends on Blazor event handlers needs a running app, such as a live demo with @onclick handlers. The full list is in Deployment.

See also