Contributing to the Docs

This page explains how to contribute to the documentation you are reading. The docs live in the noix-docs repository and are built with Astro Starlight.

Prerequisites

• Node.js 22 or later (see engines.node in package.json)
• npm (bundled with Node)
• A text editor

Setup

git clone https://github.com/NoiXdev/noix-docs.git
cd noix-docs
npm install

Local preview

npm run dev

Opens a dev server at http://localhost:4321. Changes to Markdown files hot-reload instantly.

Build

npm run build

Produces a production build in dist/. The build also runs starlight-links-validator, which fails the build if any internal links are broken. Fix all broken links before opening a PR.

Type-check

npm run check

Runs astro check to catch TypeScript and Astro component errors.

---

Where content lives

src/content/docs/inventorix/
  admin/
    installation/    # requirements, docker, environment, first-run
    configuration/   # mail, authentication, queues, storage, application
    introduction.md
    operations.md
    security.md
  user/
    getting-started.md
    assets.md
    catalog.md
    handovers.md
    users-and-access.md
    qr-codes.md
    scanning.md
    import-export.md
    notifications.md
    reports.md
    account.md
  reference/
    environment-variables.md
    cli-commands.md
    faq.md
    contributing-docs.md   # ← this file
    changelog.md

Each file maps directly to a URL: src/content/docs/inventorix/reference/faq.md → /inventorix/reference/faq/.

---

Adding a page

1. Create a .md file in the appropriate folder.
2. Add frontmatter:

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

The sidebar.order integer controls the page’s position within its folder. Starlight picks up new files automatically — no sidebar config change needed.

---

House style

Follow the conventions in the authoring style guide (.superpowers/sdd/authoring-style.md in the repo root):

• Voice: clear, direct, second person (“you”), active voice.
• No marketing language. Every sentence should help the reader do something.
• Links: use absolute site paths starting with the product namespace, e.g. /inventorix/admin/operations/. Never use root-relative /admin/... paths. Never link to a page that does not exist yet.
• Callouts: use Starlight asides — :::note, :::tip, :::caution, :::danger.
• Tables: prefer tables for reference data (env vars, command options).
• Code blocks: always include a language identifier (```bash, ```yaml, ```ini).
• No screenshots — none are available for this project.
• Reference pages (this section): terse, table-first, minimal prose.
• Admin pages: thorough, with real commands and examples.
• User pages: task-focused walkthroughs.

---

Submitting changes

1. Create a branch.
2. Write or edit content.
3. Run npm run build and confirm it passes (zero broken internal links).
4. Open a pull request against main.