---------------------------------------------------------------------- This is the API documentation for the gdtest_details_shortcode library. ---------------------------------------------------------------------- ## Functions Utility functions render(template: str) -> str Render a template string. Parameters ---------- template The template to render. Returns ------- str Rendered output. transform(data: list) -> list Transform a data list. Parameters ---------- data Input data. Returns ------- list Transformed data. ---------------------------------------------------------------------- This is the User Guide documentation for the package. ---------------------------------------------------------------------- ### Basic Usage The `::: {.details}` fenced div creates enhanced collapsible sections with smooth animation and accessible markup. ## Simple Collapsible A basic collapsible section with a title: ::: {.details summary="Click to expand"} This content is hidden by default. Click the summary bar above to reveal it. You can include **bold**, *italic*, and `code` formatting. ::: ## Default Title Omitting the summary gives a default label: ::: {.details} Content with the default summary text. ::: ## Open by Default Add the `.open` class to start expanded: ::: {.details .open summary="Already expanded"} This section is visible when the page loads. The reader can still click the summary bar to collapse it. ::: ## Multiple Sections Several collapsible sections in sequence: ::: {.details summary="Section One"} Content for the first section. ::: ::: {.details summary="Section Two"} Content for the second section. ::: ::: {.details summary="Section Three"} Content for the third section. ::: ### Callout Types The `type` attribute styles the details section like a Quarto callout — with matching colors and a default icon. ## Note A note-styled collapsible section (`type="note"`): ::: {.details summary="Additional Information" type="note"} This uses the note color scheme (blue) and automatically includes the info icon. Notes are good for supplementary information that most readers can skip. ::: ## Warning A warning-styled section (`type="warning"`): ::: {.details summary="Potential Issues" type="warning"} This uses the warning color scheme (amber) with the triangle-alert icon. Use warnings for gotchas, common mistakes, or things that could go wrong. ::: ## Tip A tip-styled section (`type="tip"`): ::: {.details summary="Pro Tip" type="tip"} This uses the tip color scheme (green) with the lightbulb icon. Tips are great for best practices and helpful advice. ::: ## Danger A danger-styled section (`type="danger"`): ::: {.details summary="Breaking Changes" type="danger"} This uses the danger color scheme (red) with the circle-alert icon. Use danger for destructive operations, breaking changes, or irreversible actions. ::: ## All Types Together Comparing all four types side by side: ::: {.details summary="Note type" type="note"} Blue theme with info icon. ::: ::: {.details summary="Warning type" type="warning"} Amber theme with alert icon. ::: ::: {.details summary="Tip type" type="tip"} Green theme with lightbulb icon. ::: ::: {.details summary="Danger type" type="danger"} Red theme with circle-alert icon. ::: ### Icons Add a Lucide icon before the summary text with the `icon` attribute. ## Custom Icons Any Lucide icon name works: ::: {.details summary="Configuration" icon="settings"} Settings and configuration options for the project. ::: ::: {.details summary="Source Code" icon="code"} View the implementation details. ::: ::: {.details summary="Download Options" icon="download"} Available download formats and mirrors. ::: ::: {.details summary="Performance Notes" icon="zap"} Benchmarks and optimization tips. ::: ::: {.details summary="Security Advisory" icon="shield"} Important security information. ::: ## Icon with Type When a `type` is set, the default icon for that type is used automatically. You can override it with a custom icon: ::: {.details summary="Default note icon" type="note"} Uses the default info icon for notes. ::: ::: {.details summary="Custom note icon" type="note" icon="book-open"} Overrides the note icon with book-open. ::: ::: {.details summary="Custom warning icon" type="warning" icon="flame"} Overrides the warning icon with flame. ::: ### Accordion Groups Use `group="name"` to create accordion behavior — only one section in the group can be open at a time. ## FAQ Accordion Click one section and the others close automatically: ::: {.details summary="What is Great Docs?" group="faq"} Great Docs is a documentation site generator for Python packages. It builds beautiful, searchable API reference sites from your docstrings. ::: ::: {.details summary="How do I install it?" group="faq"} Install with pip: ```bash pip install great-docs ``` Or with uv: ```bash uv add great-docs ``` ::: ::: {.details summary="What Python versions are supported?" group="faq"} Great Docs supports Python 3.9 and later. ::: ::: {.details summary="Is it free?" group="faq"} Yes! Great Docs is open source under the MIT license. ::: ## Multiple Groups Different groups operate independently. Sections in the "install" group don't affect the "config" group. **Installation options:** ::: {.details summary="pip" group="install"} ```bash pip install great-docs ``` ::: ::: {.details summary="conda" group="install"} ```bash conda install great-docs ``` ::: ::: {.details summary="uv" group="install"} ```bash uv add great-docs ``` ::: **Configuration files:** ::: {.details summary="great-docs.yml" group="config"} The main configuration file for your documentation site. ::: ::: {.details summary="pyproject.toml" group="config"} Package metadata is read from pyproject.toml automatically. ::: ::: {.details summary="_quarto.yml" group="config"} Quarto configuration is generated automatically by Great Docs. ::: ### Nesting Details sections can be nested inside each other for hierarchical content. Use more colons for nested fences. ## Two Levels Deep :::: {.details summary="Outer Section"} This is the outer content. ::: {.details summary="Inner Section"} This is nested inside the outer section. ::: More outer content after the nested section. :::: ## Nested with Types :::: {.details summary="Main Topic" type="note"} An overview of the main topic. ::: {.details summary="Important caveat" type="warning"} Watch out for this edge case when using the feature. ::: ::: {.details summary="Helpful hint" type="tip"} Here is a useful tip related to this topic. ::: :::: ## Three Levels Deep ::::: {.details summary="Level 1"} First level of nesting. :::: {.details summary="Level 2"} Second level of nesting. ::: {.details summary="Level 3"} Third level — the deepest. ::: :::: ::::: ### Rich Content The body of a details section supports full Markdown. ## Code Blocks ::: {.details summary="Python Example" icon="code"} ```python import great_docs site = great_docs.build( package="my-package", theme="sky", ) site.serve() ``` ::: ::: {.details summary="Shell Commands" icon="terminal"} ```bash great-docs init my-project cd my-project great-docs build great-docs serve ``` ::: ## Lists ::: {.details summary="Feature List"} Key features of the project: - Automatic API reference generation - Dark mode support - Gradient theme presets - Version badge system - Keyboard navigation ::: ::: {.details summary="Numbered Steps"} 1. Install the package 2. Run `great-docs init` 3. Edit `great-docs.yml` 4. Run `great-docs build` 5. Deploy to GitHub Pages ::: ## Tables ::: {.details summary="Comparison Table" icon="table"} | Feature | Free | Pro | |---------|------|-----| | API Reference | Yes | Yes | | Dark Mode | Yes | Yes | | Custom Themes | No | Yes | | Priority Support | No | Yes | ::: ## Blockquotes ::: {.details summary="Notable Quotes"} > Documentation is a love letter that you write to your > future self. > > — Damian Conway ::: ## Mixed Content ::: {.details summary="Full Example" type="tip" icon="book-open"} Here is a complete example combining multiple elements: **Step 1:** Install the package: ```bash pip install great-docs ``` **Step 2:** Create the configuration: | Setting | Value | |---------|-------| | theme | "sky" | | parser | "numpy" | **Step 3:** Build and verify: ```bash great-docs build great-docs serve ``` > The site should be available at `http://localhost:8080`. ::: ### Combinations Combining multiple options together for real-world use cases. ## Typed Accordion An accordion group where each section has a different type: ::: {.details .open summary="Overview" type="note" group="typed-acc"} Start with a high-level overview of the feature. This section is open by default. ::: ::: {.details summary="Known Issues" type="warning" group="typed-acc"} Current limitations and known bugs. ::: ::: {.details summary="Best Practices" type="tip" group="typed-acc"} Recommended approaches for common use cases. ::: ::: {.details summary="Migration Guide" type="danger" group="typed-acc"} Breaking changes when upgrading from v1 to v2. ::: ## Icon + Type + Open ::: {.details .open summary="Release Notes" type="note" icon="rocket"} Version 2.0 brings major improvements: - Faster build times - New gradient presets - Improved dark mode ::: ## Accordion with Icons ::: {.details summary="Getting Started" icon="rocket" group="guide"} Quick start instructions for new users. ::: ::: {.details summary="Configuration" icon="settings" group="guide"} Detailed configuration reference. ::: ::: {.details summary="Deployment" icon="cloud" group="guide"} Deploy your site to GitHub Pages, Netlify, or Vercel. ::: ::: {.details summary="Troubleshooting" icon="wrench" group="guide"} Common issues and their solutions. ::: ## Gradient Theme The `gradient` type uses your site's animated theme gradient on the summary bar and a subdued tint in the body: ::: {.details summary="Animated Gradient" type="gradient"} This details section uses the site's accent gradient colors with a smooth shifting animation. ::: ::: {.details .open summary="Gradient (open)" type="gradient" icon="sparkles"} A gradient section that starts expanded, with a custom icon. - The summary bar has a vivid animated gradient - The body has a subtle, subdued version - Respects dark mode automatically ::: ::: {.details summary="Gradient Accordion A" type="gradient" group="grad-acc"} First gradient accordion panel. ::: ::: {.details summary="Gradient Accordion B" type="gradient" group="grad-acc"} Second gradient accordion panel. ::: ## Nested Accordion An outer accordion with nested content: :::: {.details summary="Frontend" group="stack"} Frontend technologies used: ::: {.details summary="HTML/CSS"} Quarto generates semantic HTML with SCSS theming. ::: ::: {.details summary="JavaScript"} Custom JS for interactive features like accordion groups, dark mode toggle, and keyboard navigation. ::: :::: :::: {.details summary="Backend" group="stack"} Backend technologies used: ::: {.details summary="Python"} Core logic for parsing, rendering, and configuration. ::: ::: {.details summary="Lua"} Quarto shortcode extensions for custom components. ::: :::: ### Gradient Themes Each gradient preset from the Great Docs theme system is available as a details variant using `gradient="name"`. ## Sky ::: {.details summary="Sky gradient" gradient="sky"} Soft sky blues — inspired by clear horizons. The animated gradient shifts smoothly through four related hues, creating a gentle sense of motion. ::: ## Peach ::: {.details summary="Peach gradient" gradient="peach"} Warm peach and blush tones — friendly and inviting. Works well for introductory or welcoming content. ::: ## Prism ::: {.details summary="Prism gradient" gradient="prism"} Mint, sky, and lavender — a multi-spectral blend. Great for highlighting creative or multi-faceted topics. ::: ## Lilac ::: {.details summary="Lilac gradient" gradient="lilac"} Lilac and pink — soft and elegant. A refined choice for design-related documentation. ::: ## Slate ::: {.details summary="Slate gradient" gradient="slate"} Cool grays — understated and professional. Ideal for technical or enterprise documentation. ::: ## Honey ::: {.details summary="Honey gradient" gradient="honey"} Warm cream and apricot — rich and earthy. A natural choice for warm, approachable content. ::: ## Dusk ::: {.details summary="Dusk gradient" gradient="dusk"} Soft lavender-blue — twilight serenity. Evokes calm and focus, perfect for deep-dive content. ::: ## Mint ::: {.details summary="Mint gradient" gradient="mint"} Pale aqua — fresh and clean. A crisp option for health, environment, or refreshing topics. ::: ## All Presets in Sequence Every preset shown together for comparison: ::: {.details .open summary="Sky" gradient="sky"} Light: soft sky blues. Dark: deep ocean. ::: ::: {.details .open summary="Peach" gradient="peach"} Light: peach and blush. Dark: warm embers. ::: ::: {.details .open summary="Prism" gradient="prism"} Light: mint, sky, lavender. Dark: deep jewel tones. ::: ::: {.details .open summary="Lilac" gradient="lilac"} Light: lilac and pink. Dark: deep violet. ::: ::: {.details .open summary="Slate" gradient="slate"} Light: cool grays. Dark: charcoal depths. ::: ::: {.details .open summary="Honey" gradient="honey"} Light: warm cream. Dark: molten amber. ::: ::: {.details .open summary="Dusk" gradient="dusk"} Light: soft lavender. Dark: midnight indigo. ::: ::: {.details .open summary="Mint" gradient="mint"} Light: pale aqua. Dark: deep teal. ::: ## Gradient Preset Accordion Same presets in accordion mode: ::: {.details summary="Sky" gradient="sky" group="presets"} Soft sky blues with animated shimmer. ::: ::: {.details summary="Peach" gradient="peach" group="presets"} Warm peach and blush tones. ::: ::: {.details summary="Prism" gradient="prism" group="presets"} Multi-spectral mint, sky, and lavender. ::: ::: {.details summary="Lilac" gradient="lilac" group="presets"} Elegant lilac and pink. ::: ::: {.details summary="Slate" gradient="slate" group="presets"} Understated cool grays. ::: ::: {.details summary="Honey" gradient="honey" group="presets"} Rich cream and apricot. ::: ::: {.details summary="Dusk" gradient="dusk" group="presets"} Twilight lavender-blue. ::: ::: {.details summary="Mint" gradient="mint" group="presets"} Fresh pale aqua. ::: ## Gleam Border Effect Add `.gleam` to give the details frame a traveling light that sweeps around the border: ::: {.details .gleam summary="Default gleam"} A subtle light traces the border continuously. ::: ::: {.details .gleam summary="Gleam + Note" type="note"} The gleam color matches the note type (blue). ::: ::: {.details .gleam summary="Gleam + Tip" type="tip"} The gleam color matches the tip type (green). ::: ::: {.details .gleam summary="Gleam + Warning" type="warning"} The gleam color matches the warning type (amber). ::: ::: {.details .gleam summary="Gleam + Danger" type="danger"} The gleam color matches the danger type (red). ::: ## Gleam + Gradient Presets Combining the gleam border with gradient backgrounds: ::: {.details .gleam summary="Sky gleam" gradient="sky"} Animated sky gradient with a matching gleam border. ::: ::: {.details .gleam summary="Peach gleam" gradient="peach"} Warm peach gradient with a matching gleam border. ::: ::: {.details .gleam summary="Prism gleam" gradient="prism"} Multi-spectral gradient with a matching gleam border. ::: ::: {.details .gleam summary="Lilac gleam" gradient="lilac"} Elegant lilac gradient with a matching gleam border. ::: ::: {.details .gleam summary="Dusk gleam" gradient="dusk"} Twilight gradient with a matching gleam border. ::: ::: {.details .gleam summary="Mint gleam" gradient="mint"} Fresh aqua gradient with a matching gleam border. ::: ## Gleam + Theme Gradient ::: {.details .gleam .open summary="Theme accent gleam" type="gradient"} Uses the site accent colors for both the animated gradient background and the gleam border effect. :::