meta:
  path: /examples/directives
  name: Custom Directives
  desc: Comprehensive guide to all custom markdown directives available
  type: documentation
  format: toon/3.3

context: 7-page Dash docs site
relatedPages[5]:
  Home: /
  AI/LLM Integration: /examples/ai-integration
  Data Visualization: /examples/visualization
  Getting Started: /getting-started
  Interactive .md: /examples/interactive

sections[20]:
  1. [3] Introduction
     This documentation boilerplate comes with **powerful custom directives** that extend standard markdown with interactive features. Directives are special commands that let you embed Python components, display source code, generate tables of contents, and more.
     All directives use the syntax: `..
  2. [4] 5. LLM Copy Button - .. llms_copy::
  3. [3] 1. Table of Contents Directive
     The `.. toc::` directive automatically generates a navigable table of contents from your markdown headings.
  4. [4] Usage
     Simply add `.. toc::` anywhere in your markdown (typically at the top):
     ```markdown
     .. toc::
  5. [3] Section 1
  6. [3] Section 2
  7. [4] Subsection 2.1
  8. [4] Features
     - **Auto-generates** from H2 and H3 headings
     - **Clickable links** that scroll to sections
     - **Hierarchical structure** showing document organization
  9. [4] Example
     The table of contents at the top of this page was generated using `.. toc::`!
     ---
  10. [3] 2. Execute Python Directive
     > The `.. exec::` directive embeds interactive Dash components from Python modules.
  11. [4] Usage
     ```markdown
     ```
     This imports and renders the `component` variable from the specified module path.
  12. [4] How It Works
     1. Create a Python file (e.g., `docs/directives/button_example.py`)
     2. Define a `component` variable with your Dash component
     3. Reference it in markdown with `.. exec::docs.directives.button_example`
  13. [4] Example: Simple Button
     **Markdown:**
     ```markdown
     ```
  14. [3] 3. Source Code Display Directive
     > The `.. source::` directive displays syntax-highlighted source code from files.
  15. [4] Usage
  16. [4] Features
     - **Syntax highlighting** for Python code
     - **Line numbers** for easy reference
     - **Copy-to-clipboard** functionality (if enabled)
  17. [4] Example: Display Source
     Let's display the source code of the button example we just saw:
     **Markdown:**
     ```markdown
  18. [3] 4. Component Props Directive
     > The `.. kwargs::` directive auto-generates a documentation table for component properties.
  19. [4] Usage
     ```markdown
     ```
     For Dash Mantine Components:
  20. [4] Features
     - **Automatic extraction** of component properties
     - **Type information** for each prop
     - **Default values** when available

directives:
  llms_copy: [Custom Directives, Page Title, My Component]
  toc: [(none)]
  exec[12]: docs.module.submodule, docs.directives.button_example, ...
  source[8]: path/to/file.py, docs/directives/button_example.py, ...
  kwargs[6]: ComponentName, dmc.Button, ...

execComponents[12]:
  - docs.module.submodule
  - docs.directives.button_example
  - docs.directives.counter_example [callback]
  - docs.directives.form_example [callback]
  - docs.my-feature.demo
  - docs.component.example
  - docs.component.basic
  - docs.component.advanced
  - docs.buttons.primary_button_example
  - docs.ex1
  - docs.forms.validation_example
  - docs.shared.common_example

codeExamples[3]:
  1:
    file: docs/directives/button_example.py
    lang: python
    code: |
      import dash_mantine_components as dmc
      
      # Simple button example for directive showcase
      component = dmc.Button(
          "Click me!",
          variant="filled",
          color="teal",
          size="md"
      )
      
  2:
    file: docs/directives/counter_example.py
    lang: python
    code: |
      from dash import html, callback, Input, Output, State
      import dash_mantine_components as dmc
      from dash_iconify import DashIconify
      
      # Interactive counter example with callbacks
      component = html.Div([
          dmc.Title("Interactive Counter", order=4, mb=10),
          dmc.Group([
              dmc.Button(
                  "Increment",
                  id="increment-btn",
                  variant="filled",
                  color="teal",
                  leftSection=DashIconify(icon="mdi:plus-circle")
              ),
              dmc.Button(
                  "Decrement",
                  id="decrement-btn",
                  variant="filled",
                  color="red",
      # ... (45 more lines)
  3:
    file: docs/directives/form_example.py
    lang: python
    code: |
      from dash import html, callback, Input, Output, State, ALL
      import dash_mantine_components as dmc
      from dash_iconify import DashIconify
      
      # Form validation example
      component = html.Div([
          dmc.Title("User Registration Form", order=4, mb=10),
          dmc.Stack([
              dmc.TextInput(
                  label="Full Name",
                  placeholder="Enter your full name",
                  id="form-name",
                  required=True,
                  leftSection=DashIconify(icon="mdi:account")
              ),
              dmc.TextInput(
                  label="Email",
                  placeholder="your.email@example.com",
                  id="form-email",
                  required=True,
      # ... (94 more lines)

tables[1]:
  1. [Directive|Syntax|Purpose]
     `toc`|`.. toc::`|Generate table of contents
     `exec`|`.. exec::module.path`|Render Python component
     `source`|`.. source::file/path.py`|Display source code
     `kwargs`|`.. kwargs::ComponentName`|Show component props
     `llms_copy`|`.. llms_copy::Page Title`|Add AI-friendly copy button

keyLists[5]:
  - unordered: **Auto-generates** from H2 and H3 headings, **Clickable links** that scroll to sections, **Hierarchical structure** showing document organization, **Automatically updates** when you add new sections
  - unordered: **Syntax highlighting** for Python code, **Line numbers** for easy reference, **Copy-to-clipboard** functionality (if enabled), **Clean formatting** with proper indentation
  - unordered: **Automatic extraction** of component properties, **Type information** for each prop, **Default values** when available, **Descriptions** of what each prop does
  - unordered: **One-click copying** of the page's llms.txt URL, **Visual feedback** showing when URL is copied, **Works in all browsers** with fallback for non-HTTPS contex..., **AI-friendly** - users can paste the URL into ChatGPT, Clau..., **Automatic URL detection** - constructs the correct URL bas...
  - unordered: **Quick AI help** - Share documentation with AI assistants i..., **Better context** - AI gets the full page content in markdo..., **No copy-paste** - URL copying is more reliable than copyin..., **Future-proof** - Works with any AI that can fetch URLs

tips[1]:
  Example: Simple Button:
    [python] import dash_mantine_components as dmc...

bestPractices[5]:
  1. Use Meaningful Module Names
     ✅ Good:
     code[markdown]: |
       .. exec::docs.buttons.primary_button_example
  2. Show Code and Result Together
     Always pair
     code[markdown]: |
       .. exec::docs.component.example
       .. source::docs/component/example.py
  3. Add Context with Markdown
     Explain what the example demonstrates before showing it:
     code[markdown]: |
       This example demonstrates how to handle form validation:
       
       .. exec::docs.forms.validation_example
  4. Use Table of Contents for Long Pages
     For documentation pages with multiple sections, always include:
     code[markdown]: |
       .. toc::
  5. Document Component Props
     When documenting a new component, include the props table:
     code[markdown]: |
       .. kwargs::YourComponent

resources[1]:
  - GitHub Issues: https://github.com/pip-install-python/Dash-Documentation-Boilerplate/issues

summary: Custom Directives: | 20 sections | 3 code examples | 1 tips | 5 best practices | 1 tables | 1 resources | uses exec, kwargs, llms_copy, source, toc | 2 interactive components