Links

View on PyPI

AI / Agents

Skills
llms.txt
llms-full.txt

Meta

Requires: Python >=3.12
Package Info

gdtest-type-aliases

A synthetic test package whose public API is mostly PEP 695 type aliases.

A package whose public API is mostly PEP 695 type X = ... aliases: generic, bounded, constrained, variadic, ParamSpec, recursive, and a long Literal. On the Reference page you should see a ‘Type Aliases’ section listing them, each signature rendered in its source form with the type keyword. The Ledger class declares an alias in its own body, which should appear under its own ‘Type Aliases’ heading rather than being dropped. Requires Python 3.12+.

Source files

📁 gdtest_type_aliases/

📄 __init__.py

"""A test package whose public API is mostly PEP 695 type aliases."""

__version__ = "0.1.0"
__all__ = [
    "Clause",
    "ContractId",
    "Jurisdiction",
    "Key",
    "Ledger",
    "Named",
    "Pair",
    "Row",
    "Signature",
    "Validator",
    "sign",
    "summarize",
]

from collections.abc import Callable
from typing import Literal, TypeAlias

type ContractId = str
"""An opaque identifier for a single contract"""

type Pair[T] = tuple[T, T]
"""Two values of the same type, e.g. a counterparty pair"""

type Named[T: str] = dict[T, ContractId]
"""Contracts keyed by name, where the key type is bounded by `str`"""

type Key[K: (str, bytes)] = dict[K, ContractId]
"""A lookup keyed by either `str` or `bytes`, but not a mix of the two

griffe stores constraints separately from bounds, leaving `bound` as
None, so this is the form that catches reading only `bound`.
"""

type Row[T, *Ts] = tuple[T, *Ts]
"""A heterogeneous ledger row: a leading column plus any number of others"""

type Validator[**P] = Callable[P, bool]
"""Any predicate, however it is called"""

type Clause = str | list[Clause]
"""A contract clause, possibly nested

Refers to itself. PEP 695 evaluates alias values lazily, so this
needs no quoting and nothing resolves it while rendering.
"""

type Jurisdiction = Literal[
    "us-ca", "us-ny", "us-tx", "gb-eng", "gb-sct", "de-by", "fr-idf", "jp-13"
]
"""A supported governing jurisdiction, as an ISO-ish region code"""

Signature: TypeAlias = Literal["ed25519", "rsa"]
"""Which signing scheme produced a signature

The pre-PEP 695 spelling. It stays a plain attribute rather than a
TypeAlias object, but should carry the same label as its neighbours.
"""


class Ledger:
    """
    An append-only record of contract state changes.

    Declares a type alias in its own body, which belongs under a
    "Type Aliases" heading of its own rather than being dropped.
    """

    type Entry = tuple[ContractId, Jurisdiction]
    """A single ledger entry: which contract, and where it applies"""

    max_entries: int = 1000
    """How many entries the ledger retains before rotating"""

    def __init__(self) -> None:
        self._entries: list[Entry] = []

    def append(self, contract_id: ContractId, where: Jurisdiction) -> None:
        """
        Record that `contract_id` applies in `where`.

        Parameters
        ----------
        contract_id
            The contract being recorded.
        where
            The jurisdiction it applies in.
        """
        self._entries.append((contract_id, where))

    def entries(self) -> list[Entry]:
        """
        Every recorded entry, oldest first.

        Returns
        -------
        list
            The entries in insertion order.
        """
        return list(self._entries)


def sign(contract_id: ContractId, scheme: Signature) -> bool:
    """
    Sign a contract with the named scheme.

    Parameters
    ----------
    contract_id
        The contract to sign.
    scheme
        Which signing scheme to use.

    Returns
    -------
    bool
        True when the contract was signed.
    """
    return bool(contract_id and scheme)


def summarize(rows: Row[ContractId], where: Jurisdiction = "us-ca") -> Named[str]:
    """
    Group contracts by name for one jurisdiction.

    Parameters
    ----------
    rows
        The contracts to summarize.
    where
        Which jurisdiction's rules to apply.

    Returns
    -------
    dict
        Each contract name mapped to its identifier.
    """
    return {str(row): str(row) for row in rows}

📄 README.md

# gdtest-type-aliases

A synthetic test package whose public API is mostly PEP 695 type aliases.

📄 great-docs.yml generated

# Great Docs Configuration
# See https://posit-dev.github.io/great-docs/user-guide/configuration.html
#
# Every option appears below at its default value, with the values it accepts
# documented above it. Set only what you want to change: an option you leave
# out or commented out keeps its default.

# Module Name
# -----------
# Importable module name, when it differs from the project name
# (e.g. project 'py-yaml12' imports as 'yaml12').
# : null - (default) auto-detect
# : type(str) - the module name
# module: null

# Display Name
# ------------
# Display name for your package in the site navbar/title. Use this for a
# marketing/presentation name (e.g. 'My Package').
# : null - (default) the actual package name (e.g. 'my_package' or 'my-package')
# : type(str) - the name to display
# display_name: null

# Project Type
# ------------
# Primary ecosystem(s) the project belongs to. Controls which
# ecosystem-specific links and features are active by default.
# : python - (default) Python package; enables the PyPI link
# : go - Go CLI/library; disables the PyPI link by default
# : type(list) - mixed project, e.g. [python, go]
# project_type: python

# Docstring Parser
# ----------------
# The docstring format used in your package. Auto-detected during
# initialization, but can be overridden here.
# : numpy - (default) numpydoc style
# : google - Google style
# : sphinx - Sphinx/reStructuredText style
parser: numpy

# Dynamic Introspection
# ---------------------
# How the renderer inspects your package. Auto-detected during initialization
# based on what works for your package, but can be overridden here.
# : true - (default) runtime introspection; more accurate for complex packages
# : false - static analysis only; better for packages with cyclic aliases
dynamic: true

# Jupyter Kernel
# --------------
# Jupyter kernel to use for executing code cells in .qmd files.
# This is set at the project level so it applies to all pages, including
# auto-generated API reference pages. Can be overridden in individual .qmd
# file frontmatter if needed for special cases.
# jupyter: python3

# Exclusions
# ----------
# Items to exclude from auto-documentation (affects 'init' and 'scan')
# exclude:
#   - InternalClass
#   - helper_function
# exclude: []

# Names to force-include even if they match AUTO_EXCLUDE
# auto_include: []

# Bypass the built-in AUTO_EXCLUDE list entirely
# no_auto_exclude: false

# PyPI Link
# ---------
# : null - (default) link to pypi.org for Python projects, no link otherwise
# : true - auto-detect the package name and link to pypi.org
# : false - disable the PyPI link
# : type(str) - a custom package index URL
# pypi: https://artifactory.example.com/pkg
# pypi: null

# GitHub Integration
# ------------------
# GitHub repository URL override (e.g. "https://github.com/owner/repo").
# repo: null

# GitHub link style
# : widget - (default) a widget showing the stars count
# : icon - a simple icon
# github_style: widget

# Site URL
# --------
# Canonical address of the deployed docs site. Used for skills-page install
# commands, .well-known/ discovery, sitemaps, and subdirectory deployments;
# also sets website.site-url in _quarto.yml.
# site_url: null

# Source Link Configuration
# -------------------------
# source:
#   enabled: true              # Enable/disable source links (default: true)
#   branch: null               # Git branch/tag to link to (default: auto-detect)
#   path: null                 # Custom source path for monorepos (default: auto-detect)
#   placement: usage           # Where to place the link: "usage" (default) or "title"

# Sidebar Filter
# --------------
# sidebar_filter:
#   enabled: true              # Enable/disable filter (default: true)
#   min_items: 20              # Minimum items before showing filter (default: 20)

# CLI Documentation
# -----------------
# cli:
#   enabled: false        # Enable CLI documentation
#   module: null          # e.g. my_package.cli; auto-detected
#   name: null            # Click command object; auto-detected
#   title: null           # Optional index page + sidebar title
#   desc: null            # Optional intro paragraph atop the index page
#   # sections: explicit grouping/ordering (omit = auto by code order). Example:
#   #   sections:
#   #     - title: "Project setup"
#   #       desc: "Create and configure a project."
#   #       contents: [init, config]
#   #     - title: Building
#   #       contents: [build, preview]
#   sections: []

# Go CLI Documentation
# --------------------
# Builds the Go binary and extracts its command tree via --help. Works with any
# Go CLI (Cobra, urfave/cli, ...) whose subcommands support --help.
# go_cli:
#   enabled: false   # Enable Go CLI documentation (default: false)

# MCP Server Documentation
# ------------------------
# Auto-generates reference pages from an MCP server's tool/resource/prompt
# definitions.
# mcp:
#   enabled: true          # Enable MCP server documentation
#   module: null           # Importable module path (e.g. "sweet.mcp")
#   server_var: null       # Variable name of the Server instance; auto-detected when null
#   name: null             # Display name override; defaults to the server name
#   # Manual tool categories (grouping on the index page). Example:
#   #   categories:
#   #     "Data tools": [load, save]
#   categories: {}

# Dark Mode Toggle
# ----------------
# Enable/disable the dark mode toggle in navbar (default: true)
# dark_mode_toggle: true

# Author Information
# ------------------
# Author metadata for display in the landing page sidebar and page attribution
# authors:
#   - name: "Your Name"
#     email: you@example.com
#     role: "Lead Developer"
#     affiliation: Organization
#     github: yourusername
#     homepage: https://yoursite.com
#     orcid: 0000-0002-1234-5678
#     image: https://github.com/yourusername.png  # Avatar (GitHub URL or local path)
# authors: []

# Funding
# -------
# Funding organization (copyright holder / funder).
# funding:
#   name: "Posit Software, PBC"
#   roles: ["Copyright holder", "funder"]
#   ror: https://ror.org/03wc8by49
# funding: null

# Site Settings
# -------------
# Forwarded to _quarto.yml (format.html). `site` is a Quarto passthrough:
# its subtree is merged into `format.html`, so most valid `format.html` keys
# work here (e.g. `toc-title: "On this page"`). Reserved keys that great-docs
# manages itself and always overrides: `css` (copied and referenced by
# basename separately), `code-copy` (disabled — great-docs supplies its own
# copy-code widget), `html-table-processing` (disabled — required for GT
# table styling), and `mermaid` (fixed to the light theme — dark mode is
# handled via a CSS container). The great-docs page/UI settings that used to
# live here (language, show_dates, date_format, show_author, show_security)
# are top-level keys below; setting them under `site` still works and is
# lifted automatically.
# site:
#   theme: flatly            # Quarto theme
#   toc: true                # Show table of contents
#   toc-depth: 2             # TOC heading depth
#   html-math-method: katex  # HTML math renderer (e.g. mathjax)

# Page Metadata
# -------------
# Language for UI text (BCP 47 code, e.g., "en", "fr", "de", "ja", "zh-Hans")
# Translates navbar labels, widget text, tooltips, and accessibility labels
# language: en

# Show page timestamps in footer
# show_dates: false

# Date format (Python strftime)
# date_format: "%B %d, %Y"

# Show author attribution with dates
# show_author: true

# Show security policy page (from SECURITY.md)
# show_security: true

# Team Author
# -----------
# Optional catch-all author for auto-generated pages (reference, changelog, etc.)
# team_author:
#   name: "Project Team"
#   image: assets/team-avatar.png
#   url: https://github.com/org/project
# team_author: null

# Changelog (GitHub Releases)
# ---------------------------
# Auto-generate a Changelog page from GitHub Releases.
# changelog:
#   enabled: true              # Enable/disable changelog (default: true)
#   max_releases: 50           # Max releases to include (default: 50)

# Custom Sections
# ---------------
# Add custom page groups (examples, tutorials, blog, etc.) to the site.
# Each section gets a navbar link and a sidebar. An auto-generated
# card-based index page is created only when `index: true` is set;
# otherwise the navbar links directly to the first page in the section.
# If you provide your own index.qmd in the directory it is always used.
#
# sections:
#   - title: Examples            # Navbar link text
#     dir: examples              # Source directory (relative to project root)
#     index: true                # Generate card-based index page (default: false)
#     index_columns: 2           # Columns for image cards: 1 or 2 (default: 2)
#     navbar_after: "User Guide" # Place after this navbar item (optional)
#   - title: Tutorials
#     dir: tutorials             # No index — navbar links to first page
#   - title: Blog                # Blog section using Quarto's listing directive
#     dir: blog
#     type: blog                 # "blog" for Quarto listing, omit for card grid
# sections: []

# Custom Static Pages
# -------------------
# Add hand-written HTML pages that Great Docs should either wrap with the site
# shell (layout: passthrough) or copy through unchanged (layout: raw).
#
# : null - (default) discover the conventional `custom/` directory
# : false - disable discovery
# : type(str) - a single directory, e.g. marketing
# : type(list) - one entry per directory:
# custom_pages:
#   - dir: marketing             # Source directory (relative to project root)
#     output: py                 # URL/output prefix (optional; defaults to dir basename)
#   - dir: playgrounds
#     output: demos
# custom_pages: null

# Homepage
# --------
# : index - (default) separate homepage from the README / index source
# : user_guide - the first user-guide page becomes the landing page
# homepage: index

# User Guide
# ----------
# Where the User Guide .qmd files live, and optionally how they are ordered.
# : null - (default) look for user_guide/ in the project root
# : type(str) - a custom directory (relative to project root), e.g. docs/guides
# : type(list) - explicit section ordering and grouping:
# user_guide:
#   - section: "Get Started"
#     contents:
#       - text: Welcome
#         href: index.qmd
#       - quickstart.qmd
#       - installation.qmd
#   - section: "Advanced Topics"
#     contents:
#       - advanced-config.qmd
#       - extending.qmd
#
# File paths are relative to the user guide directory (no user_guide/ prefix).
# When using explicit ordering, numeric filename prefixes are preserved as-is.
# user_guide: null

# Bibliography & Citations
# ------------------------
# Project-level bibliography for [@citation-key] syntax. Paths are relative to
# the project root; the file(s) are copied into the build directory and wired
# into _quarto.yml so every page can cite without per-page frontmatter.
# : [] - (default) no bibliography
# : type(str) - a single file, e.g. docs/references.bib
# : type(list) - several files:
# bibliography:
#   - docs/references.bib
#   - docs/software.bib
# bibliography: []
# csl: docs/nature.csl                    # optional citation style
# csl: null

# API Reference Structure
# -----------------------
# Explicit control over API reference sections. If not provided, sections are
# auto-generated from discovered exports. Each section has a title, description,
# and list of contents.
#
# For classes, use `members: true` (default) to document methods inline on the
# class page, or `members: false` to exclude methods (you can place them
# explicitly elsewhere in the reference if needed).
#
# reference:
#   - title: "Core Classes"
#     desc: "Main classes for working with the package"
#     contents:
#       - name: MyClass
#         members: false       # Don't document methods here
#       - SimpleClass          # Methods documented inline (default)
#
#   - title: "Utility Functions"
#     desc: "Helper functions for common tasks"
#     contents:
#       - helper_func
#       - another_func
reference:
  - title: Classes
    desc: Main classes provided by the package
    contents:
      - Ledger  # 2 method(s)

  - title: Functions
    desc: Utility functions
    contents:
      - sign
      - summarize

  - title: Constants
    desc: Module-level constants and data
    contents:
      - Signature

  - title: Type Aliases
    desc: Type alias definitions
    contents:
      - Clause
      - ContractId
      - Jurisdiction
      - Key
      - Named
      - Pair
      - Row
      - Validator

# Inline Methods
# --------------
# Whether class methods get their own pages or stay inline.
# : 5 - (default) inline up to 5 methods, split above that
# : true - always inline
# : false - always split
# : type(int) - inline up to N methods, split above N
# inline_methods: 5

# Logo & Favicon
# --------------
# A logo replaces the text title in the navbar.
# : type(str) - a single file used in both light and dark mode
# : type(map) - (default) light/dark variants, as below
# logo:
#   light: null            # null = no logo
#   dark: null             # dark-mode variant; falls back to `light` when null
#   show_title: false      # keep the text title alongside the logo

# Favicon.
# : null - (default) auto-generate from the logo, else skip
# : type(str) - a single file, e.g. assets/favicon.png
# : type(map) - one file per purpose:
# favicon:
#   icon: assets/icon.png
#   apple_touch: assets/apple-touch-icon.png
#   og_image: assets/og-image.png
# favicon: null

# Hero Section
# ------------
# Landing-page hero.
# : true - force enable
# : false - force disable
# : type(map) - (default) set the fields explicitly, as below
# hero:
#   enabled: null          # null = auto (on when a logo is set)
#   logo: null             # hero-specific logo; falls back to the navbar logo
#   logo_height: 200px     # max-height CSS value
#   name: null             # defaults to display_name; false hides it
#   tagline: null          # false hides it
#   badges: auto           # "auto" (from README), a list, or false
#   starfield: false       # interactive starfield animation

# Markdown Pages
# --------------
# Generate .md companions for every HTML page and show a copy/view-as-Markdown
# widget on each page.
# : false - disable both
# : type(map) - (default) set the fields explicitly, as below
# markdown_pages:
#   enabled: true   # Generate .md companions for every HTML page (default: true)
#   widget: true    # Show the copy/view-as-Markdown widget (requires enabled)

# Announcement Banner
# -------------------
# Site-wide banner above or below the navbar. Setting `content` enables it.
# : type(str) - the banner text (sets `content`)
# : type(map) - (default) set the fields explicitly, as below
# announcement:
#   content: null          # null = no banner; else the banner text (supports basic Markdown)
#   type: info             # "info" | "warning" | "success" | "danger"
#   dismissable: true      # Allow visitors to dismiss the banner
#   url: null              # Optional link the banner text points to
#   style: null            # Optional gradient preset (same names as navbar_style)
#   position: above-navbar # "above-navbar" (default) | "below-navbar"

# Versioning
# ----------
# Multi-version documentation; disabled when empty. Newest first.
# : [] - (default) single-version site
# : type(list) - tags only, e.g. ["0.3", "0.2", "0.1"], or a map per version:
# versions:
#   - tag: "0.3"
#     label: "0.3.0"
#     latest: true
# versions: []

# Version selector widget (enabled automatically when `versions` is non-empty).
# version_selector:
#   enabled: true             # Master switch for the widget
#   placement: navbar-right   # "navbar-right" | "navbar-left" | "sidebar-top"
#   show_eol: true            # Include end-of-life versions in the dropdown
#   warning_banner: true      # Show a banner on non-latest versions

# Floating version aliases.
# version_aliases:
#   latest: true   # /v/latest/ -> latest stable version
#   stable: true   # /v/stable/ -> same as latest
#   dev: true      # /v/dev/ -> prerelease version, if any

# Badge "new" expiry
# -----------------
# How long a page keeps its "new" status badge before it is considered old.
# : null - (default) no expiry; the badge persists
# : type(str) - a duration understood by parse_badge_expiry
#               (see user_guide/30-multi-version-docs.qmd)
# new_is_old: null

# Colors & Navbar
# ---------------
# Site-wide accent color; sets --gd-accent.
# : null - (default) the theme's own accent color
# : type(str) - any CSS color, used in both modes, e.g. "#3b82f6"
# : type(map) - per-mode:
# accent_color:
#   light: "#3b82f6"
#   dark: "#60a5fa"
# accent_color: null

# Navbar gradient preset.
# : null - (default) no gradient
# : type(str) - a preset name, e.g. sky, peach, lilac
# navbar_style: null

# Navbar solid background color. Text color is chosen automatically for
# contrast (APCA). Overridden when navbar_style is set.
# : null - (default) the theme's own navbar color
# : type(str) - any CSS color, used in both modes, e.g. "#3b82f6"
# : type(map) - per-mode:
# navbar_color:
#   light: "#3b82f6"
#   dark: "#60a5fa"
# navbar_color: null

# Content-area gradient preset (same preset names as navbar_style); adds a
# subtle radial glow at the top of the content area.
# : type(str) - a preset name (sets `preset`)
# : type(map) - (default) set the fields explicitly, as below
# content_style:
#   preset: null   # null = disabled; else a gradient preset name
#   pages: all     # "all" or "homepage"

# Scale to Fit
# ------------
# Auto-shrink wide HTML output to the content width. The matched element's
# nearest output wrapper is scaled down (never up).
# : null - (default) disabled
# : false - disabled
# : type(list) - CSS selectors to auto-scale, e.g. ["#pb_tbl"]
# Per-page override: `scale-to-fit: ["#pb_tbl"]`
# scale_to_fit: null

# Minimum scale for scale-to-fit; below it, content is shown full size with
# horizontal scrolling instead.
# : null - (default) no minimum
# : false - no minimum
# : type(float) - minimum scale factor, 0-1 (e.g. 0.4 = don't shrink below 40%)
# : mobile - disable scaling at viewports ≤ 576px
# : tablet - disable scaling at viewports ≤ 768px
# : desktop - disable scaling at viewports ≤ 992px
# Per-page override: `scale-to-fit-min-scale: "tablet"`
# scale_to_fit_min_scale: null

# Navigation Icons
# ----------------
# Lucide icons prepended to sidebar/navbar entries.
# : {} - (default) no icons
# : false - disabled
# : type(map) - an icon per navbar/sidebar entry:
# nav_icons:
#   navbar:
#     "User Guide": book-open
#   sidebar:
#     Reference: code
# nav_icons: {}

# UI Features
# -----------
# Keyboard shortcuts and help overlay.
# keyboard_nav: true

# Auto-generated package-info page (dependency details), linked from homepage Meta.
# package_info_page: true

# Back-to-top floating button.
# back_to_top: true

# Footer attribution ("Site created with Great Docs").
# attribution: true

# Custom Head HTML
# ----------------
# Injected into <head> of every page.
# : [] - (default) nothing injected
# : type(str) - inline HTML, e.g. '<link rel="preconnect" href="https://example.com">'
# : type(list) - several entries, mixing inline HTML and `text:`/`file:` maps:
# include_in_header:
#   - '<script defer src="/analytics.js"></script>'
#   - file: partials/head.html
# include_in_header: []

# Freeze (Execution Caching)
# --------------------------
# Whether computational documents re-run during builds. A scalar shorthand
# sets `mode` (e.g. `freeze: false`).
# mode:
#   : auto - (default) re-render only when the source changes
#   : true - never re-render during project render
#   : false - execute every document on every build
#   : null - as false
# pre_render: script(s) to run before render (e.g. copy _freeze/ into the build dir)
# freeze:
#   mode: auto
#   pre_render: []

# Pre-render Scripts
# ------------------
# Quarto's native pre-render hook (alternative to freeze.pre_render). Copied
# into the build directory and wired into _quarto.yml. Paths are relative to
# root.
# : [] - (default) no scripts
# : type(str) - a single script, e.g. scripts/before-render.py
# : type(list) - several, e.g. [scripts/before-render.py, scripts/other.py]
# pre_render: []

# Agent Skills
# ------------
# Emits a SKILL.md conforming to the Agent Skills spec (https://agentskills.io/)
# so coding agents can learn the package.
# skill:
#   enabled: true       # Emit a SKILL.md for this package (default: true)
#   file: null          # Path to a hand-written SKILL.md (overrides auto-generation)
#   well_known: true    # Also serve at /.well-known/agent-skills/{name}/SKILL.md + index.json
#   # Strings for the Gotchas section.
#   gotchas: []
#   # Strings for the Best Practices section.
#   best_practices: []
#   # Manual decision-table rows. Example:
#   #   decision_table:
#   #     - need: "Parse a file"
#   #       use: read_yaml()
#   decision_table: []
#   extra_body: null    # Path to extra Markdown appended to the generated body
#   # Multiple named skills (overrides 'file' when set):
#   # skills:
#   #   - name: my-package
#   #     file: skills/my-package/SKILL.md
#   #   - name: authoring-pages
#   #     file: skills/authoring-pages/SKILL.md
#   skills: []

# Social Cards & Open Graph
# -------------------------
# Auto-generate <meta> tags for social media previews (LinkedIn, Discord, Slack,
# Bluesky, Mastodon, X/Twitter, and other platforms). Enabled by default.
#
# Fine-grained control:
# social_cards:
#   enabled: true
#   image: assets/social-card.png   # Default og:image for all pages
#   twitter_site: "@myhandle"       # Twitter/X site @handle
#   twitter_card: summary_large_image  # "summary" or "summary_large_image"
# social_cards:
#   enabled: true          # Auto-generate social preview meta tags (default: true)
#   image: null            # Default og:image for all pages; omitted from meta tags when null
#   twitter_card: null     # "summary" or "summary_large_image"
#   twitter_site: null     # Twitter/X site @handle (e.g. "@myhandle")

# Page Status Badges
# ------------------
# Lifecycle indicators in sidebar navigation. Pages opt in via frontmatter
# (`status: new`, `deprecated`, ...).
# page_status:
#   enabled: false            # Master switch for page status badges
#   show_in_sidebar: true     # Show badges next to sidebar navigation links
#   show_on_pages: true       # Show a status indicator below page titles (like tags)
#   # Built-in status definitions (extend or override).
#   statuses:
#     new:
#       label: New
#       icon: sparkles
#       color: "#10b981"
#       description: Recently added
#     updated:
#       label: Updated
#       icon: refresh-cw
#       color: "#3b82f6"
#       description: Recently updated
#     beta:
#       label: Beta
#       icon: flask-conical
#       color: "#f59e0b"
#       description: Beta feature
#     deprecated:
#       label: Deprecated
#       icon: triangle-alert
#       color: "#ef4444"
#       description: May be removed in a future release
#     experimental:
#       label: Experimental
#       icon: beaker
#       color: "#8b5cf6"
#       description: API may change without notice
#     upcoming:
#       label: Upcoming
#       icon: rocket
#       color: "#e63946"
#       description: Coming in a future release

# Page Tags
# ---------
# Categorize pages for discoverability via frontmatter
# (`tags: [Python, Testing, API]`).
# tags:
#   enabled: false         # Master switch for page tags
#   index_page: true       # Auto-generate a tags index page listing all tags and their pages
#   show_on_pages: true    # Render tag pills above page titles, linked to the tag index
#   hierarchical: true     # Support hierarchical tags with "/" (e.g. "Python/Testing")
#   # Optional tag icons (tag name -> Lucide icon). Example:
#   #   icons:
#   #     Python: code
#   icons: {}
#   # Shadow tags: names hidden from public view (internal organization only).
#   # Shadow-tagged pages are indexed but their tags are not rendered.
#   shadow: []
#   scoped: false          # Show a tag cloud scoped to the section on section pages
#   location: top          # Default tag pill placement: "top" or "bottom"

# SEO
# ---
# Generates sitemap.xml, robots.txt, and discoverability metadata.
# seo:
#   enabled: true            # Master switch for all SEO features
#   sitemap:
#     enabled: true          # Generate sitemap.xml
#     # Change frequency by page type (always|hourly|daily|weekly|monthly|yearly|never).
#     changefreq:
#       homepage: weekly
#       reference: monthly
#       user_guide: monthly
#       changelog: weekly
#       default: monthly
#     # Priority by page type (0.0-1.0).
#     priority:
#       homepage: 1.0
#       reference: 0.8
#       user_guide: 0.9
#       changelog: 0.6
#       default: 0.5
#   robots:
#     enabled: true          # Generate robots.txt
#     allow_all: true        # Allow all crawlers by default
#     disallow: []           # Paths to disallow, e.g. ["/drafts/", "/_internal/"]
#     crawl_delay: null      # Optional crawl delay in seconds
#     extra_rules: []        # Extra raw lines, e.g. ["User-agent: GPTBot", "Disallow: /"]
#   canonical:
#     enabled: true          # Add canonical URLs to pages
#     # Base URL (e.g. "https://example.github.io/pkg/"); auto-detected from
#     # GitHub Pages when null.
#     base_url: null
#   title_template: "{page_title} | {site_name}"   # supports {page_title} and {site_name}
#   structured_data:
#     enabled: true              # Add JSON-LD to pages
#     type: SoftwareSourceCode   # Schema.org type
#   default_description: null   # Falls back to the package description when null