Contributing to the Docs

The S3 Manager documentation lives in the noix-docs repository alongside docs for other NoiX products. This page covers everything you need to contribute.

Prerequisites and setup

Requirement	Version
Node.js	22 or newer
npm	bundled with Node.js

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

Development

npm run dev

Starts the Astro dev server with live reload. Open http://localhost:4321 in a browser.

Build and validate

npm run build

Produces a production build in dist/. The build runs starlight-links-validator; broken internal links fail the build. Always run a build before opening a pull request.

npm run check

Runs astro check for TypeScript and Astro component errors. Expect zero errors and zero warnings.

Content structure

S3 Manager docs live under src/content/docs/s3manager/:

src/content/docs/s3manager/
├── getting-started/   # Installation, introduction, first connection, updating
├── guide/             # Feature walkthroughs (one page per feature)
└── reference/         # This section — terse reference pages

Each .md file in those directories is automatically picked up by the scoped sidebar. You do not need to register pages anywhere — adding a file to the right folder is enough.

Frontmatter (required on every page)

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

sidebar.order controls ordering within the folder. Use integers that leave gaps (e.g. 1, 2, 3) so new pages can be inserted without renumbering.

House style

• Voice: second person (“you”), active voice, no marketing language.
• Links: use absolute site paths — /s3manager/guide/cors-editor/ not ../cors-editor. Never link to a page that does not exist; broken links fail the build.
• Code blocks: use a language specifier. Use ```bash for shell commands, ```ini for KEY=value config blocks (not ```env — the build emits a warning for unknown languages).
• Callouts: use Starlight asides — :::note, :::tip, :::caution, :::danger — not blockquotes.
• Tables: prefer Markdown tables for options, settings, and comparisons.
• Reference pages: terse, table-first, minimal prose.
• Guide pages: task-focused walkthroughs, enough detail to complete the task.

Adding a page

1. Create a .md file in the appropriate folder (getting-started/, guide/, or reference/).
2. Add the required frontmatter (title, description, sidebar.order).
3. Write the content following the house style above.
4. Run npm run build to confirm no broken links and no build errors.
5. Open a pull request against main.