|
| 1 | +--- |
| 2 | +title: shelldocs preview |
| 3 | +description: Serve the output of shelldocs build locally, the way a static host would, to check an export before deploying it. |
| 4 | +order: 5 |
| 5 | +--- |
| 6 | + |
| 7 | +# `shelldocs preview` |
| 8 | + |
| 9 | +`shelldocs preview` serves the static site that [`shelldocs build`](/docs/cli/build) wrote, the way GitHub Pages, Netlify and Cloudflare Pages serve it. Use it to check an export before you deploy: links, the not-found page, search, a site built for a subpath. |
| 10 | + |
| 11 | +## Synopsis |
| 12 | + |
| 13 | +```bash |
| 14 | +shelldocs preview [--dir <dir>] [--output <path>] [--port <n>] [--base-href <path>] |
| 15 | +``` |
| 16 | + |
| 17 | +## Default use |
| 18 | + |
| 19 | +Build, then preview, from the docs project folder: |
| 20 | + |
| 21 | +```bash |
| 22 | +shelldocs build |
| 23 | +shelldocs preview |
| 24 | +``` |
| 25 | + |
| 26 | +The export in `./publish` is served at `http://localhost:5050`. Press `Ctrl+C` to stop. |
| 27 | + |
| 28 | +## How it serves |
| 29 | + |
| 30 | +<TypeTable> |
| 31 | +<TypeRow Name="A file" Type="200" Description="Served as it is, with a content type from its extension." /> |
| 32 | +<TypeRow Name="A folder" Type="200" Description="Its index.html. Every page of an export is a folder with an index.html." /> |
| 33 | +<TypeRow Name="{path}.html" Type="200" Description="Used when there is no file or folder of that name." /> |
| 34 | +<TypeRow Name="Anything else" Type="404" Description="The export's 404.html, with a 404 status, as most static hosts do." /> |
| 35 | +</TypeTable> |
| 36 | + |
| 37 | +Nothing is cached, so after a rebuild a reload shows the new output. Requests can't reach files outside the export. |
| 38 | + |
| 39 | +## Sites built for a subpath |
| 40 | + |
| 41 | +An export built with `--base-href /my-repo/` is served under that path. `shelldocs preview` reads the base from the export's `index.html`, so it needs no flag: |
| 42 | + |
| 43 | +```bash |
| 44 | +shelldocs build --base-href /my-repo/ |
| 45 | +shelldocs preview |
| 46 | +``` |
| 47 | + |
| 48 | +The site is at `http://localhost:5050/my-repo/`, and `/` redirects there. Pass `--base-href` to serve under another path than the one the build wrote. |
| 49 | + |
| 50 | +## Options |
| 51 | + |
| 52 | +<TypeTable> |
| 53 | +<TypeRow Name="--dir" Type="string" Default="current folder" Description="Project folder. --output is relative to it." /> |
| 54 | +<TypeRow Name="--output" Type="string" Default="publish" Description="The static site to serve, as passed to shelldocs build." /> |
| 55 | +<TypeRow Name="--port" Type="int" Default="5050" Description="Port to listen on." /> |
| 56 | +<TypeRow Name="--base-href" Type="string?" Default="the export's base href" Description="Path to serve the site under." /> |
| 57 | +</TypeTable> |
| 58 | + |
| 59 | +## Exit codes |
| 60 | + |
| 61 | +<TypeTable> |
| 62 | +<TypeRow Name="0" Type="ok" Description="Stopped with Ctrl+C." /> |
| 63 | +<TypeRow Name="1" Type="error" Description="No index.html in the output folder. Run shelldocs build first, or point --output at its folder." /> |
| 64 | +</TypeTable> |
| 65 | + |
| 66 | +The command needs the ASP.NET Core runtime, which any machine that builds a Blazor site already has. It was added in `0.1.18-alpha`, replacing an unfinished `preview <name>` placeholder. |
| 67 | + |
| 68 | +## See also |
| 69 | + |
| 70 | +<CardGrid Columns="2"> |
| 71 | +<LinkCard Title="shelldocs build" Description="Write the static site this command serves." Href="/docs/cli/build" /> |
| 72 | +<LinkCard Title="Deployment" Description="What works on a static host, and how to publish." Href="/docs/guides/deployment" /> |
| 73 | +</CardGrid> |
0 commit comments