Changelog

This changelog is generated automatically from GitHub Releases.

v0.11.0

2026-05-18 · GitHub

Great Docs v0.11.0 is a major release focused on build performance, CLI documentation, and skills management. You can now build documentation sites directly from remote repos, freeze expensive code cell outputs to speed up subsequent builds, and automatically generate Click CLI reference pages. This release also introduces collapsible details sections, mobile-friendly page navigation, and the ability to publish multiple AI agent skills from a single project.

New Features

  • Skills overhaul — Skills documentation has been reworked to support multiple named skills, each with its own SKILL.md, configured under skill.skills. The Skills page now features a sticky switcher bar for toggling between them, and each skill is individually installable via the .well-known/agent-skills/ discovery endpoint. (#162, #164, #165, #171)
  • Click CLI documentation — Automatically generate rich, sectioned reference pages for Click-based CLIs with usage signatures, typed options, and descriptions extracted from code. Each command page now includes structured documentation alongside a collapsible --help output view. (#169, #173)
  • Freezing/caching of outputs — Cache notebook execution results in a _freeze/ directory so rebuilds skip re-computation. The great-docs freeze command lets you re-execute specific pages on demand, --info shows cache status across all pages, and the freeze config option (auto or true) controls whether Great Docs re-renders only when sources change or always uses the cache. (#158)
  • ‘On This Page’ listing on mobile — A floating button on mobile viewports opens a compact table-of-contents panel, giving readers quick access to page sections that would otherwise require much scrolling to find. (#168)
  • Mock code cells — Split displayed code from executed code in a single cell using #| source-code: mock, letting readers see clean examples while hiding setup or scaffolding logic. (#161)
  • Collapsible details component — Add expandable content sections using ::: {.details} fenced divs with smooth animations, optional icons, callout-style coloring, and accordion grouping. (#166)
  • Build site from repo — Clone and build documentation for any Git-hosted package with great-docs build --from-repo, handling environment setup, dependency installation, and optional preview automatically. (#153)
  • Page-level build timings — Every build now records per-page render durations in a build-timings.json artifact, and the great-docs timings command surfaces the slowest pages to help identify bottlenecks. (#159)
  • site_url option — New configuration option for sites deployed to subdirectories or multi-version hosts, ensuring correct root-relative asset paths without broken styles or navigation. (#160)

Enhancements

  • Links to pages with numeric ordering prefixes (e.g., 01-intro.qmd) now resolve correctly despite the prefix being stripped for clean URLs. (#167)

Bug Fixes

  • Hidden files (e.g., .nojekyll) are now included in GitHub Pages artifact uploads. (#163)
  • Navbar background default color updated to match the intended design. (#170)

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

v0.10.0

2026-05-03 · GitHub

Great Docs v0.10.0 introduces two powerful data display tools (Table Previews and Table Explorer) for embedding static and interactive tables directly in documentation pages. This release also adds two new shortcode extensions (Horizontal Rules and Keyboard Keys), a new inline_methods config option for controlling API reference page splitting, and several improvements to the homepage, sidebar, and Table Explorer UX.

New Features

  • Table Previews — New tbl_preview() function and shortcode that render self-contained HTML table previews from almost any data source (Polars, Pandas, CSV, Parquet, Arrow, and more). Each preview includes a colored type badge, compact dtype labels, row-number gutters, head/tail splitting for large tables, and missing-value highlighting. Output is JavaScript-free and works identically in light and dark mode. (#134)
  • Table Explorer — New tbl_explorer() function and shortcode that generate fully interactive table widgets with sorting, token-based filtering, pagination, column toggling, copy-to-clipboard, and CSV download. Accepts the same data sources as tbl_preview() and embeds all data as inline JSON with a static fallback. (#137)
  • Horizontal Rules — New shortcode for decorative horizontal rules with four line styles, eight palette colors (plus custom CSS colors), adjustable thickness and width, embedded text labels, and nine ready-made presets including animated gradients. (#143)
  • Keyboard Keys — New shortcode that renders styled keyboard key caps with a 3D border effect, monospace font, and dark-mode support. Handles single keys, multi-key combos with shortcut= syntax, and platform-aware rendering that shows macOS symbols (⌘, ⌥, ⇧) or Windows key names automatically. (#145)

Enhancements

  • The row_index_offset parameter on tbl_preview() lets you control the starting row number (e.g., set to 1 for 1-based numbering). (#136)
  • tbl_explorer() now conserves the configured size across interactions, preventing layout shifts when sorting, filtering, or paginating. (#138)
  • The section sidebar in desktop view now floats as a pinned navigation panel with independent scroll containment, gradient scroll affordances, and auto-scrolling to the active page. (#144)
  • The Table Explorer column toggle now uses a responsive icon-plus-text button that collapses gracefully on smaller screens. (#147)
  • New inline_methods config option controls whether class methods are inlined on the parent class page or split to separate pages. Accepts true (always inline), false (always split), or an integer threshold (default: 5). (#139)

Bug Fixes

  • Inherited methods are now rendered correctly when using include_inherited: true or explicit members lists in the API reference configuration. (#146)
  • Sorting in the Table Explorer no longer requires holding the Shift key for multi-column sorts. (#148)
  • Versioned sites no longer drop pages due to an incomplete version comparison scheme that failed on certain version string formats. (#150)
  • Scale-to-fit containers now support per-container data-min-scale overrides, fixing cases where a global minimum was too aggressive for certain content. (#151)
  • YouTube video embeds now use the standard embedded player with native controls instead of a custom lite player. (#152)

Documentation

  • Added a new Authoring QMD Files page to the User Guide covering frontmatter, Markdown syntax, executable code blocks, and other .qmd features. (#142)
  • Extensively revised and expanded User Guide pages across multiple sections including Table Previews, Table Explorer, Horizontal Rules, Keyboard Keys, Scale-to-Fit, and more.
  • The Great Docs landing page has been improved with a cleaner layout and better visual hierarchy. (#140)

New Contributors

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

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)