Documentation site

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

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

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. Run npm run build and fix broken links.
5. 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.

Deploy

The workflow .github/workflows/docs.yml builds the site on every push to main that touches docs/ and deploys it with GitHub Pages.

The site needs:

1. GitHub Pages enabled with GitHub Actions as the source.
2. The custom domain unixnu.com in the repository Pages settings.
3. DNS records for the domain.

docs/public/CNAME contains:

unixnu.com

DNS for an apex domain:

Type	Name	Value
A	@	185.199.108.153
A	@	185.199.109.153
A	@	185.199.110.153
A	@	185.199.111.153
CNAME	www	unixnu.github.io

GitHub Pages also serves the site over IPv6:

Type	Name	Value
AAAA	@	2606:50c0:8000::153
AAAA	@	2606:50c0:8001::153
AAAA	@	2606:50c0:8002::153
AAAA	@	2606:50c0:8003::153

Enable Enforce HTTPS after the certificate is issued.

Badge

The README uses:

[![Documentation](https://img.shields.io/badge/docs-unixnu.com-2A5BD7?logo=readthedocs&logoColor=white)](https://unixnu.com)

Link check

cd docs
npm run build

VitePress fails the build on a broken internal link.

Next steps

• Repository layout
• Overview