Contributing to the Docs

This page explains how to contribute to this documentation site (the noix-docs repository), not to dotfix itself.

Setup

Node.js 22 or later is required (see engines in the docs package.json).

npm install

Development commands

Command	What it does
npm run dev	Start the Astro dev server with live reload
npm run build	Production build — fails on broken internal links
npm run check	Run astro check — TypeScript and Astro diagnostics

Content location

All dotfix pages live under:

src/content/docs/dotfix/
  getting-started/   ← Introduction, Installation, Your first machine, Another Mac
  guide/             ← Sets, Packages, Files & Shell, Secrets, Menubar App, Background Check
  reference/         ← CLI Commands, Repository Layout, Troubleshooting, Security & Privacy, Build from Source, Changelog, Contributing to the Docs

Adding a page

1. Create a .md file in the appropriate folder (getting-started/, guide/, or reference/).
2. Add the required frontmatter:

---
title: Page Title
description: One sentence, under 160 characters, for SEO.
sidebar:
  order: <integer>
---

The sidebar group for each folder is auto-generated from its contents; no manual sidebar wiring is needed for new files within an existing folder.

House style

• Internal links — use absolute paths within the product namespace, e.g. /dotfix/guide/sets/. Never use root-relative paths like /guide/....
• Code blocks — use a language identifier (```bash, ```toml, ```yaml).
• Callouts — use Starlight asides: :::note, :::tip, :::caution, :::danger.
• Tables — prefer tables for reference data (options, commands, keys).
• No images — screenshots are not included in this documentation.

Accuracy

dotfix’s command output and option names are quoted verbatim in these pages. When the tool changes, check dotfix <command> --help rather than trusting the page — a documented flag that does not exist is worse than no documentation.

Link integrity

The build runs starlight-links-validator. Any internal link that points to a page that does not exist will fail the build. Before adding a link, confirm the target page exists. If it does not, describe the target in prose instead.