Contributing to the Docs

This page explains how to contribute to this documentation site (the noix-docs repository), not to the nfc-keyboard-emulator application itself. For app contributions see CONTRIBUTING.md in the app repository.

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 nfc-keyboard-emulator pages live under:

src/content/docs/nfc-keyboard-emulator/
  getting-started/   ← Introduction, Installation, First scan
  guide/             ← Readers, Typing & Safety, Output Format, Scan Log, Tray & Startup
  reference/         ← Supported Hardware, Troubleshooting, Security & Privacy, Build from Source, Contributing to the Docs, Changelog

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. /nfc-keyboard-emulator/guide/readers/. Never use root-relative paths like /guide/....
• Code blocks — use a language identifier (```bash, ```ini, ```yaml). For KEY=value blocks use ```ini; do not use ```env (no highlighter).
• Callouts — use Starlight asides: :::note, :::tip, :::caution, :::danger.
• Tables — prefer tables for reference data (options, commands, environment variables).
• No images — screenshots are not included in this 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.