Links
AI / Agents
gdtest-ug-dark-assets
Test dark-mode asset copying.
User guide with dark-mode image assets in non-images/ subdirectories (assets/orientation/, assets/charts/, assets/diagrams/). Tests that dark-mode siblings — both naming-convention (.light./.dark.) and explicit dark= attribute — are copied to _site. Regression test for GitHub issue #268.
Source files
gdtest_ug_dark_assets/
__init__.py
"""Test package for dark-mode asset copying."""
core.py
"""Core module."""
def process(data: str) -> str:
"""Process input data.
Parameters
----------
data : str
The input data to process.
Returns
-------
str
The processed output.
"""
return datauser_guide/
assets/
charts/
dashboard-custom-dark.svg
<svg xmlns="http://www.w3.org/2000/svg" width="700" height="450"><rect width="700" height="450" fill="#0d1117" rx="8"/><text x="350" y="231" text-anchor="middle" fill="white" font-size="16" font-family="sans-serif">Dashboard (Custom Dark)</text></svg>
dashboard.dark.svg
<svg xmlns="http://www.w3.org/2000/svg" width="700" height="450"><rect width="700" height="450" fill="#16213e" rx="8"/><text x="350" y="231" text-anchor="middle" fill="white" font-size="16" font-family="sans-serif">Dashboard (Dark)</text></svg>
dashboard.light.svg
<svg xmlns="http://www.w3.org/2000/svg" width="700" height="450"><rect width="700" height="450" fill="#ffffff" rx="8"/><text x="350" y="231" text-anchor="middle" fill="#333" font-size="16" font-family="sans-serif">Dashboard (Light)</text></svg>
diagrams/
component-day.svg
<svg xmlns="http://www.w3.org/2000/svg" width="600" height="380"><rect width="600" height="380" fill="#fafafa" rx="8"/><text x="300" y="196" text-anchor="middle" fill="#333" font-size="16" font-family="sans-serif">Component Diagram (Day)</text></svg>
component-night.svg
<svg xmlns="http://www.w3.org/2000/svg" width="600" height="380"><rect width="600" height="380" fill="#0f3460" rx="8"/><text x="300" y="196" text-anchor="middle" fill="white" font-size="16" font-family="sans-serif">Component Diagram (Night)</text></svg>
flow.dark.svg
<svg xmlns="http://www.w3.org/2000/svg" width="500" height="350"><rect width="500" height="350" fill="#1e1e2f" rx="8"/><text x="250" y="181" text-anchor="middle" fill="white" font-size="16" font-family="sans-serif">Flow Chart (Dark)</text></svg>
flow.light.svg
<svg xmlns="http://www.w3.org/2000/svg" width="500" height="350"><rect width="500" height="350" fill="#f5f5f5" rx="8"/><text x="250" y="181" text-anchor="middle" fill="#333" font-size="16" font-family="sans-serif">Flow Chart (Light)</text></svg>
orientation/
sweep-generator.dark.svg
<svg xmlns="http://www.w3.org/2000/svg" width="600" height="400"><rect width="600" height="400" fill="#1a1a2e" rx="8"/><text x="300" y="206" text-anchor="middle" fill="white" font-size="16" font-family="sans-serif">Sweep Generator (Dark)</text></svg>
sweep-generator.light.svg
<svg xmlns="http://www.w3.org/2000/svg" width="600" height="400"><rect width="600" height="400" fill="#f0f4f8" rx="8"/><text x="300" y="206" text-anchor="middle" fill="#333" font-size="16" font-family="sans-serif">Sweep Generator (Light)</text></svg>
images/
status.dark.svg
<svg xmlns="http://www.w3.org/2000/svg" width="500" height="300"><rect width="500" height="300" fill="#1a1a2e" rx="8"/><text x="250" y="156" text-anchor="middle" fill="white" font-size="16" font-family="sans-serif">Status Panel (Dark)</text></svg>
status.light.svg
<svg xmlns="http://www.w3.org/2000/svg" width="500" height="300"><rect width="500" height="300" fill="#e8f0fe" rx="8"/><text x="250" y="156" text-anchor="middle" fill="#333" font-size="16" font-family="sans-serif">Status Panel (Light)</text></svg>
01-naming-convention.qmd
---
title: "Naming Convention Dark Mode"
---
## Auto-Detected Dark Variants
Images using the `.light.ext` / `.dark.ext` naming convention
swap automatically when the reader toggles dark mode.
{.lightbox}
The dark variant `sweep-generator.dark.svg` should load in dark mode.
## Second Example
{.lightbox}02-explicit-dark.qmd
---
title: "Explicit Dark Attribute"
---
## Explicit dark= Attribute
Use `dark="..."` to point at a non-conventionally named dark variant:
{.lightbox dark="assets/diagrams/component-night.svg"}
## Mixed: Convention + Explicit
Convention-based (auto-detected):
{.lightbox}
Explicit override on a convention-named file:
{.lightbox dark="assets/charts/dashboard-custom-dark.svg"}03-in-images-dir.qmd
---
title: "Images in Standard Directory"
---
## Standard images/ Directory
Images in `images/` have always worked. This page confirms that:
{.lightbox}README.md
# gdtest-ug-dark-assets Test dark-mode asset copying.
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: []
# 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