Contributing to the Docs

This page explains how to contribute to this documentation site. The site is built with Astro Starlight and lives in the noix-docs repository.

Prerequisites

• Node 22 or later (enforced by the engines field in package.json).
• Familiarity with Markdown and basic Git.

Local development

# Install dependencies
npm install

# Start the Astro dev server (live reload)
npm run dev

# Build for production
npm run build

# Type-check MDX and Astro components
npm run check

The dev server starts at http://localhost:4321 by default. Changes to Markdown files are reflected immediately without a restart.

Repository layout

Marketix content lives under src/content/docs/marketix/:

src/content/docs/marketix/
├── admin/
│   ├── installation/         # requirements, docker, environment, first-run
│   ├── configuration/        # mailer, storage, branding
│   ├── introduction.md
│   ├── operations.md
│   ├── security.md
│   └── user-and-project-management.md
├── user/
│   ├── getting-started.md
│   ├── projects.md
│   ├── links.md
│   ├── domains.md
│   ├── qr-codes.md
│   ├── pixels.md
│   ├── statistics-reports.md
│   ├── team.md
│   └── account.md
└── reference/
    ├── environment-variables.md
    ├── cli-commands.md
    ├── faq.md
    ├── contributing-docs.md   # this page
    └── changelog.md

Each folder maps to a section in Marketix’s scoped sidebar, which is generated automatically — you do not need to register new files anywhere.

Adding a page

1. Create a .md file in the correct folder under src/content/docs/marketix/{admin,user,reference}/.
2. Add the required frontmatter (see below).
3. Write the content following the house style.
4. Run npm run build locally to confirm no broken links are introduced.

Frontmatter

Every page requires:

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

sidebar.order controls the position of the page within its folder. Use the next integer in the existing sequence.

House style

• Voice: Second person (“you”), active voice, no marketing language.
• Headings: Start body headings at ##. The page title becomes the <h1> automatically — do not add a top-level # heading.
• Code blocks: Always specify a language. Use ```bash for shell commands, ```yaml for YAML, ```ini for .env / KEY=value blocks. Do not use ```env — Expressive Code has no env highlighter and the build emits a warning.
• Asides / callouts: Use Starlight’s built-in aside syntax:

:::note
Informational callout.
:::

:::tip
Helpful suggestion.
:::

:::caution
Something to be careful about.
:::

:::danger
Destructive or irreversible action warning.
:::

• Tables: Prefer Markdown tables for reference content (env vars, options, commands).
• Internal links: Use absolute paths within the /marketix/ namespace, for example:

[Environment Variables](/marketix/reference/environment-variables/)
[Docker deployment](/marketix/admin/installation/docker/)

Never use root-relative /admin/... paths. Never link to a page that does not exist.

Link integrity

The build runs starlight-links-validator. Any broken internal link causes the build to fail. Before opening a pull request:

1. Run npm run build locally.
2. Verify the output shows 0 broken links.

If you are not sure whether a target page exists yet, reference the section in prose rather than adding a link.

Submitting changes

Open a pull request against the main branch of noix-docs. The CI pipeline runs npm run build (which includes the link validator) on every pull request.