Documentation Site Example

This guide shows how to set up a complete documentation site with md0 CMS, including multiple sections, hierarchical navigation, and versioning.

Documentation Structure

Recommended Structure

my-docs/
├── docs/
│   ├── getting-started/
│   │   ├── introduction.md
│   │   ├── installation.md
│   │   └── quick-start.md
│   ├── guides/
│   │   ├── basic-usage.md
│   │   └── advanced-features.md
│   ├── api/
│   │   ├── authentication.md
│   │   └── endpoints.md
│   └── examples/
│       ├── example-1.md
│       └── example-2.md
└── public/
    └── images/
        └── docs/

Why This Structure?

• Section-based: Clear organization by topic
• Hierarchical: Easy navigation structure
• Scalable: Add new sections easily
• SEO-friendly: Clean URLs

Setup

Step 1: Create Collections

Option 1: Single Collection

Name: Documentation
Path: docs/**/*.md
Description: All documentation pages

Option 2: Multiple Collections (Recommended)

# Getting Started
Name: Getting Started
Path: docs/getting-started/**/*.md
Description: Introduction and setup guides

# Guides
Name: Guides
Path: docs/guides/**/*.md
Description: Usage guides and tutorials

# API Reference
Name: API Reference
Path: docs/api/**/*.md
Description: API documentation

# Examples
Name: Examples
Path: docs/examples/**/*.md
Description: Code examples and samples

Step 2: Define Documentation Schema

fields:
  - name: title
    type: string
    required: true
    placeholder: "Page title"

  - name: description
    type: text
    required: true
    maxLength: 300
    placeholder: "Brief description for SEO"

  - name: category
    type: select
    required: true
    options:
      - Getting Started
      - Guides
      - API Reference
      - Examples

  - name: order
    type: number
    default: 0
    description: "Order in navigation (lower = higher)"

  - name: last_updated
    type: date
    default: now

  - name: contributors
    type: array
    items: string
    description: "GitHub usernames"

  - name: difficulty
    type: select
    options:
      - Beginner
      - Intermediate
      - Advanced

  - name: related_pages
    type: array
    items: string
    description: "Slugs of related pages"

  - name: prerequisites
    type: array
    items: string
    description: "Required knowledge or setup"

  - name: version
    type: string
    description: "Version this applies to (e.g., 'v2.0+')"

  - name: deprecated
    type: boolean
    default: false

  - name: sidebar_label
    type: string
    description: "Short label for sidebar (defaults to title)"

Creating Documentation

Getting Started Page

---
title: "Introduction to md0 CMS"
description: "Learn what md0 CMS is and how it can help you manage content in GitHub."
category: "Getting Started"
order: 1
difficulty: "Beginner"
last_updated: 2024-01-15
---

# Introduction to md0 CMS

md0 CMS is a GitHub-native content management system that provides a visual interface for managing markdown files.

## What is md0 CMS?

md0 CMS allows you to:

- Edit markdown files visually
- Manage frontmatter with forms
- Organize content into collections
- Sync automatically with GitHub

## Who is it for?

- Developers managing markdown content
- Technical writers creating documentation
- Teams collaborating on content
- Anyone using static site generators

## Next Steps

- [Installation](/docs/getting-started/installation)
- [Quick Start Guide](/docs/getting-started/quick-start)

Guide Page

---
title: "Creating Collections"
description: "Learn how to create and configure collections to organize your content."
category: "Guides"
order: 10
difficulty: "Beginner"
prerequisites:
  - "GitHub repository connected"
  - "Basic understanding of glob patterns"
related_pages:
  - "define-schema"
  - "collection-patterns"
last_updated: 2024-01-15
---

# Creating Collections

Collections organize your content by type or category.

## What is a Collection?

A collection is a group of content files that:

- Share the same frontmatter schema
- Live in a specific path pattern
- Represent the same content type

## Creating Your First Collection

1. Click "Collections" in sidebar
2. Click "Create Collection"
3. Fill in details:

...

API Reference Page

---
title: "Authentication"
description: "API authentication methods and best practices."
category: "API Reference"
order: 1
difficulty: "Intermediate"
version: "v2.0+"
last_updated: 2024-01-15
---

# Authentication

md0 CMS uses OAuth 2.0 for authentication.

## OAuth Flow

1. Redirect user to GitHub
2. User authorizes app
3. GitHub redirects back with code
4. Exchange code for token

## Code Example

\`\`\`javascript
const authUrl = `https://github.com/login/oauth/authorize?client_id=${clientId}`
window.location.href = authUrl
\`\`\`

## Best Practices

- Store tokens securely
- Refresh tokens before expiry
- Handle authorization errors

## See Also

- [GitHub OAuth Documentation](https://docs.github.com/oauth)

Navigation Structure

Sidebar Configuration

Most docs frameworks support sidebar config. Map md0 CMS frontmatter to sidebar:

// Example for Next.js
const sidebar = [
  {
    title: "Getting Started",
    items: docs
      .filter((doc) => doc.category === "Getting Started")
      .sort((a, b) => a.order - b.order)
      .map((doc) => ({
        title: doc.sidebar_label || doc.title,
        href: `/docs/${doc.slug}`,
      })),
  },
  {
    title: "Guides",
    items: docs
      .filter((doc) => doc.category === "Guides")
      .sort((a, b) => a.order - b.order)
      .map((doc) => ({
        title: doc.sidebar_label || doc.title,
        href: `/docs/${doc.slug}`,
      })),
  },
];

Breadcrumbs

Use category and title for breadcrumbs:

Home > Getting Started > Introduction
Home > API Reference > Authentication

Previous/Next Links

Sort by order within category:

const currentIndex = docs.findIndex((doc) => doc.slug === currentSlug);
const prev = docs[currentIndex - 1];
const next = docs[currentIndex + 1];

Advanced Features

Search

Enable search with frontmatter:

- name: keywords
  type: array
  items: string
  description: "Search keywords"

- name: search_boost
  type: number
  default: 1
  description: "Search result priority"

Versioning

Handle multiple versions:

Option 1: Separate folders

docs/
├── v1/
├── v2/
└── v3/

Option 2: Version frontmatter

version: "v2.0+"

Filter by version in your docs site.

Code Tabs

Use frontmatter for language-specific content:

- name: code_examples
  type: array
  items: object
  fields:
    - name: language
      type: string
    - name: code
      type: text

Table of Contents

Auto-generate from headings:

- name: toc_max_depth
  type: number
  default: 3
  description: "Maximum heading depth in TOC"

- name: hide_toc
  type: boolean
  default: false

Feedback

Track page feedback:

- name: feedback_enabled
  type: boolean
  default: true

- name: feedback_prompt
  type: string
  default: "Was this page helpful?"

Multi-Language Docs

Structure

docs/
├── en/
│   ├── getting-started/
│   └── guides/
└── es/
    ├── getting-started/
    └── guides/

Schema

- name: locale
  type: select
  required: true
  options:
    - en
    - es
    - fr
    - de

- name: translated_from
  type: string
  description: "Original page slug"

- name: translation_status
  type: select
  options:
    - Complete
    - In Progress
    - Needs Update

Collaboration Features

Contributors

- name: author
  type: string
  required: true
  description: "Primary author"

- name: contributors
  type: array
  items: string
  description: "Additional contributors"

- name: reviewer
  type: string
  description: "Technical reviewer"

Review Status

- name: review_status
  type: select
  default: "Draft"
  options:
    - Draft
    - In Review
    - Approved
    - Published

- name: review_notes
  type: text
  description: "Notes for reviewers"

Best Practices

Writing Guidelines

Clear titles:

title: "Creating Collections"  # Good
title: "Collections"           # Less clear

Descriptive slugs:

docs/getting-started/installation  # Good
docs/install                       # Less clear

Complete descriptions:

description: "Learn how to install md0 CMS on macOS, Windows, and Linux."

Content Organization

Logical order:

# Getting Started
1. Introduction (order: 1)
2. Installation (order: 2)
3. Quick Start (order: 3)

# Guides
10. Basic Usage (order: 10)
20. Advanced Features (order: 20)

Related pages:

related_pages:
  - "collection-patterns"
  - "schema-configuration"

SEO

• Write unique descriptions (don't duplicate content)
• Use keywords naturally in title and description
• Add alt text to all images
• Use proper heading hierarchy

Integration Examples

Docusaurus

// docusaurus.config.js
module.exports = {
  presets: [
    [
      "@docusaurus/preset-classic",
      {
        docs: {
          path: "docs",
          routeBasePath: "docs",
          sidebarPath: require.resolve("./sidebars.js"),
        },
      },
    ],
  ],
};

VitePress

// .vitepress/config.js
export default {
  themeConfig: {
    sidebar: [
      {
        text: "Getting Started",
        items: [
          { text: "Introduction", link: "/getting-started/introduction" },
          { text: "Installation", link: "/getting-started/installation" },
        ],
      },
    ],
  },
};

Next.js

See Next.js Integration for complete example.

Troubleshooting

Sidebar Not Updating

Check:

1. Order values are set
2. Category matches exactly
3. Sidebar generation logic is correct
4. Cache is cleared

Search Not Working

Check:

1. Keywords are added to frontmatter
2. Search index is rebuilding
3. Content is being indexed correctly

Next Steps

• Define Schemas for documentation
• Collection Patterns for organization
• Markdown Editing for writing

Related Examples

• Blog Setup
• Multi-Collection Setup