Maintainer Guide

How to contribute to and maintain this handbook. Everyone is a maintainer.

The one rule

If someone asked you a question twice, write the answer here.

Everything else in this guide is tactical. That rule is strategic.

Quick start — editing with Obsidian

This handbook is a folder of plain text files. The recommended editor is Obsidian — free, offline, and works directly on the files.

First-time setup

1. Download and install Obsidian (free).
2. Open Obsidian → Open folder as vault → select the gstarlink-handbook folder.
3. That’s it. All pages appear in the left sidebar under pages/.

Obsidian tips

• Files end in .mdx — Obsidian treats them like Markdown.
• Use Live Preview mode (default) for a WYSIWYG-like experience.
• The folder structure in the sidebar mirrors the website navigation.
• Ignore the node_modules/, .next/, and scripts/ folders — Obsidian already hides them.

Previewing changes locally

To see your changes exactly as they appear on the website:

cd gstarlink-handbook
npm install          # first time only
npm run dev          # starts on http://localhost:3000

Open http://localhost:3000 and navigate to your page. Changes save automatically — just refresh the browser.

File structure

Every page in the handbook is an .mdx file inside the pages/ folder:

pages/
├── _meta.ts                    ← top-level navigation order
├── index.mdx                   ← home page
├── company/
│   ├── _meta.ts                ← controls sidebar order for this section
│   ├── index.mdx               ← "Company" section overview
│   ├── mission.mdx
│   └── ...
├── customer-service/
│   ├── _meta.ts
│   ├── sop/
│   │   ├── _meta.ts
│   │   └── ...
│   └── training/
│       └── ...
├── operations/
├── product/
├── tech/
├── marketing/
└── people/

The folder hierarchy becomes the URL:

• pages/customer-service/sop/communication.mdx → /customer-service/sop/communication

Creating a new page

1. Create the file in the right folder. Use lowercase, hyphen-separated filenames:

   pages/customer-service/sop/my-new-topic.mdx

2. Add frontmatter at the very top of the file:

   ---
   title: 'My New Topic'
   public: false
   last_updated: 2026-04-23
   owner: Your Name
   ---
    
   # My New Topic
    
   Content starts here.

3. Add it to _meta.ts in the same folder to control where it appears in the sidebar (see below).

Controlling sidebar order — _meta.ts

Each folder has a _meta.ts file that sets the sidebar title and order for pages in that folder.

export default {
  "index": "Overview",
  "communication": "Communication",
  "order-fulfilment": "Order fulfilment",
  "my-new-topic": "My New Topic",   // ← add your page here
}

• The key matches the filename (without .mdx).
• The value is the title shown in the sidebar.
• Pages not listed appear at the bottom in alphabetical order.

Frontmatter reference

Every .mdx file must start with a YAML frontmatter block:

---
title: 'Page Title'          # required — shown in browser tab and sidebar
public: false                # required — see below
last_updated: 2026-04-23     # update this whenever you edit the page
owner: Ray                   # the person accountable for accuracy
---

public: false vs public: true

When in doubt → use public: false. It is always easier to open a page up later than to remove it from Google’s index.

Never mark public: true if the page contains:

• Costs, margins, or supplier pricing
• Passwords, API keys, or credentials
• Internal strategy, org charts, or individual performance

MDX writing rules

MDX is Markdown with JSX support. It is stricter than regular Markdown — broken syntax causes the whole page to fail with an error. Follow these rules:

✅ Standard Markdown — always works

# Heading 1
## Heading 2
 
**bold**, *italic*, `inline code`
 
- bullet list
- another item
 
1. numbered list
2. another item
 
[Link text](https://example.com)
 
> Blockquote text

⚠️ HTML tags — must be self-closing void elements

Void HTML elements (<br>, <hr>, <img>) must include the closing slash:

<!-- ❌ Wrong — will crash the page -->
<br>
<img src="..." alt="...">
 
<!-- ✅ Correct -->
<br />
<img src="..." alt="..." />

⚠️ < before numbers — must be escaped

A bare < followed by a number is misread as a JSX tag:

<!-- ❌ Wrong — will crash the page -->
Response time is <24 hours.
Price is <500 AUD.
 
<!-- ✅ Correct — use the HTML entity -->
Response time is &lt;24 hours.
Price is &lt;500 AUD.

⚠️ No style="..." string attributes

Inline styles must be written as a JavaScript object, not a string:

<!-- ❌ Wrong -->
<div style="color: red">...</div>
 
<!-- ✅ Correct -->
<div style={{ color: 'red' }}>...</div>

⚠️ Images — use standard Markdown syntax

Always use Markdown image syntax, not HTML:

<!-- ✅ Correct -->
![Alt text](https://example.com/image.png)
 
<!-- ❌ Avoid unless necessary -->
<img src="https://example.com/image.png" alt="Alt text" />

Do not reference local GitBook asset paths (.gitbook/assets/...) — those images don’t exist in this repository.

Creating a new section (folder)

To add a whole new section (e.g. pages/finance/):

1. Create the folder and an index.mdx inside it.
2. Create a _meta.ts inside it listing all pages.
3. Add the section to the parent _meta.ts:

// pages/_meta.ts
export default {
  "company": "Company",
  "operations": "Operations",
  "finance": "Finance",   // ← new section
  ...
}

Writing style

• Write for the person joining next month — not for the person who already knows.
• Decisions get a reason. “We use X because Y.” Not just “We use X.”
• Sentences over bullets when you are explaining reasoning. Bullets lose context.
• Update last_updated when you change a page. Stale pages get removed in quarterly reviews.
• Owner is a person, not a team. When ownership changes, update the field.

Deprecating a page

Don’t delete pages immediately — they are evidence of what we used to think.

1. Add deprecated: true to the frontmatter.
2. Add a notice at the top of the page:

   > **Deprecated.** This page is outdated. See [New Page](/path/to/new) instead.
3. Leave it for 90 days. If no one objects, delete it.

The two-question test

Before you save any change, ask:

1. Will someone find this when they search for it? If not, fix the title or placement.
2. Will this still be true in three months? If not, add dates, owners, and conditions.