docs: Add detailed documentation for HeadingPlugin and TOCPlugin

docs/source/plugins/heading.rst

@@ -0,0 +1,51 @@
+Heading Plugin
+=============
+
+The Heading plugin allows you to create HTML headings (h1-h6) with optional styling and anchors that can be referenced by the Table of Contents plugin.
+
+Configuration Options
+-------------------
+
+* ``heading_level`` - The heading level (h1-h6)
+* ``heading`` - The heading text content
+* ``heading_id`` - The HTML ID attribute for the heading (required for TOC entries)
+* ``heading_context`` - Bootstrap contextual class for styling (primary, secondary, success, etc.)
+* ``heading_alignment`` - Text alignment (left, center, right)
+
+Example Usage
+------------
+
+Basic heading::
+
+    heading_level: h2
+    heading: My Section Title
+    heading_id: section-1
+
+Styled heading with custom alignment::
+
+    heading_level: h3
+    heading: Important Section
+    heading_id: important
+    heading_context: primary
+    heading_alignment: center
+
+Table of Contents Integration
+---------------------------
+
+To make a heading appear in a table of contents:
+
+1. Always set a unique ``heading_id`` for the heading
+2. Place the heading before any TOC plugins that should reference it
+3. Use semantic heading levels (h1 > h2 > h3) for proper hierarchy
+
+Example with TOC integration::
+
+    heading_level: h2
+    heading: First Section
+    heading_id: first-section
+
+    heading_level: h3
+    heading: Subsection
+    heading_id: first-section-sub
+
+The above headings will appear in any TOC plugin placed after them in the content flow.

docs/source/plugins/index.rst

@@ -0,0 +1,9 @@
+Plugins
+=======
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Available Plugins:
+
+   heading
+   toc

docs/source/plugins/toc.rst

@@ -0,0 +1,63 @@
+Table of Contents Plugin
+=======================
+
+The Table of Contents (TOC) plugin automatically generates a navigation list from heading plugins with defined anchor IDs.
+
+Important Notes
+-------------
+
+* TOC entries are only generated from heading plugins that have a ``heading_id`` defined
+* The TOC plugin must be placed **after** the headings it should include
+* Use grid layouts to position the TOC above content while maintaining proper render order
+
+Configuration Options
+-------------------
+
+* ``list_attributes`` - HTML attributes for the TOC list element
+* ``link_attributes`` - HTML attributes for TOC link elements
+* ``item_attributes`` - HTML attributes for TOC list item elements
+
+Example Usage
+------------
+
+Basic TOC::
+
+    # Will generate a list of all headings with IDs that appear before this TOC
+
+Positioning TOC Above Content
+---------------------------
+
+To display the TOC at the top of a page while maintaining proper render order:
+
+1. Create a two-column grid layout
+2. Place headings in the main content column
+3. Place TOC in the sidebar column
+4. Use Bootstrap order classes to display sidebar first
+
+Example grid structure::
+
+    Grid Row
+    ├── Column 1 (order-2)
+    │   ├── Heading 1
+    │   ├── Content...
+    │   └── Heading 2
+    └── Column 2 (order-1)
+        └── TOC Plugin
+
+This structure allows the TOC to render after the headings but display before them visually.
+
+Customizing TOC Appearance
+------------------------
+
+Example with custom attributes::
+
+    list_attributes:
+        class: nav nav-pills flex-column
+
+    link_attributes:
+        class: nav-link
+
+    item_attributes:
+        class: nav-item
+
+This will style the TOC using Bootstrap nav classes.