v0.14.1

Great Docs v0.14.1 is a maintenance release focused on bug fixes and cross-platform stability. It resolves a number of rendering and configuration issues (including navbar color CSS leaking on Firefox, preview hangs in Safari, and margin sidebar placement) alongside fixes for Windows subprocess encoding, custom page tags, and project-level bibliography forwarding. The site header has also been improved for mobile devices.

Enhancements

• Improved the site header layout and behavior on mobile devices. (#229)

Bug Fixes

• navbar_color: CSS no longer leaks onto the root element, fixing a rendering issue seen on Firefox. (#233)
• Project-level bibliography is now correctly forwarded so citations resolve as expected. (#234)
• Fixed preview hangs that occurred in the Safari browser. (#223)
• The metadata margin sidebar is now placed after the body, correcting its positioning. (#224)
• Tags now render correctly on custom pages. (#225)
• Section files are now copied correctly. (#226)
• Removed 404 errors seen with helper scripts. (#222)
• Subprocess pipes are now decoded as UTF-8 on Windows, preventing encoding errors. (#217)
• Fixed a pypi: false bug where the package_name was mishandled. (#232)
• hero_name now correctly returns False instead of None when set to False. (#221)

New Contributors

• @amyheather made their first contribution in #221

v0.14.0

Great Docs v0.14.0 introduces a full-featured lightbox for images. Add a single .lightbox class to any image (or set lightbox: auto on a page) and readers can expand it into a focused, full-screen view with zoom and panning, swipeable galleries, captions and credits, dark-mode image variants, numbered annotations, before/after comparison sliders, and a toolbar for copying, downloading, and deep-linking images. The assets load automatically on every site, so there is nothing to install or enable.

New Features

• Lightbox — Any image marked with .lightbox opens into a full-screen view with zoom (100–400%) and drag-to-pan. Enable it per image with the .lightbox class, or per page with lightbox: auto (opting individual images out with .nolightbox). (#216)
• Galleries — Images sharing a group value bind into a gallery that readers page through with arrow buttons, keyboard keys, a filmstrip, and touch swipes, with optional looping and autoplay. A .lightbox-gallery fenced div collapses a set into a compact stacked-photo cover with a count badge. (#216)
• Annotations — Overlay numbered, tooltip-bearing markers on an image via an annotations JSON array; markers stay anchored on both the thumbnail and the enlarged view. (#216)
• Before/after comparison — A {{< compare >}} shortcode (or .lightbox-compare div) stacks two images behind a draggable divider, with horizontal or vertical split and a configurable start position. (#216)
• Dark-mode image variants — Opt in with a dark attribute or a .light/.dark filename convention to swap to a dark-optimized image live when the reader toggles themes. (#216)
• Captions, credits, and responsive sources — Add caption and credit lines, and serve sharper images in the enlarged view with standard srcset/sizes or an explicit full-src. (#216)
• Toolbar and deep linking — Copy an image to the clipboard (rasterized to PNG, so SVGs paste cleanly), download it using its alt text as the filename, or copy a #lightbox= deep link that reopens the page on that exact image. (#216)

Documentation

• Added a new "Lightbox" user guide page covering quick start, galleries, annotations, comparison sliders, dark-mode variants, deep linking, accessibility, and the full attribute reference. (#216)

v0.13.1

Great Docs v0.13.1 is a maintenance release focused on rendering correctness and polish. Key fixes address HTML table styling preservation, mobile sidebar scrolling, and callable attribute documentation. The license page and homepage sidebar also received a few presentation upgrades.

Enhancements

• The license page now displays comprehensive SPDX metadata including permissions, conditions, limitations, and interactive badge tooltips. (#209)
• The homepage right sidebar now gets external link indicators. (#210)
• Various package build improvements for reliability and maintainability. (#206)

Bug Fixes

• Pre-styled HTML tables (e.g., from Great Tables) are no longer overwritten by Quarto's Bootstrap styling; table processing is disabled site-wide. (#205)
• The mobile "On This Page" sidebar now scrolls reliably to sections using precise position calculations instead of scrollIntoView(). (#208)
• Callable attributes defined as method = some_function are now correctly promoted to full function documentation. (#204)
• MCP reference page generation now supports FastMCP instances in addition to the standard mcp.server.Server. (#198)
• MCP generation state is properly tracked and stale references are cleaned up between builds. (#197)
• Fixed a UnicodeEncodeError crash on Windows systems with limited console encoding. (#201, @chriscarrollsmith)
• Duplicate page headings no longer appear on single-object API pages. (#194, @bschwedler)

Maintenance

• Python 3.14 added to CI matrix and package classifiers. (#203)

New Contributors

• @chriscarrollsmith made their first contribution in #201

v0.13.0

Great Docs v0.13.0 introduces automatic reference documentation for MCP (Model Context Protocol) servers. Packages that expose MCP tools, resources, and prompts now get fully generated reference pages integrated into the documentation site, making AI agent capabilities discoverable by both humans and machines.

New Features

• MCP server documentation — Automatically generates reference pages for MCP server capabilities (tools, resources, prompts, and resource templates) by introspecting your server module. Pages include parameter types, defaults, required markers, and are styled consistently with existing API reference docs. A .well-known/mcp.json manifest is also generated for client auto-discovery. (#195, #196)

v0.12.0

Great Docs v0.12.0 introduces Termshow, a fully integrated terminal recording and playback system for embedding interactive terminal demos directly in your documentation. Beyond this major addition, this release provides build reliability improvements (including automatic retry on transient errors and versioned-site validation) along with flexible PyPI link configuration and smarter Python version detection for CI workflows.

New Features

• Termshow — Record, edit, and render interactive terminal sessions as SVG-based players embedded in documentation pages. Includes CLI commands for recording (termshow record), editing via a web-based editor (termshow edit), and rendering to SVG frames, with support for chapters, annotations, and visual highlight overlays. (#183, #185, #186, #187, #189, #191, #192, #193)
• PyPI URL config key — New pypi configuration option to control package links: set to True for auto-detection, False to disable, or pass a custom URL string for private registries (#179). (#180)

Bug Fixes

• Build performance improved with per-build caches for package introspection, avoiding redundant work across rendering phases (#172). (#174)
• Quarto renders now automatically retry on transient filesystem errors instead of failing silently. (#176)
• Version expression comparison now correctly handles complex expressions with operators (>=, <) and comma-separated tags. (#175)
• API objects are now categorized in a single batch call, producing accurate type badges in _object_types.json. (#177)
• Python version is now auto-detected from pyproject.toml's requires-python for GitHub Pages deployment workflows. (#178)
• Pre-render and post-render validation added for versioned sites, catching missing .qmd files and failed HTML output early (#181). (#188)

Documentation

• Added guidance on the site_url setting for proper link resolution in deployed sites. (#182)

v0.11.0

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)

v0.10.0

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 {{< tbl-preview >}} 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 {{< tbl-explorer >}} 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 {{< hr >}} 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 {{< keys >}} 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

• @bschwedler made their first contribution in #139.

v0.9

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 {{< color-swatch >}} 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)

v0.8

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: [version-badge new X] 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)

v0.7

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)