"""Shared MkDocs Material snippet templates and frontmatter helpers."""

from __future__ import annotations


DEFAULT_FRONTMATTER_KEYS: tuple[str, ...] = ("title", "description")
OPTIONAL_FRONTMATTER_KEYS: tuple[str, ...] = ("icon", "status", "subtitle", "template")
DEFAULT_SECTIONS: tuple[str, ...] = ("Overview", "Usage", "Examples")

__all__ = [
    "DEFAULT_FRONTMATTER_KEYS",
    "DEFAULT_SECTIONS",
    "MATERIAL_SNIPPETS",
    "OPTIONAL_FRONTMATTER_KEYS",
    "render_frontmatter",
]

MATERIAL_SNIPPETS: dict[str, str] = {
    "frontmatter": """---
title: Page title
description: Short summary for SEO/social cards.
icon: material/book-open-page-variant
status: new
subtitle: Optional context
---
""",
    "admonition": """!!! note
    This is a Material-compatible admonition.
""",
    "tabs": """=== "Python"
    ```python
    print("hello")
    ```

=== "Bash"
    ```bash
    echo "hello"
    ```
""",
    "highlight": """```python hl_lines="2"
def add(a, b):
    return a + b
```
""",
}


def render_frontmatter(title: str, description: str = "") -> str:
    """Render a standard MkDocs Material frontmatter block.

    Args:
        title: Page title to place in frontmatter.
        description: Optional summary text. Falls back to a generated sentence.

    Returns:
        YAML frontmatter string compatible with MkDocs Material pages.
    """
    summary = description or f"{title} page generated by mcp-zen-of-docs."
    return (
        "---\n"
        f"title: {title}\n"
        f"description: {summary}\n"
        "icon: material/file-document-outline\n"
        "status: new\n"
        "---\n"
    )
