|
| 1 | +# navrouter.dev |
| 2 | + |
| 3 | +The docs for nav-router, in `docs/` of the monorepo. Run the commands below from here (`docs/`), or |
| 4 | +from the root with `npm -w docs run <script>`. |
| 5 | + |
| 6 | +The nav-router site: a homepage and docs, built with Astro from plain Markdown. Astro only turns |
| 7 | +Markdown into pages through the layouts. Styles and the few scripts are plain CSS and JS, and every |
| 8 | +page ships as static HTML. |
| 9 | + |
| 10 | +```sh |
| 11 | +npm install # from the repo root: the docs are a workspace |
| 12 | +npm run sandbox # once: the playground's workers and the example libraries into public/ |
| 13 | +npm run cert # once: a local.navrouter.dev cert from the trusted dev CA (see cert/README.md) |
| 14 | +npm run dev # https://local.navrouter.dev on :443; search uses /search-index.json |
| 15 | +npm run build # the sandbox, then the static site in dist/, then a Pagefind index |
| 16 | +npm run preview # serve dist/, search uses Pagefind |
| 17 | +``` |
| 18 | + |
| 19 | +Plugin and core sizes are measured at build from `../packages/nav-router` (`src/lib/sizes.js`), |
| 20 | +so they are always the package's own. A size that can't be measured fails the build. |
| 21 | + |
| 22 | +Live examples (`/examples/`) run on `@semantic-ui/playground` from npm. `npm run sandbox` copies its |
| 23 | +workers into `public/sandbox/`, and the libraries the examples import into `public/libs/` (nav-router's |
| 24 | +source, and the one-file build of `@semantic-ui/utils`). Run it once after install; the copies are |
| 25 | +git-ignored. |
| 26 | + |
| 27 | +## Deploys |
| 28 | + |
| 29 | +CI builds and ships prebuilt to Vercel (project `navrouter`, Root Directory `docs`). Vercel's own |
| 30 | +Git deploys are off. |
| 31 | + |
| 32 | +| Trigger | Environment | |
| 33 | +|---|---| |
| 34 | +| Push to `main` touching `docs/` or `packages/` | staging, `staging.navrouter.dev` (`.github/workflows/staging-deploy.yml`) | |
| 35 | +| A `v*` tag, or Run workflow by hand | production, `navrouter.dev` (`.github/workflows/release-deploy.yml`) | |
| 36 | + |
| 37 | +## Writing a page |
| 38 | + |
| 39 | +A page is a Markdown file in `src/content/docs/<section>/`, where section is `guides`, `api` or |
| 40 | +`plugins`. Its place in the sidebar comes from `src/lib/nav.js`. A nav item whose page doesn't exist |
| 41 | +yet shows as a dimmed stub. |
| 42 | + |
| 43 | +```yaml |
| 44 | +--- |
| 45 | +title: isActive() # set as code when the page has a kind |
| 46 | +kind: function # class | function | plugin, optional |
| 47 | +lede: One or two sentences. `code` is allowed. |
| 48 | +import: import { isActive } from 'nav-router' # optional, shown with a copy button |
| 49 | +size: core # optional: 'core' or a plugin file name, measured at build |
| 50 | +updated: 2026-11-05 |
| 51 | +--- |
| 52 | +``` |
| 53 | + |
| 54 | +### Conventions |
| 55 | + |
| 56 | +| Write | Get | |
| 57 | +|---|---| |
| 58 | +| `:::note[Title]` … `:::` | A callout. Also `tip`, `warning`, `danger`. | |
| 59 | +| `:::steps` around an ordered list | Numbered steps. Start each item with **bold** text for its title. | |
| 60 | +| `:::entry` … `:::` | A reference entry. Open it with ``### `navigate()` :kind[method]``. | |
| 61 | +| `:::truth` around a table | `true` and `false` cells become tinted words. | |
| 62 | +| ` ```js title="app.js" ` | A code block with a file name. | |
| 63 | +| ` ```js for="core vue svelte semantic" label="routes.js" ` | Consecutive fences like this become one block with a tab per version. The reader's framework picks the tab. | |
| 64 | +| ` ```js {3,5} ` | Highlighted lines. | |
| 65 | +| ` ```js signature ` | A signature block. | |
| 66 | +| ` ```params ` / ` ```returns ` | YAML rendered as parameter rows (`name`, `type`, `required`, `default`, `description`, nested `options`). | |
| 67 | +| A table with a `Type` column | Code in that column is read as types. | |
| 68 | +| A paragraph of only **bold** text inside an entry | An entry label such as "Parameters". | |
| 69 | + |
| 70 | +A block that holds another block needs a longer fence: `::::entry` around a `:::warning`. |
| 71 | + |
| 72 | +Framework ids for `for=` are in `FRAMEWORKS` in `src/scripts/site.js`. Preact falls back to the React |
| 73 | +version, and every other framework falls back to `core`. |
| 74 | + |
| 75 | +## Layout |
| 76 | + |
| 77 | +| Path | Holds | |
| 78 | +|---|---| |
| 79 | +| `src/content/docs/` | the pages | |
| 80 | +| `src/lib/nav.js` | sections, groups and their order | |
| 81 | +| `src/lib/markdown/` | the remark and rehype passes and the Shiki meta transformer behind the conventions above | |
| 82 | +| `src/layouts/` | `Base` (document, theme) and `Docs` (topbar, sidebar, on this page, pager) | |
| 83 | +| `src/styles/` | `tokens.css` (shared), `docs.css`, `home.css` | |
| 84 | +| `src/scripts/` | `site.js` (framework picker, code tabs, copy, inline code, theme), `search.js`, `docs-client.js`, `hero.js` | |
| 85 | +| `src/lib/home-body.html` | the homepage markup, kept as HTML because its code samples are full of braces | |
| 86 | + |
| 87 | +`npm run build` runs `astro sync --force` first. Astro caches rendered Markdown and doesn't notice |
| 88 | +changes to the Markdown plugins. |
0 commit comments