# YAML Frontmatter Standards for Documentation

This document defines the YAML frontmatter standards for AO documentation to ensure consistency and enable advanced MkDocs features.

## Required vs Optional Keys

### Required Keys (all pages)

```yaml
---
title: "Page Title"           # Explicit title, shown in sidebar/tabs
description: "Brief summary"  # For social cards and SEO meta tags
---
```

### Recommended Keys (when applicable)

```yaml
---
status: new                   # Page status: new, deprecated
icon: material/file-document  # Navigation icon
---
```

### Optional Keys

```yaml
---
subtitle: "Additional context"  # Rendered below title in sidebar
template: custom.html           # Custom page template
hide:
  - navigation                  # Hide navigation
  - toc                         # Hide table of contents
  - footer                      # Hide footer
---
```

## Key Definitions

### title

**Purpose**: Explicit page title for navigation, social cards, and browser tabs.

**Rules**:
- Should match or be similar to the H1 heading
- Keep under 60 characters for SEO
- Use sentence case: "Getting started" not "Getting Started"

**Example**:
```yaml
title: "Getting started with AO"
```

### description

**Purpose**: Page summary for social cards, search results, and SEO meta tags.

**Rules**:
- 150-160 characters maximum
- Should describe what the page covers
- Use active voice

**Example**:
```yaml
description: "Learn how to set up AO in your project and complete your first workflow using constitution and baseline."
```

### status

**Purpose**: Visual indicator in navigation for page state.

**Values**:
- `new` - Recently added content
- `deprecated` - Content being phased out

**Example**:
```yaml
status: new
```

### icon

**Purpose**: Visual icon displayed in navigation sidebar and tabs.

**Format**: Use Material Design Icons notation: `material/icon-name`

**Example**:
```yaml
icon: material/rocket-launch
```

## Page Type Templates

### Concept Page

```yaml
---
title: "Constitution"
description: "The constitution is your project's authority document—it defines what the agent can and cannot do."
icon: material/file-document-outline
---
```

### Tutorial/Guide Page

```yaml
---
title: "Quick start"
description: "Get up and running with AO in under 5 minutes with this step-by-step guide."
icon: material/play-circle-outline
---
```

### Reference Page

```yaml
---
title: "CLI commands reference"
description: "Complete reference for all AO CLI commands, options, and examples."
icon: material/console
---
```

### New Feature Page

```yaml
---
title: "Scheduler command"
description: "Schedule and manage automated task execution with the new aoc scheduler command."
status: new
icon: material/clock-outline
---
```

## Enforcement Mechanism

### Option A: CI Validation (Recommended)

Add a validation step to CI that checks all docs have required frontmatter:

```bash
# .github/workflows/docs.yml
- name: Validate frontmatter
  run: |
    python scripts/validate_frontmatter.py docs/
```

Validation script checks:
1. All `.md` files in `docs/` have frontmatter
2. Required keys (`title`, `description`) are present
3. `title` is under 60 characters
4. `description` is under 160 characters

### Option B: Pre-commit Hook

```yaml
# .pre-commit-config.yaml
- repo: local
  hooks:
    - id: validate-frontmatter
      name: Validate docs frontmatter
      entry: python scripts/validate_frontmatter.py
      language: python
      files: ^docs/.*\.md$
```

### Option C: MkDocs Plugin (meta plugin)

Material for MkDocs has a `meta` plugin that can enforce defaults:

```yaml
# mkdocs.yml
plugins:
  - meta:
      meta_file: '**/.meta.yml'
```

Create `.meta.yml` in docs folders to set defaults for all pages.

## Migration Plan

### Phase 1: Add frontmatter to new pages (immediate)

All new documentation must include required frontmatter.

### Phase 2: Backfill existing pages (1 week)

Update existing pages in priority order:
1. `docs/index.md`
2. `docs/getting-started/*.md`
3. `docs/concepts/*.md`
4. `docs/skills/*.md`
5. `docs/cli/*.md`
6. `docs/languages/*.md`
7. `docs/deployment/*.md`

### Phase 3: Enable CI enforcement (after backfill)

Turn on CI validation after all pages have required frontmatter.

## Example Migration

**Before** (`docs/concepts/constitution.md`):
```markdown
# Constitution

The constitution is your project's authority document...
```

**After**:
```yaml
---
title: "Constitution"
description: "The constitution is your project's authority document—it defines what the agent can and cannot do."
icon: material/file-document-outline
---

# Constitution

The constitution is your project's authority document...
```

## References

- [MkDocs Material: Setting page title](https://squidfunk.github.io/mkdocs-material/reference/#setting-the-page-title)
- [MkDocs Material: Setting page description](https://squidfunk.github.io/mkdocs-material/reference/#setting-the-page-description)
- [MkDocs Material: Setting page status](https://squidfunk.github.io/mkdocs-material/reference/#setting-the-page-status)
- [MkDocs: Meta-Data](https://www.mkdocs.org/user-guide/writing-your-docs/#meta-data)
