Skip to content

Commit 86b5ddd

Browse files
authored
Merge pull request #10 from Semantic-Org/docs/site
Docs(site): Move the navrouter.dev site into docs/
2 parents 9628222 + 8628916 commit 86b5ddd

90 files changed

Lines changed: 14417 additions & 1406 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
name: Release Deploy
2+
3+
# Deploys the docs site to production (navrouter.dev) on a tagged release, so the live docs match
4+
# the last release while staging shows main. Builds here and ships prebuilt, as staging-deploy.yml
5+
# does. Run it by hand (Actions > Release Deploy > Run workflow) to ship before the first tag.
6+
# Requires: VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_NAVROUTER_PROJECT_ID
7+
8+
on:
9+
push:
10+
tags:
11+
- 'v*'
12+
workflow_dispatch:
13+
14+
concurrency:
15+
group: release-deploy
16+
cancel-in-progress: false
17+
18+
permissions:
19+
contents: read
20+
21+
jobs:
22+
docs:
23+
name: Deploy docs to production
24+
runs-on: ubuntu-latest
25+
timeout-minutes: 15
26+
env:
27+
VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
28+
VERCEL_PROJECT_ID: ${{ secrets.VERCEL_NAVROUTER_PROJECT_ID }}
29+
steps:
30+
- uses: actions/checkout@v7
31+
- uses: actions/setup-node@v7
32+
with:
33+
node-version-file: '.node-version'
34+
cache: 'npm'
35+
36+
- uses: actions/cache@v6
37+
with:
38+
path: docs/node_modules/.astro
39+
key: docs-astro-${{ runner.os }}-${{ github.sha }}
40+
restore-keys: |
41+
docs-astro-${{ runner.os }}-
42+
43+
# from the repo root, as in staging-deploy.yml
44+
- name: Build and deploy docs to production
45+
env:
46+
VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
47+
run: |
48+
npx vercel pull --yes --environment=production --token="$VERCEL_TOKEN"
49+
npx vercel build --prod --token="$VERCEL_TOKEN"
50+
npx vercel deploy --prebuilt --prod --token="$VERCEL_TOKEN"
Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: Staging Deploy
2+
3+
# Deploys the docs site to the staging environment (staging.navrouter.dev) on every push to main that
4+
# touches the site or the packages it documents. Builds here and ships prebuilt, so Vercel runs no
5+
# build. Vercel's own Git deploys are off (docs/vercel.json); this and release-deploy.yml are the
6+
# only ways into an environment. Same flow as Semantic-Org/Semantic-Next.
7+
# Requires: VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_NAVROUTER_PROJECT_ID
8+
9+
on:
10+
push:
11+
branches: [main]
12+
paths:
13+
- 'docs/**'
14+
- 'packages/**'
15+
- 'package-lock.json'
16+
- '.github/workflows/staging-deploy.yml'
17+
18+
concurrency:
19+
# a newer main push supersedes an in-flight staging build
20+
group: staging-deploy
21+
cancel-in-progress: true
22+
23+
permissions:
24+
contents: read
25+
26+
jobs:
27+
docs:
28+
name: Deploy docs to staging
29+
runs-on: ubuntu-latest
30+
timeout-minutes: 15
31+
env:
32+
VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
33+
VERCEL_PROJECT_ID: ${{ secrets.VERCEL_NAVROUTER_PROJECT_ID }}
34+
steps:
35+
- uses: actions/checkout@v7
36+
- uses: actions/setup-node@v7
37+
with:
38+
node-version-file: '.node-version'
39+
cache: 'npm'
40+
41+
# astro's incremental cache, shared with the release deploy
42+
- uses: actions/cache@v6
43+
with:
44+
path: docs/node_modules/.astro
45+
key: docs-astro-${{ runner.os }}-${{ github.sha }}
46+
restore-keys: |
47+
docs-astro-${{ runner.os }}-
48+
49+
# from the repo root: the project's Root Directory is docs/, which vercel applies relative to
50+
# the working directory. the CLI pairs --environment (pull) with --target (build, deploy) for
51+
# a custom environment. `vercel build` runs the project's install and `npm run build`, which
52+
# syncs the sandbox first, so the output matches a remote build
53+
- name: Build and deploy docs to staging
54+
env:
55+
VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
56+
run: |
57+
npx vercel pull --yes --environment=staging --token="$VERCEL_TOKEN"
58+
npx vercel build --target=staging --token="$VERCEL_TOKEN"
59+
npx vercel deploy --prebuilt --target=staging --token="$VERCEL_TOKEN"

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,4 @@ node_modules
22
dist
33
.DS_Store
44
*.log
5+
.vercel

‎.node-version‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
24

‎docs/.gitignore‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
node_modules/
2+
dist/
3+
.astro/
4+
cert/*
5+
!cert/README.md
6+
# generated by npm run sandbox
7+
public/sandbox/
8+
public/libs/

‎docs/README.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
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.

‎docs/astro.config.mjs‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
import { rehypeHeadingIds, unified } from '@astrojs/markdown-remark';
2+
import { transformerMetaHighlight } from '@shikijs/transformers';
3+
import { defineConfig } from 'astro/config';
4+
import { existsSync, readFileSync } from 'node:fs';
5+
import remarkDirective from 'remark-directive';
6+
import { createCssVariablesTheme } from 'shiki';
7+
8+
import { rehypeDocs } from './src/lib/markdown/rehype-docs.js';
9+
import { remarkDocs } from './src/lib/markdown/remark-docs.js';
10+
import { transformerFenceMeta } from './src/lib/markdown/shiki-meta.js';
11+
12+
// shiki writes css variables; tokens.css maps them onto the site's syntax colors, so code follows
13+
// the theme toggle with no second highlighting pass
14+
const theme = createCssVariablesTheme({ name: 'nav-router', variablePrefix: '--shiki-', fontStyle: true });
15+
// read as the site reads code: object keys as keys, the colon after them as punctuation, comments set back
16+
theme.tokenColors.push(
17+
{
18+
scope: ['meta.object-literal.key', 'support.type.property-name'],
19+
settings: { foreground: 'var(--shiki-token-parameter)' },
20+
},
21+
{
22+
scope: ['punctuation.separator.key-value', 'meta.object-literal.key punctuation'],
23+
settings: { foreground: 'var(--shiki-token-punctuation)' },
24+
},
25+
{
26+
scope: ['comment', 'punctuation.definition.comment'],
27+
settings: { foreground: 'var(--shiki-token-comment)', fontStyle: 'italic' },
28+
},
29+
);
30+
31+
const HOST = 'local.navrouter.dev';
32+
const CERT = { key: `./cert/${HOST}-key.pem`, cert: `./cert/${HOST}.pem` };
33+
const hasCert = existsSync(CERT.key) && existsSync(CERT.cert);
34+
if (!hasCert) { console.warn('[site] no cert in cert/: dev runs over http on :4321. Run `npm run cert`.'); }
35+
36+
export default defineConfig({
37+
site: 'https://navrouter.dev',
38+
trailingSlash: 'always',
39+
// the dev origin: https://local.navrouter.dev on :443, every interface, one site up at a time (the
40+
// house pattern). without the cert (npm run cert, see cert/README.md), plain http on :4321
41+
server: { host: true, port: hasCert ? 443 : 4321 },
42+
devToolbar: { enabled: false },
43+
vite: {
44+
server: {
45+
allowedHosts: [HOST],
46+
fs: { allow: ['..'] },
47+
...(hasCert && {
48+
https: { key: readFileSync(CERT.key), cert: readFileSync(CERT.cert) },
49+
hmr: { host: HOST, protocol: 'wss' },
50+
}),
51+
},
52+
},
53+
markdown: {
54+
processor: unified({
55+
remarkPlugins: [remarkDirective, remarkDocs],
56+
// ids first, so the docs plugin can anchor headings; astro then skips its own pass
57+
rehypePlugins: [rehypeHeadingIds, rehypeDocs],
58+
}),
59+
shikiConfig: {
60+
theme,
61+
transformers: [transformerMetaHighlight(), transformerFenceMeta()],
62+
},
63+
},
64+
});

‎docs/cert/README.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Local-dev SSL certs
2+
3+
`npm run dev` serves `https://local.navrouter.dev` on :443 when the cert is here: one dev site up at
4+
a time, always at the same origin. HTTPS is needed off localhost, and by the playground's service
5+
worker.
6+
7+
`npm run cert` signs one with the dev CA this machine already trusts (`next/docs/cert`, or set
8+
`DEV_CA_DIR`), so there is nothing new to trust. The CA's key is read in place, never copied here.
9+
10+
Then point the name at the machine: `<vm ip> local.navrouter.dev` in the hosts file of the machine
11+
you browse from (or a DNS record, since the domain is ours), and `127.0.0.1 local.navrouter.dev` here.
12+
13+
Without a cert, dev falls back to plain http on :4321. Certs are git-ignored; only this README is kept.

‎docs/package.json‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
{
2+
"name": "nav-router-docs",
3+
"private": true,
4+
"type": "module",
5+
"scripts": {
6+
"dev": "astro dev",
7+
"build": "npm run sandbox && astro sync --force && astro build && pagefind --site dist",
8+
"preview": "astro preview",
9+
"clean": "rm -rf dist .astro node_modules/.astro",
10+
"cert": "bash scripts/make-cert.sh",
11+
"sandbox": "node scripts/sync-sandbox.mjs"
12+
},
13+
"dependencies": {
14+
"@astrojs/markdown-remark": "7.3.5",
15+
"@fontsource-variable/schibsted-grotesk": "^5.3.0",
16+
"@fontsource/fragment-mono": "^5.3.0",
17+
"@fontsource/schibsted-grotesk": "^5.3.0",
18+
"@semantic-ui/playground": "^0.18.0",
19+
"@semantic-ui/utils": "^0.18.0",
20+
"@shikijs/transformers": "4.6.0",
21+
"astro": "7.4.6",
22+
"esbuild": "0.28.2",
23+
"pagefind": "1.6.0",
24+
"remark-directive": "4.0.0",
25+
"satori": "^0.63.2",
26+
"shiki": "4.6.0",
27+
"unist-util-visit": "5.2.0",
28+
"yaml": "2.9.1"
29+
}
30+
}

‎docs/public/favicon.svg‎

Lines changed: 1 addition & 0 deletions
Loading

0 commit comments

Comments
 (0)