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