How to Contribute

This is the practical guide for contributing to docs.mediakind.com. For writing style, see the Style Guide. For page templates and structure, see Page Structure.

All documentation is written in Markdown. The site also supports a set of custom MDX components for callouts, cards, tabs, and more — see the Component Reference.

How Publishing Works

• The repo is hosted on GitHub.
• main is production (docs.mediakind.com). All approved PRs merge here.
• Contributors create a feature branch, make changes, and open a PR into main when changes are ready.
• PRs always require approval before merging.
• A Cloudflare preview URL is automatically built for every PR so reviewers can check the changes in the browser before approving.

Rules

• Never commit directly to main.
• Always branch off the latest main.
• Keep PRs focused — one topic or section per PR where possible.
• If you changed a page URL, add a redirect for the old URL and mention it in the PR description.

Quick Contributions via GitHub UI (Non-Technical)

1. Navigate to the file in GitHub inside src/content/docs/.
2. Click the pencil Edit icon (top right of the file view).
3. Make your changes in the editor.
4. At the bottom, choose Create a new branch for this commit and name it docs/<short-description>.
5. Click Propose changes to open a PR.
6. Add reviewers: relevant team members and the docs maintainer.
7. A Cloudflare preview link will appear in the PR automatically. Share it with reviewers so they can check the rendered result.
8. Once approved, merge. Changes go live within a few minutes.

Standard Workflow (Command Line)

Prerequisites

• Node.js 18.20.8+, 20.3+, or 22+ — download from nodejs.org, LTS version.
• pnpm — npm install -g pnpm

Setup

git clone <repo-url>
cd mk-online-doc
pnpm install

Always use pnpm install, not npm install. Running npm install ignores the lockfile and can resolve different package versions, which can cause build failures.

Making Changes

1. Pull the latest main:

git checkout main
git pull origin main

1. Create a feature branch:

git checkout -b docs/<short-description>

1. Start the dev server:

pnpm dev

The site runs at http://localhost:3000. Changes to content files (.md, .mdx) hot-reload automatically.

1. Make your changes — all doc pages live in src/content/docs/.
2. Before pushing, check for build errors:

pnpm build

1. Commit and push:

git add <files>
git commit -m "docs: <short summary>"
git push -u origin docs/<short-description>

1. Open a PR on GitHub from your branch into main. Add reviewers and share the preview link when it appears.

Site Structure

Concept	Location	Notes
All doc pages	src/content/docs/	Subfolders map to URL sections
URL mapping	File path → URL	src/content/docs/mkio/getting-started.md → /mkio/getting-started
Folder landing page	index.md or index.mdx	Required if you want a clickable section root
Sidebar order	sidebar.order in frontmatter	Lower numbers sort higher; no _meta.json
API reference pages	src/pages/api-reference/	Not content — pages generated from the OpenAPI specs at build time
OpenAPI specs	public/openapi/	Served as static JSON at build time

Adding a New Page

Just create a .md or .mdx file inside the appropriate folder in src/content/docs/. Starlight picks it up automatically and adds it to the sidebar.

src/content/docs/mkio/new-feature.md

This becomes /mkio/new-feature. No config file to update.

Control where it appears in the sidebar with frontmatter:

---
title: New Feature
sidebar:
  order: 5
---

Pages without an order appear after ordered pages, sorted alphabetically.

Note on Custom Sidebar Sorting: This site uses a custom sidebar component override (src/components/overrides/Sidebar.astro). If you are adding a page in a directory that has static custom ordering defined in Sidebar.astro’s deepOrder or topLevelOrder maps, those hardcoded arrays will take priority over your page’s frontmatter sidebar.order.

Adding a New Sub-Section (Folder)

Create a folder inside src/content/docs/<parent>/ and add your files:

src/content/docs/mkio/streaming/
  index.md           # landing page at /mkio/streaming
  live-streaming.md  # /mkio/streaming/live-streaming
  vod-streaming.md   # /mkio/streaming/vod-streaming

No config changes needed. The folder appears automatically as a collapsible group in the sidebar.

To control the folder’s display label and sorting position:

1. In the folder’s landing page (index.md), configure sidebar.order in frontmatter.
2. In the custom sidebar component (src/components/overrides/Sidebar.astro), you can add the folder name and its custom label to the groupLabels configuration map.

Adding a New Root-Level Section

A root-level section is a top-level sidebar group like MK.IO or MK.IO Beam. Adding one requires three steps:

Step 1: Create a directory in src/content/docs/:

src/content/docs/my-new-section/
  index.md
  first-page.md

Step 2: Register it in astro.config.mjs by adding an entry to the sidebar array:

sidebar: [
  { label: 'MK.IO',        autogenerate: { directory: 'mkio' } },
  { label: 'MK.IO Beam',   autogenerate: { directory: 'beam' } },
  { label: 'API Guides',   autogenerate: { directory: 'api-guides' } },
  { label: 'My New Section', autogenerate: { directory: 'my-new-section' } },  // add this
  { label: 'Contributing', autogenerate: { directory: 'docs-contribute' } },
],

The directory value must match the folder name exactly. The label is the sidebar heading.

Step 3: Register the section and define sorting in the custom sidebar component (src/components/overrides/Sidebar.astro):

1. Add the directory name and its human-readable title to the productLabels map:

   const productLabels = {
     mkio: 'MK.IO',
     beam: 'MK.IO Beam',
     'api-guides': 'API Guides',
     'my-new-section': 'My New Section', // add this
     'docs-contribute': 'Contributing',
   }

2. Define the folder sorting order under the topLevelOrder map:

   'my-new-section': {
     __index: 1,
     'first-page': 10,
   }

Adding a New API Reference

The API reference is generated at build time from OpenAPI specs in public/openapi/, configured in src/config/api-sources.mjs. In short: add the spec (raw file or build-time fetch), add one entry to API_SPEC_SOURCES with a product (and optionally a group to nest the API under a collapsible sub-group within that product), and the landing card, pages, schema docs, sidebar, markdown twins, and search records are generated automatically. JSON and YAML files are supported, as are OpenAPI 3.x and Swagger 2.0 documents.

For the full walkthrough — including auto-fetch vs. raw files, sidebar order and title, the product pill, and grouping many specs under one section — see Adding API Specs.

Common Mistakes

• Don’t push to main directly. All changes go through a PR.
• Don’t use _meta.json — that was the old Nextra system. Sidebar order is now sidebar.order in frontmatter.
• Don’t include the file extension in links — use /mkio/getting-started not /mkio/getting-started.md.
• Don’t forget to pull latest main before branching. Stale branches cause merge conflicts.
• Don’t create root-level sections without updating astro.config.mjs. The folder will exist but won’t appear in the sidebar.

Further Reading

• Style Guide — writing tone and formatting rules
• Page Structure — templates and content types
• Component Reference — all available MDX components
• Markdown Reference — quick markdown cheat sheet