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)

Navigate to the file in GitHub inside src/content/docs/.
Click the pencil Edit icon (top right of the file view).
Make your changes in the editor.
At the bottom, choose Create a new branch for this commit and name it docs/<short-description>.
Click Propose changes to open a PR.
Add reviewers: relevant team members and the docs maintainer.
A Cloudflare preview link will appear in the PR automatically. Share it with reviewers so they can check the rendered result.
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

Pull the latest main:

git checkout main
git pull origin main

Create a feature branch:

git checkout -b docs/<short-description>

Start the dev server:

pnpm dev

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

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

pnpm build

Commit and push:

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

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 — custom Astro pages using Scalar
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:

In the folder’s landing page (index.md), configure sidebar.order in frontmatter.
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):

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',
}

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 section is powered by Scalar and OpenAPI specs. Adding a new API requires four steps:

Step 1: Obtain or configure the OpenAPI spec file. You can choose one of two options:

Option A (Static spec): Place the OpenAPI JSON file directly under public/openapi/:
```
public/openapi/my-api.json
```

Option B (Live spec fetched during build): If the spec is hosted at a public URL, register it in the prebuild fetch script. Open scripts/fetch-openapi.mjs and append an entry to the SOURCES array:

const SOURCES = [
  // ...existing entries...
  {
    name: "My API",
    url: "https://api.example.com/doc/openapi.json",
    file: "my-api.json", // local output filename created under public/openapi/
  },
];

Step 2: Register it in src/components/api/api-sources.ts:

export const API_SOURCES = [
  { slug: 'media-api',    title: 'Media API',    url: '/openapi/media.json' },
  // ...existing entries...
  { slug: 'my-api',       title: 'My API',        url: '/openapi/my-api.json' },  // add this
] as const

Step 3: Create the Astro page at src/pages/api-reference/my-api.astro. Copy an existing one (e.g. flows-api.astro) and update the slug and title:

---
import { getSourcesForSlug } from '../../components/api/api-sources'
// ...other imports...
const title = 'My API Reference'
const sources = getSourcesForSlug('my-api')
---
<!doctype html>
<!-- rest of layout, identical to other API pages -->

Step 4: Add the reference to the header navigation dropdown. In src/components/nav/SiteHeader.tsx, add an entry to the apiItems array:

const apiItems: DropdownItemProps[] = [
  { title: 'Media API', description: 'Create, manage, and stream media assets.', icon: <Server size={16} />, href: '/api-reference/media-api' },
  // ...existing entries...
  { title: 'My API', description: 'My API endpoints and schemas.', icon: <Server size={16} />, href: '/api-reference/my-api' }, // add this
]

Once merged, the new API will automatically:

Appear in the API reference dropdown in the top header navigation
Appear in the API reference switcher in the sidebar of the API reference pages
Get a full-text stub in llms.txt and llms-full.txt
Be indexed by the site search (via the Scalar UI)
Get a static Markdown summary at /api-reference/my-api.md

The deep-link URL routing, theme sync, and endpoint copy buttons all work automatically through shared components — no extra wiring needed.

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.