You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/README.md
+20-24Lines changed: 20 additions & 24 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,46 +17,42 @@ docs/
17
17
18
18
## Writing Documentation
19
19
20
-
Write plain Markdown without frontmatter:
20
+
Each Markdown file needs minimal YAML frontmatter with a title and description:
21
21
22
22
```markdown
23
-
# Your Page Title
23
+
---
24
+
title: Your Page Title
25
+
description: A brief summary of what this page covers.
26
+
---
24
27
25
28
Content here...
26
29
```
27
30
28
-
The build process automatically extracts the title from the first `# Heading` and adds frontmatter to a temporary copy.
31
+
Starlight renders the `title` as the page's H1 heading, so do **not** add a separate `# Heading` in the content.
29
32
30
33
### Best Practices
31
34
32
-
- Use standard Markdown - keep it simple and GitHub-friendly
33
-
-Start with H1 heading: `# Title`
34
-
- Use relative links: `[text](./other-doc.md)`
35
+
- Use standard Markdown — keep it simple and GitHub-friendly
36
+
-Always include `title` and `description` in frontmatter
37
+
- Use relative links with `.md` extensions: `[text](./other-doc.md)` (works on GitHub; a rehype plugin strips `.md` at build time)
35
38
- Use `.md` files (not `.mdx`) for better GitHub rendering
36
39
- Code blocks with language: ` ```bash `
40
+
- Use em dashes (`—`) to separate list item subjects from descriptions: `- **Term** — Description`
37
41
38
42
## Generated Documentation
39
43
40
44
Some docs are auto-generated from code:
41
45
42
-
-**`reference/cli.md`**- Generated by `scripts/generate-cli-docs.sh` from CLI command definitions
43
-
-**`schemas/*.json`**- Generated by `scripts/generate-config-schemas.sh` from Rust types
46
+
-**`reference/cli.md`**— Generated by `scripts/generate-cli-docs.sh` from CLI command definitions
47
+
-**`schemas/*.json`**— Generated by `scripts/generate-config-schemas.sh` from Rust types
44
48
45
49
Run these scripts when command-line options or config types change.
46
50
47
51
## Build Process
48
52
49
-
The documentation website is built using [Astro](https://astro.build/) + [Starlight](https://starlight.astro.build/). The build process is handled by `scripts/prepare-docs.sh`, which:
53
+
The documentation website is built using [Astro](https://astro.build/) + [Starlight](https://starlight.astro.build/). Starlight reads directly from the `docs/` directory via a glob content loader — no preprocessing step is needed.
50
54
51
-
1. Copies markdown files from `docs/` to `docs-site/.docs-temp/` (excluding schemas and READMEs)
52
-
2. Adjusts relative paths and strips `.md` extensions for Starlight's clean URLs
53
-
3. Adds frontmatter (extracts title from H1 heading)
54
-
55
-
This keeps source docs clean and framework-agnostic while enabling a polished documentation site. The script runs automatically during the build process (`npm run build` in `docs-site/`), but you can also run it manually:
56
-
57
-
```bash
58
-
./scripts/prepare-docs.sh
59
-
```
55
+
A rehype plugin (`docs-site/plugins/rehype-rewrite-links.mjs`) rewrites `.md` links at build time so that relative links with `.md` extensions work on both GitHub and the documentation site.
60
56
61
57
## Preview
62
58
@@ -85,8 +81,8 @@ The documentation website is automatically built and deployed to GitHub Pages:
85
81
## Adding New Documentation
86
82
87
83
1. Create a `.md` file in the appropriate directory
88
-
2.Start with a `# Heading` (used as page title)
89
-
3. Write standard Markdown content
84
+
2.Add YAML frontmatter with `title` and `description`
85
+
3. Write standard Markdown content (no H1 heading — Starlight renders the title)
90
86
4. Add the page to the sidebar in `../docs-site/astro.config.mjs` under the appropriate section:
91
87
```js
92
88
{
@@ -100,9 +96,9 @@ The documentation website is automatically built and deployed to GitHub Pages:
0 commit comments