# github-pages-frontmatter-required

> Fix MkDocs navigation YAML errors by adding frontmatter with title to all index.md files

- Author: Andrew Holder
- Repository: drewswiredin/vincent-chappie
- Version: 20260209202943
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-10
- Source: https://github.com/drewswiredin/vincent-chappie
- Web: https://mule.run/skillshub/@@drewswiredin/vincent-chappie~github-pages-frontmatter-required:20260209202943

---

---
name: github-pages-frontmatter-required
description: Fix MkDocs navigation YAML errors by adding frontmatter with title to all index.md files
domain: GitHub
user-invocable: false
allowed-tools: Read, Edit, Grep, Glob
---

# GitHub Pages Frontmatter Required

Navigation generation fails with YAML parsing error if index.md files lack frontmatter with title field.

## The Problem

Navigation generation creates invalid YAML:
```
ERROR: expected <block end>, but found ':'
  in mkdocs.yml, line 89, column 13
```

Navigation entry looks like:
```yaml
- : docs/work/roadmaps/archive/index.md
```

Empty key (before colon) breaks YAML parsing.

## Root Cause

Navigation generators extract titles from frontmatter `title:` field. Files without this field return empty string, creating malformed YAML entry.

## Solution

All index.md files must have frontmatter:

```markdown
---
title: Page Title
---

# Page Title

Content here...
```

## Common Culprits

- Archive index files (`docs/work/roadmaps/archive/index.md`)
- Auto-generated placeholder files
- Template files copied without frontmatter
- README files converted to index.md

## Fix Existing Files

```bash
# Find index.md files without frontmatter
find docs -name "index.md" -exec grep -L "^---$" {} \;

# Add frontmatter to each
```

## Navigation Generator Pattern

Typical title extraction:
```bash
title=$(awk '/^title:/ {gsub(/^title: /, ""); print; exit}' "$file")
```

Returns empty if no `title:` field exists.

## Gotcha

Even if the file has `# Title` heading, frontmatter is required for navigation generation. The heading alone is not extracted.