Page Structure

This page explains how to structure documentation pages, pick the right content type, and use frontmatter.

File Location

All documentation pages live inside src/content/docs/. The folder structure maps directly to URLs:

File path	URL
src/content/docs/mkio/getting-started.md	/mkio/getting-started
src/content/docs/beam/live-encoder/index.md	/beam/live-encoder
src/content/docs/api-guides/authentication.mdx	/api-guides/authentication

API reference pages are a special case — they live in src/pages/api-reference/ and are not content files. See How to Contribute.

---

File Types

Extension	When to use
.md	Plain markdown — no React components needed
.mdx	When you need custom components (Cards, Callouts, Tabs, Tooltips, etc.)

If in doubt, use .md. You can rename to .mdx later if you need components.

---

File Naming

• All lowercase.
• Use hyphens between words: create-an-asset.md, not CreateAnAsset.md.
• Folder landing pages must be named index.md (or index.mdx).
• The file path determines the URL: there is no separate routing config.

---

Frontmatter

Every page must start with YAML frontmatter:

---
title: Clear page title
description: One-sentence summary of what the page helps the reader do.
---

Required fields

• title — appears in the browser tab, breadcrumbs, sidebar, and search results.
• description — used by search engines, social previews, and the LLM-friendly text output.

Sidebar fields

---
title: My Page
sidebar:
  order: 3               # controls sort position within the folder (lower = higher)
  label: Custom Label    # optional — overrides title in the sidebar only
---

• sidebar.order — a number controlling sort position within the same folder. Pages without an order appear after ordered pages, sorted alphabetically.
• sidebar.label — optional. Useful when the page title is too long for the sidebar. If not set, the sidebar shows title.

Optional LLM fields

These fields affect what appears in /llms.txt and /llms-full.txt:

---
llm_ignore: true       # exclude this page from all LLM output (e.g. internal-only pages)
llm_optional: true     # include in llms-full.txt but not in the default llms.txt index
llm_priority: high     # 'high' | 'normal' (default) | 'low' — affects ordering in llms.txt
---

---

Images and Static Assets

Place images and other static files in the public/ folder at the project root. They are served at the root URL path:

File path	URL
public/mkio-getting-started.png	/mkio-getting-started.png
public/beam/encoder-diagram.png	/beam/encoder-diagram.png

Reference them in Markdown or MDX with a root-relative path:

![Alt text](/mkio-getting-started.png)

or as an HTML image (useful when you need to control width):

<img src="/mkio-getting-started.png" alt="Alt text" width="600" />

Filename length limit — important

Keep filenames under 100 characters (including the leading /). The site build enforces a hard 100-character limit per routing rule. Every file in public/ automatically becomes a routing rule, so a long filename breaks the build with a cryptic _routes.json error.

Tools that generate long names by default:

Tool	What it produces	What to do
Figma export	Component_Name--Variant_2025-11-10.png	Rename before saving
macOS screenshot	Screenshot 2025-11-10 at 13.09.55.png	Rename before saving
Notion export	Untitled Database abc123de.png	Rename before saving
Hash-prefixed CDN	34663418de2cc3cf...filename.png	Rename — strip the hash prefix

Naming convention

• All lowercase, hyphens between words: encoding-jobs-overview.png
• Be descriptive enough to identify the content: mkio-asset-list-view.png not screenshot1.png
• Match the page topic in the name so it stays findable: beam-encoder-hardware-requirements.png

---

Heading Hierarchy

• Use exactly one # (H1) per page — this should match your title.
• Use ## (H2) for major sections.
• Use ### (H3) for sub-sections.
• Do not skip levels (e.g. do not jump from ## to ####).

The site automatically strips the H1 heading when it matches the frontmatter title to avoid duplication in the rendered output. You still need the H1 in the file — it is used as the fallback title in some contexts.

---

Page Template (Copy/Paste)

---
title: Clear page title
description: One-sentence summary.
---

# Clear page title

Short intro paragraph explaining what this page covers and who it is for.

## Prerequisites

- Requirement 1
- Requirement 2

## Steps

1. First action.
2. Second action.
3. Third action.

## Verify

- Expected result 1
- Expected result 2

---

Content Types

Choose the type that best matches the purpose of your page.

How-to

• Helps the reader complete a specific task.
• Title uses an imperative verb: “Create an asset”, “Configure a transform”.
• Structure: intro → (optional prerequisites) → numbered steps → expected result.

Overview / Concept

• Explains what something is and why it matters.
• Title uses a noun phrase: “Streaming endpoints”, “Asset filters”.
• Structure: intro → key concepts → (optional diagram or table) → related links.

Reference

• Factual, structured information (API fields, presets, configuration options).
• Title uses a noun phrase: “Encoding transform presets”.
• Structure: intro → table or definition list → examples.

Getting Started

• End-to-end onboarding guide for first-time users.
• Structure: intro → prerequisites → ordered steps covering the full workflow → next steps.

---

Sidebar Navigation

Sidebar position is controlled by sidebar.order in frontmatter. Lower numbers appear higher in the list.

---
title: My Page
sidebar:
  order: 3
  label: Custom sidebar label   # optional — overrides title in the sidebar
---

There is no _meta.json. The old Nextra-based site used _meta.json files in each folder to define sidebar order and labels. The Astro site uses frontmatter only.

Example: three pages in getting-started/ sorted 1 → 2 → 3:

# account-setup.md
sidebar:
  order: 1

# video-workflows.md
sidebar:
  order: 2

# navigation-features.md
sidebar:
  order: 3

Folders inherit their sort position from the lowest sidebar.order value of their children, so you usually don’t need to set order on folder index files unless you want to pin the folder to a specific position.

Do not change order values without checking with the docs maintainer — it affects navigation for all readers.