Changelog

This changelog is generated automatically from GitHub Releases.

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)