UniXNU/docs/contributing/documentation.md

Documentation site

The documentation is a VitePress site in docs/. It is published to https://unixnu.com.

Procedure

1. Identify the owning page and its English/Chinese counterpart. For device results, update the device's structured record.
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 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 and Technical reference to the changed page in both languages.
5. Preview the page using 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

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. 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. 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

cd docs
npm run build

VitePress fails the build on a broken internal link.

Next steps

• Repository layout
• Port a device

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.

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.