Changelog

This changelog is generated automatically from GitHub Releases.

v0.9

2026-04-22 · GitHub

Great Docs v0.9 adds a new Color Swatches shortcode for documenting color palettes, improves support for PyO3/Maturin compiled packages, and fixes the mobile sidebar toggle button that was non-functional on sites without a gradient navbar style.

New Features

  • Color Swatches — New shortcode that renders interactive color palettes from YAML files or built-in presets. Each swatch displays hex codes, shows RGB/HSL breakdowns on hover, evaluates WCAG/APCA contrast ratios, and supports click-to-copy. (#130)

Bug Fixes

  • PyO3/Maturin compiled extension modules are now handled correctly during documentation rendering, including dotted module names and missing line numbers. (#132)
  • The mobile sidebar toggle button in the Title Bar now works on all sites, not only those with a gradient navbar style. The intercept logic was moved from the conditionally-loaded navbar-style.js to the always-loaded navbar-widgets.js. (#133)

Full Changelog: https://github.com/posit-dev/great-docs/compare/v0.8…v0.9

v0.8

2026-04-21 · GitHub

Great Docs v0.8 introduces versioned documentation builds, letting readers browse docs for any supported release while maintainers declare versions once and let the build handle the rest. This release also brings clean URLs by stripping numeric directory prefixes, customizable sidebar groups, automatic badge expiry, and comprehensive mobile-responsive navigation. Keyboard shortcuts, stale-badge linting, and better error messages round out a release focused on authoring power and reader experience.

New Features

  • Versioned documentation — Build separate, version-scoped copies of the documentation site. Each version entry in great-docs.yml can reference an api_snapshot or git_ref to regenerate API pages from that release, with automatic frontmatter filtering, version fences, and sidebar pruning. (#116, #118)

  • Clean URL prefixes — Numeric ordering prefixes (e.g., 01-, 0001-) are now automatically stripped from user guide filenames and subdirectory names in auto-discovery mode, producing cleaner published URLs without changing how authors organize files. (#111)

  • Sidebar groups — Flat section pages can now be organized into named groups in the sidebar via a sidebar_groups config, each with a section title and contents list, removing the need for subdirectories to achieve logical grouping. (#124)

Enhancements

  • Badge expiry keeps docs current: <span class="gd-badge gd-badge-new">New in X</span> markers automatically disappear based on configurable rules—after N releases, a calendar date, a specific version, and more—via the new_is_old config option. (#119)

  • Pages scoped to prerelease versions or with upcoming: frontmatter now automatically display an “upcoming” status badge, clearly labeling not-yet-released features for readers. (#122)

  • New stale-versions lint check flags outdated version badges, stale callouts, and upcoming: frontmatter referencing already-released versions so maintainers can keep annotations current. (#123)

  • Documentation sites are now fully usable on phones and tablets with a slide-in menu overlay, pinned secondary nav, vertically stacked prev/next links, and responsive table handling. (#126, #128)

  • New keyboard shortcuts for direct navigation to the User Guide and API Reference (where available) allow for quicker keyboard access to key sections. (#109)

  • Build log presentation is improved with clearer formatting and with build-time heuristics. (#113, #114)

  • When Quarto is not installed, users now get an immediate, actionable error with install instructions instead of a cryptic subprocess failure. (#127, @tylerriccio33)

Bug Fixes

  • Namespace packages now initialize correctly. (#115)

  • GitHub Actions workflow versions are updated and the build command is properly configured. (#110, #117)

  • New auto_include and no_auto_exclude options let packages override the built-in auto-exclude list, so intentionally public names like version or utils can be documented. (#129)

Maintenance

  • The legacy renderer and builder-style API have been removed, simplifying the codebase. (#81, #82, @has2k1)

Full Changelog: https://github.com/posit-dev/great-docs/compare/v0.7…v0.8

v0.7

2026-04-13 · GitHub

Great Docs v0.7 introduces Scale-to-Fit, a new feature that automatically adapts wide HTML output to fit the page width, and improves the visual presentation of section index pages with a card-based gallery layout. This release also delivers a broad set of fixes across blog sections, GT table handling, homepage layouts, and cross-referencing, resulting in a more reliable and polished documentation experience.

New Features

  • Scale-to-Fit — Automatically shrinks wide HTML output (GT tables, DataFrames, custom widgets) to fit the page width, falling back to horizontal scrolling when content would shrink beyond a configurable minimum threshold. Configurable globally via scale_to_fit and scale_to_fit_min_scale in great-docs.yml, per-page via frontmatter, or manually with a :::{.scale-to-fit} div. (#97)

Enhancements

  • Section index pages now use a card-based gallery layout with image cards, hover effects, and a responsive grid, making sections with visual content more discoverable. (#108)

Bug Fixes

  • Blog index pages now render with correct layout and styling. (#103)
  • Blog sections with a user-provided index.qmd page are now laid out properly. (#106)
  • Assets in blog directories are now copied to the finalized site. (#107)
  • GT tables are no longer incorrectly wrapped in responsive table containers. (#95)
  • GT tables now receive proper scoped styling and ID-based CSS selectors. (#96)
  • Homepage layout now works correctly when blended with a user guide that uses subdirectories. (#94)
  • Homepage content alignment is no longer broken when code cells are present. (#100)
  • Great Docs Link System (GDLS) cross-references now resolve correctly on non-reference pages such as user guides and blog posts. (#101)
  • Griffe compatibility was improved with conditional imports for older versions, and project_root is now properly resolved for development installs. (#105)
  • CairoSVG is now optional; rasterizing is skipped when the library is not installed. (#92)
  • Subdirectory assets are now properly copied to the output directory. (#93)
  • Changelog section headings are now normalized for consistent rendering. (#98)
  • Previous/next navigation links now stack vertically on mobile screens. (#99)
  • Backticks in docstring headers are now handled correctly during rendering. (#102)
  • Favicons are injected into resources using absolute URLs for reliable loading across all pages. (#104)

Full Changelog: https://github.com/posit-dev/great-docs/compare/v0.6…v0.7

v0.6

2026-04-07 · GitHub

Great Docs v0.6 is focused on page-level metadata, content enrichment, and site customization. This release introduces page tags for categorizing content, page status badges that surface lifecycle state in both the page body and sidebar, inline Lucide icon insertion via a simple shortcode, and support for hand-authored custom HTML pages. An experimental API Evolution feature lets you track how your package’s public API changes across tagged releases, with CLI diffing, positional evolution tables, and embeddable shortcodes.

New Features

  • Custom pages — Hand-written HTML pages can now be auto-discovered and integrated into your documentation site with minimal transformation. Configure source directories via the custom_pages option for product landing pages, interactive demos, or any content that doesn’t fit the .qmd workflow. (#79)
  • Page tags — Categorize pages with tags added via YAML frontmatter (e.g., tags: [Python, Testing, API]). Great Docs renders pill-shaped tag links above page titles and auto-generates a tags index page listing all tags with their linked pages. Enable with tags: true. (#83)
  • Page status badges — Mark pages with lifecycle statuses such as new, beta, deprecated, or experimental in frontmatter. Color-coded badges appear below the page title and as compact icons in the sidebar, with built-in Lucide icons, colors, and descriptions that are automatically translated for non-English sites. (#86)
  • Inline icons — Insert any of 1,900+ Lucide icons anywhere in .qmd content using the shortcode. Icons scale with surrounding text, sit on the baseline, inherit text color, and support optional size and label parameters for accessibility. (#90)
  • API Evolution (experimental) — Track how your package’s public API changes across tagged releases with the new great-docs api-diff command. Produces added/removed/changed symbol summaries with breaking-change detection, positional evolution tables, dependency graphs, and API surface timelines. Embed evolution tables directly in pages with the shortcode.

Enhancements

  • Changelog page generation now uses a structured format with version numbers, release dates, GitHub links, and grouped sections for features, enhancements, and bug fixes. (#76)
  • Added q as a keyboard shortcut to return to the homepage. (#80)
  • Tag pill location can now be configured to appear at the "top" (default) or "bottom" of the page via tags.location. (#87)

Bug Fixes

  • Keyboard navigation icon now appears in the navbar widget tray. (#77)
  • Keyboard shortcuts button now displays a tooltip on hover. (#78)
  • Improved styling of previous/next page navigation links. (#84)
  • Resolved tag rendering issues on pages with certain frontmatter configurations. (#85)
  • File operations now always specify UTF-8 encoding, preventing issues on systems with non-UTF-8 defaults. (#88)
  • Navbar widgets (dark-mode toggle, keyboard shortcuts, GitHub icon, search) are now collected into a single flex container for uniform spacing and predictable ordering. (#91)

Full Changelog: https://github.com/posit-dev/great-docs/compare/v0.5…v0.6

v0.5

2026-04-01 · GitHub

Great Docs v0.5 brings meaningful improvements to site navigation, discoverability, and content fidelity. This release introduces Lucide icon support for navbar and sidebar navigation items, automatic social card meta tags for richer link previews, and a fully keyboard-navigable interface with shortcuts for search, page browsing, dark mode, and more. The navbar logo now displays a version and release date tooltip, and a bug fix ensures horizontal scrolling works correctly when a site has many top-level navigation items.

New Features

  • Navigation icons — Assign Lucide icons to navbar and sidebar navigation labels via the new nav_icons config option. Icons can be configured independently for navbar and sidebar scopes, mapping label text to any Lucide icon name. (#70)
  • Social cards — Per-page Open Graph and Twitter Card meta tags (og:title, og:description, og:url, og:image) are now injected automatically. A default image can be set via social_cards.image; the feature is enabled by default and can be disabled with social_cards: false. (#72)
  • Keyboard navigation — Sites now ship with a keyboard shortcut layer (enabled by default; disable with keyboard_nav: false). Shortcuts include / or s to focus search, [ / ] for previous/next page, d to toggle dark mode, c to copy the page as Markdown, and h or ? to show a help overlay. All shortcuts are skipped when a text input is focused and respect prefers-reduced-motion. (#73)

Enhancements

  • Navbar logo tooltip now shows the package version tag and release date when the navbar uses a logo image instead of a text title. (#69)
  • Improved API index presentation in the navbar to more clearly distinguish API and CLI reference sections. (#71)

Bug Fixes

  • Fixed horizontal scrolling for top-level navbar items on sites with many navigation links — items no longer wrap or get clipped. (#74)
  • Refined Markdown postprocessing to correctly decode HTML entities, repair UTF-8 mojibake sequences (e.g., ’ → '), and normalize smart quotes and dashes to plain ASCII for portable output. (#75)

Full Changelog: https://github.com/posit-dev/great-docs/compare/v0.4…v0.5

v0.4

2026-03-30 · GitHub

Great Docs v0.4 adds internationalization, making it possible to present your entire documentation site in any of 23 languages with a single config option. This release also introduces a back-to-top button for easier page navigation, and license pages now display structured permissions, conditions, and limitations as color-coded badges.

New Features

  • Internationalization (i18n) — All UI text—navbar labels, button tooltips, relative timestamps, accessibility attributes—can now be translated by setting site.language in great-docs.yml. Translations include proper plural forms and localized date expressions (#41). (#66, #68)

  • Back-to-top button — A floating button appears after scrolling down, smoothly returning users to the top of the page. Respects prefers-reduced-motion, adapts to dark mode, and shifts to avoid overlapping prev/next navigation. Enabled by default; disable with back_to_top: false. (#65)

  • License feature badges — License pages now display structured metadata showing permissions (green), conditions (blue), and limitations (red) as collapsible, color-coded badge groups. Supports 70+ SPDX-identified licenses. (#67)

Full Changelog: https://github.com/posit-dev/great-docs/compare/v0.3…v0.4

v0.3

2026-03-27 · GitHub

Great Docs v0.3 focuses on documentation quality and media support. A new lint command helps catch missing docstrings, broken cross-references, and style inconsistencies before your docs go live. Video embeds are now performance-optimized with lazy-loading and lightweight YouTube placeholders that load full players only on click. SECURITY.md files are automatically integrated into your documentation site, making security policies discoverable alongside your API reference.

New Features

  • Video embed optimization — YouTube embeds use lightweight thumbnail placeholders that load the full player only when clicked, significantly improving page load times. Vimeo and other iframes lazy-load via IntersectionObserver, and local videos automatically set preload="metadata". (#64)
  • Documentation linting — New great-docs lint command analyzes your package’s public API for missing docstrings, broken cross-references, style mismatches, and unknown directives. Supports JSON output for CI integration. (#63)
  • SECURITY.md support — Security policy files are auto-detected from the project root or .github/ directory and converted to a security.qmd page with a link in the Community section. Controllable via show_security config option. (#62)

Bug Fixes

  • Reference section tables now have improved styling and correct anchor linking behavior. (#61)

Full Changelog: https://github.com/posit-dev/great-docs/compare/v0.2.1…v0.3

v0.2.1

2026-03-27 · GitHub

Packaging fix release — no functional changes from v0.2.

Changes

  • Switched to setuptools_scm for automatic version detection from Git tags.

Full Changelog: https://github.com/posit-dev/great-docs/compare/v0.2…v0.2.1

v0.2

2026-03-27 · GitHub

Great Docs v0.2 brings significant improvements to site presentation, content quality, and SEO. This release introduces styled tooltips throughout, responsive tables that work on any screen size, Mermaid diagram support with dark mode compatibility, and comprehensive SEO features including automatic sitemap generation. A new proofread command powered by Harper helps catch grammar and spelling issues locally. Pages can now display creation/modification metadata, and ROADMAP.md files are automatically integrated into your documentation.

New Features

  • ROADMAP.md support: Project roadmap files are now auto-detected and integrated into the documentation site with proper navigation links. (#42)
  • Page metadata display: Pages can optionally show creation/modification dates and author attribution, sourced from Git history with frontmatter overrides. (#46)
  • Tippy.js tooltips: Native browser tooltips replaced with instant, material-design styled tooltips that work beautifully in both light and dark modes. (#47)
  • Harper proofreading: New great-docs proofread command for local grammar and spelling checks with a built-in technical dictionary and multiple output formats (#43). (#48)
  • Mermaid diagram support: Proper theme support for Mermaid diagrams including dark mode compatibility and consistent styling (#45). (#51)
  • SEO features: Comprehensive search engine optimization with automatic sitemap.xml, robots.txt, canonical URLs, JSON-LD structured data, and an seo audit command. (#53)
  • Responsive tables: Tables are now horizontally scrollable on narrow viewports with visual scroll indicators and touch-friendly momentum scrolling. (#54)

Enhancements

  • Markdown is now supported in announcement banner text, allowing links and formatting. (#35)

Bug Fixes

  • Custom copy-code button styling and assets were added to fix inconsistent appearance. (#36)
  • Python version is now auto-detected for GitHub deployment workflows (#38). (#40)
  • GitHub Actions workflow action versions were updated to current releases. (#49)
  • Table styling was refined for better visual consistency. (#55)
  • The deprecated spell-check CLI command was removed. (#56)
  • Images in README.md files are now properly copied to the output directory (#39). (#57)
  • Package manager detection was improved for more accurate GHA workflow configuration (#37). (#58)
  • A missing option was added to the CI workflow generation CLI command. (#60)

Documentation

  • Added documentation on GitHub repository discovery and explicit repository definition in config (#31). (#59)

Full Changelog: https://github.com/posit-dev/great-docs/compare/v0.1…v0.2

v0.1

2026-03-20 · GitHub

Initial release – An easy-to-use documentation site generator for Python packages.

Highlights

Great Docs turns your Python package into a polished, modern documentation site with minimal setup. Run great-docs init, great-docs build, and you’re done.

Core Features

  • Automatic API reference generation from your package’s public API, with support for NumPy, Google, and Sphinx docstring styles
  • CLI documentation auto-generated from Click-based command groups
  • User guide support with Quarto-based markdown (.qmd) files
  • Built-in recipes – 18 step-by-step guides covering common documentation tasks
  • GitHub Pages deployment with one command (great-docs setup-github-pages), including PR preview deployments

CLI Commands

Command Description
great-docs init Initialize docs config with auto-discovered API structure
great-docs build Build the documentation site (supports --watch mode)
great-docs preview Serve the site locally
great-docs scan Inspect discoverable API symbols
great-docs config Generate a template config with all options
great-docs check-links Validate URLs across source and docs
great-docs spell-check Check documentation spelling with custom dictionaries
great-docs setup-github-pages Generate a GitHub Actions workflow for deployment
great-docs uninstall Remove generated docs files

Styling & Theming

  • Modern default theme with dark mode toggle
  • 8+ navbar gradient presets (sky, peach, lilac, mint, ocean, sunset, forest, …)
  • Custom navbar colors with automatic APCA contrast selection
  • Logo support with light/dark variants and auto-generated favicons
  • Hero section for landing pages
  • Announcement banners (dismissible, styled)

LLM & AI Integration

  • Auto-generates llms.txt and llms-full.txt for LLM consumption
  • Generates SKILL.md conforming to the Agent Skills specification
  • Serves skills at /.well-known/skills/ for AI agent discovery

Configuration

All options live in a single great-docs.yml file. See great-docs config for the full list, or visit the documentation.

Requirements

  • Python >= 3.11
  • Quarto (must be installed separately)