119 lines
4.5 KiB
Markdown
119 lines
4.5 KiB
Markdown
# Documentation site
|
|
|
|
The documentation is a VitePress site in `docs/`. It is published to `https://unixnu.com`.
|
|
|
|
## Procedure {#procedure}
|
|
|
|
1. Identify the owning page and its English/Chinese counterpart. For device results, update the device's [structured record](#device-records).
|
|
2. Edit the current procedure or reference. An operation needs prerequisites, working directory, ordered commands, expected results and the next step.
|
|
3. Link the page from the relevant workflow. Follow [Add a page](#add-a-page) for navigation and locale entries.
|
|
4. Run `npm --prefix docs run build` from the main checkout. Resolve build errors, then follow body links from [Port a device](/porting/steps) and [Technical reference](/reference/) to the changed page in both languages.
|
|
5. Preview the page using [local development](#local-development), check its command blocks and next-step links, then publish the documentation commit.
|
|
|
|
## Requirements
|
|
|
|
| Tool | Version |
|
|
| --- | --- |
|
|
| Node.js | 22 or newer |
|
|
| npm | 10 or newer |
|
|
|
|
## Local development
|
|
|
|
```sh
|
|
cd docs
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
The site runs at the URL printed by VitePress. `npm run build` writes the static site to `docs/.vitepress/dist`. `npm run preview` serves the built site.
|
|
|
|
## Structure
|
|
|
|
```
|
|
docs/
|
|
.vitepress/
|
|
config.mts site configuration
|
|
theme/ custom CSS
|
|
public/
|
|
CNAME custom domain
|
|
logo-light.svg
|
|
logo-dark.svg
|
|
guide/ getting started and build
|
|
concepts/ boot chain, payload, prelink, userdata, security
|
|
porting/ device porting
|
|
drivers/ UEFI, XNU and kext drivers
|
|
xnu/ source, patches, pages, boot arguments
|
|
devices/ device pages and examples
|
|
reference/ command line, configuration, outputs, QEMU, glossary
|
|
contributing/ this section
|
|
zh/ Simplified Chinese locale
|
|
```
|
|
|
|
## Add a page
|
|
|
|
Format 2 device pages follow [record publication](/porting/records#publishing-and-reuse). Use these steps for authored guides.
|
|
|
|
1. Create the Markdown file under the matching section.
|
|
2. Add the page to the sidebar in `docs/.vitepress/config.mts`.
|
|
3. Add the Chinese page under `docs/zh/` and to the Chinese sidebar.
|
|
4. Link the page from a relevant guide or topic index reachable from [Port a device](/porting/steps). Put task prerequisites and the next step in the page body.
|
|
5. Follow the body links from Port a device in each language to confirm the page is reachable.
|
|
6. Run `npm run build` and fix broken links.
|
|
7. Add the language switcher entry when a new section starts.
|
|
|
|
## Language editions
|
|
|
|
The site has two locales:
|
|
|
|
| Locale | Path | Language |
|
|
| --- | --- | --- |
|
|
| Root | `/` | English |
|
|
| `zh` | `/zh/` | Simplified Chinese |
|
|
|
|
Both editions carry the same pages. A change to one page updates both editions in the same pull request.
|
|
|
|
## Writing rules
|
|
|
|
- Use standard technical terms.
|
|
- State the current behavior directly.
|
|
- Avoid em-dashes and en-dashes.
|
|
- Avoid metaphors.
|
|
- Use neutral headings.
|
|
- Keep the page focused on one subject.
|
|
- Use tables for references and lists for steps.
|
|
- Put device-specific values in the device page.
|
|
- Put a concrete command in every procedure.
|
|
- Number task steps in execution order and include inputs, working directory, commands, expected results and the next step. Reference pages link to the relevant procedure.
|
|
|
|
## Link check
|
|
|
|
```sh
|
|
cd docs
|
|
npm run build
|
|
```
|
|
|
|
VitePress fails the build on a broken internal link.
|
|
|
|
## Next steps
|
|
|
|
- [Repository layout](/contributing/repository)
|
|
- [Port a device](/porting/steps)
|
|
|
|
## Device records
|
|
|
|
Site builds require Python 3.11 or newer. `npm run build` renders the committed
|
|
catalog and record snapshots. The twice-daily catalog workflow discovers sources,
|
|
pins revisions and refreshes format 2 pages, the index and navigation.
|
|
Edit `porting.toml` in the device repository and publish it. Both language
|
|
editions use the same record. Existing legacy pages retain their authored text;
|
|
new legacy entries contain a repository link. See the [record guide](/porting/records#publishing-and-reuse).
|
|
|
|
## Driver guides
|
|
|
|
Organize steps by hardware inputs, interface implementation, OS integration,
|
|
build and verification. Link real source files at reviewed revisions and name
|
|
the relevant symbols, call order, data ownership and error handling. Use board
|
|
sources as references and keep device status in device records. Each step states
|
|
what to change and how to observe its result. Use matching source references in
|
|
the English and Chinese editions.
|