Page Structure

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

File Types

File Naming

• All lowercase.
• Use hyphens between words: create-an-asset.mdx, not Create An Asset.mdx.
• Folder landing pages must be named index.mdx.
• The file path determines the URL: pages/mkio/how-to/stream-content.mdx → /mkio/how-to/stream-content.

Frontmatter

Every page must start with YAML frontmatter:

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

• title — appears in the browser tab and sidebar (if not overridden by _meta.json).
• description — used by search engines and social previews.

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 ####).

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 labels and order are controlled by _meta.json inside each folder.
• Add a key to _meta.json whenever you create a new page, and remove it when you delete one.
• Do not change sidebar order without checking with the docs maintainer.

Example _meta.json:

{
  "getting-started": "Getting Started",
  "how-to": "How-To Guides",
  "reference": "Reference"
}