Documentation Page Front Matter

Documentation Page Front Matter

This skill guides writing YAML front matter for mkdocs-material documentation pages. Front matter controls social card generation and page metadata.

Front Matter Format

---
title: "Page Title"
description: "Brief description of the page."
---

Title Guidelines

• Use descriptive titles that provide context
• Include the subject matter (e.g., "LanceDB Configuration" not just "Configuration")
• Keep titles concise but informative
• For API reference pages: "[Subject] API" or "API reference for [Subject]"
• For configuration pages: "[Subject] Configuration"
• For index pages: Use the section name (e.g., "Integrations", "User Guide")

Description Guidelines

DO:

• Briefly summarize what the page covers
• Keep descriptions general and conceptual
• Use simple, direct language
• Focus on the page content, not the subject itself

DON'T:

• Enumerate specific implementation details that may become outdated
• List specific technologies, databases, or tools unless the page is specifically about one
• Prescribe use cases (avoid "for local development", "ideal for production", etc.)
• Use verbose explanations
• Describe what the subject does (describe the page instead)

Examples

Good Descriptions

# API reference page
description: "API reference for DuckDBMetadataStore."

# Configuration page
description: "Configuration options for ClickHouseMetadataStore."

# Concept page
description: "How Metaxy calculates and tracks versions."

# Index page
description: "Available metadata store backends for Metaxy."

# Integration overview
description: "Dagster integration for Metaxy."

# Guide page
description: "Defining dependencies between features."

Bad Descriptions (Avoid These)

# Too verbose, lists specific details
description: "Connect Metaxy with orchestrators like Dagster, databases like ClickHouse and BigQuery, and plugins for SQLModel and SQLAlchemy."

# Prescribes use case
description: "Use DuckDB as a fast embedded analytical database for local development and testing with Metaxy."

# Enumerates implementation details
description: "Configuration options for DuckDBMetadataStore including database path, extensions, and DuckLake settings."

# Describes the subject, not the page
description: "A pluggable metadata layer for ML pipelines that tracks feature versions, dependencies, and data lineage."

Patterns by Page Type

Checklist

Before finalizing front matter, verify:

• Title provides enough context to be meaningful in isolation
• Description is one sentence or less
• Description describes the page, not the subject
• No specific implementation details that could become outdated
• No prescriptive language about use cases
• Consistent with patterns used across the documentation