From b6d3b69f499eeba658948d3845ddfbd2cb8d410f Mon Sep 17 00:00:00 2001 From: "sourcery-ai[bot]" Date: Mon, 25 Nov 2024 15:31:47 +0000 Subject: [PATCH 1/8] docs: Add documentation for HeadingPlugin and TOCPlugin Add comprehensive documentation for the HeadingPlugin and TOCPlugin, including configuration details, usage examples, and best practices for content organization. Documentation: - Add new documentation for the HeadingPlugin, detailing configuration options, anchor settings, and usage examples. - Introduce documentation for the TOCPlugin, explaining its dependency on heading anchors and the required rendering order. - Update the index to include the new documentation pages for HeadingPlugin and TOCPlugin. Resolves #229 --- docs/source/index.rst | 2 + docs/source/plugins/heading.rst | 60 ++++++++++++++++++++++++++++++ docs/source/plugins/toc.rst | 65 +++++++++++++++++++++++++++++++++ 3 files changed, 127 insertions(+) create mode 100644 docs/source/plugins/heading.rst create mode 100644 docs/source/plugins/toc.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index b0e2ce3c..9eee3fe6 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -83,6 +83,8 @@ Contents custom_components grid components + plugins/heading + plugins/toc how-to/index reference diff --git a/docs/source/plugins/heading.rst b/docs/source/plugins/heading.rst new file mode 100644 index 00000000..f9dbb4c0 --- /dev/null +++ b/docs/source/plugins/heading.rst @@ -0,0 +1,60 @@ +######### + Heading +######### + +The Heading plugin allows you to add headings (h1-h6) to your content with optional styling and anchors for navigation. + +************* +Configuration +************* + +- **Heading Level**: Choose h1-h6 for the heading tag +- **Heading Text**: The text content of the heading +- **Heading ID**: Optional anchor ID for TOC linking +- **Heading Alignment**: Text alignment (left, center, right) +- **Heading Context**: Optional Bootstrap contextual class for styling + +Example +======= + +Basic heading:: + +

My Section Title

+ +To create a heading that will appear in a table of contents: + +1. Add a Heading plugin +2. Set the heading level (e.g., h2) +3. Enter your heading text +4. Set a unique ID in the "Heading ID" field +5. Optional: Adjust alignment and styling + +Advanced Usage +============= + +Styling +------- + +You can apply Bootstrap contextual classes through the "Heading Context" setting: + +- primary +- secondary +- success +- danger +- warning +- info +- light +- dark + +For example, selecting "primary" will add the ``text-primary`` class. + +TOC Integration +-------------- + +To make a heading appear in a Table of Contents: + +1. The heading **must** have an ID set +2. The TOC plugin must be placed **after** the heading in the content flow +3. Only headings with IDs will appear in the TOC + +See the :doc:`Table of Contents ` documentation for more details. diff --git a/docs/source/plugins/toc.rst b/docs/source/plugins/toc.rst new file mode 100644 index 00000000..5e5ebfc7 --- /dev/null +++ b/docs/source/plugins/toc.rst @@ -0,0 +1,65 @@ +################### + Table of Contents +################### + +The Table of Contents (TOC) plugin automatically generates a navigation list from headings in your content. + +**Important**: The TOC plugin must be placed **after** the headings it references in the content flow. + +************* + How it Works +************* + +The TOC plugin: + +1. Scans for Heading plugins that appear before it in the content +2. Collects headings that have an ID set +3. Generates a nested list of links to those headings + +Basic Usage +========== + +To create a table of contents: + +1. Add your Heading plugins with IDs set +2. Add the TOC plugin after the headings +3. The TOC will automatically generate when the page renders + +Positioning at Top of Page +========================= + +Since the TOC must be placed after headings to collect them, use grid layouts to display it at the top: + +Two Column Layout Example +------------------------ + +1. Create a container +2. Add a row with two columns +3. In the first (left) column: + - Add the TOC plugin +4. In the second (right) column: + - Add your content with Heading plugins +5. Set column widths appropriately (e.g., 3/9 split) + +Example Structure:: + + Container + └── Row + ├── Column (col-3) + │ └── TOC Plugin + └── Column (col-9) + ├── Heading Plugin + ├── Content... + ├── Heading Plugin + └── More content... + +This creates a sidebar layout with the TOC always visible while scrolling through content. + +Best Practices +============= + +1. Always set IDs on headings that should appear in the TOC +2. Use consistent heading levels for proper hierarchy +3. Keep heading IDs unique across the page +4. Consider using the grid layout pattern for better UX +5. Test navigation on both desktop and mobile views From 59ab1031e46e9caa2067cd3b24d35c1a5dfd12f2 Mon Sep 17 00:00:00 2001 From: Fabian Braun Date: Mon, 25 Nov 2024 16:38:45 +0100 Subject: [PATCH 2/8] Delete docs/source/plugins/heading.rst --- docs/source/plugins/heading.rst | 60 --------------------------------- 1 file changed, 60 deletions(-) delete mode 100644 docs/source/plugins/heading.rst diff --git a/docs/source/plugins/heading.rst b/docs/source/plugins/heading.rst deleted file mode 100644 index f9dbb4c0..00000000 --- a/docs/source/plugins/heading.rst +++ /dev/null @@ -1,60 +0,0 @@ -######### - Heading -######### - -The Heading plugin allows you to add headings (h1-h6) to your content with optional styling and anchors for navigation. - -************* -Configuration -************* - -- **Heading Level**: Choose h1-h6 for the heading tag -- **Heading Text**: The text content of the heading -- **Heading ID**: Optional anchor ID for TOC linking -- **Heading Alignment**: Text alignment (left, center, right) -- **Heading Context**: Optional Bootstrap contextual class for styling - -Example -======= - -Basic heading:: - -

My Section Title

- -To create a heading that will appear in a table of contents: - -1. Add a Heading plugin -2. Set the heading level (e.g., h2) -3. Enter your heading text -4. Set a unique ID in the "Heading ID" field -5. Optional: Adjust alignment and styling - -Advanced Usage -============= - -Styling -------- - -You can apply Bootstrap contextual classes through the "Heading Context" setting: - -- primary -- secondary -- success -- danger -- warning -- info -- light -- dark - -For example, selecting "primary" will add the ``text-primary`` class. - -TOC Integration --------------- - -To make a heading appear in a Table of Contents: - -1. The heading **must** have an ID set -2. The TOC plugin must be placed **after** the heading in the content flow -3. Only headings with IDs will appear in the TOC - -See the :doc:`Table of Contents ` documentation for more details. From c84d39228be3174417575c9005a4bb9c3bd10e18 Mon Sep 17 00:00:00 2001 From: Fabian Braun Date: Mon, 25 Nov 2024 16:40:17 +0100 Subject: [PATCH 3/8] Update docs/source/index.rst --- docs/source/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 9eee3fe6..1c2e9349 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -83,7 +83,6 @@ Contents custom_components grid components - plugins/heading plugins/toc how-to/index reference From af4165bf011a22abb279c9a1a3c4998680b504d6 Mon Sep 17 00:00:00 2001 From: Fabian Braun Date: Mon, 25 Nov 2024 16:40:24 +0100 Subject: [PATCH 4/8] Update docs/source/plugins/toc.rst --- docs/source/plugins/toc.rst | 64 ++++++++++++++++++++++++++++++++++++- 1 file changed, 63 insertions(+), 1 deletion(-) diff --git a/docs/source/plugins/toc.rst b/docs/source/plugins/toc.rst index 5e5ebfc7..299a0f58 100644 --- a/docs/source/plugins/toc.rst +++ b/docs/source/plugins/toc.rst @@ -1,4 +1,66 @@ -################### +############################## +Headings and table of contents +############################## + +********* + Heading +********* + +The Heading plugin allows you to add headings (h1-h6) to your content with optional styling and anchors for navigation. + +Configuration +************* + +- **Heading Level**: Choose h1-h6 for the heading tag +- **Heading Text**: The text content of the heading +- **Heading ID**: Optional anchor ID for TOC linking +- **Heading Alignment**: Text alignment (left, center, right) +- **Heading Context**: Optional Bootstrap contextual class for styling + +Example +======= + +Basic heading:: + +

My Section Title

+ +To create a heading that will appear in a table of contents: + +1. Add a Heading plugin +2. Set the heading level (e.g., h2) +3. Enter your heading text +4. Set a unique ID in the "Heading ID" field +5. Optional: Adjust alignment and styling + +Advanced Usage +============= + +Styling +------- + +You can apply Bootstrap contextual classes through the "Heading Context" setting: + +- primary +- secondary +- success +- danger +- warning +- info +- light +- dark + +For example, selecting "primary" will add the ``text-primary`` class. + +TOC Integration +-------------- + +To make a heading appear in a Table of Contents: + +1. The heading **must** have an ID set +2. The TOC plugin must be placed **after** the heading in the content flow +3. Only headings with IDs will appear in the TOC + +******************* Table of Contents ################### From 9d32a66f0b57e5a47c00a0416aee0ca19d334c78 Mon Sep 17 00:00:00 2001 From: Fabian Braun Date: Mon, 25 Nov 2024 16:41:53 +0100 Subject: [PATCH 5/8] Update docs/source/plugins/toc.rst --- docs/source/plugins/toc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/plugins/toc.rst b/docs/source/plugins/toc.rst index 299a0f58..682d254b 100644 --- a/docs/source/plugins/toc.rst +++ b/docs/source/plugins/toc.rst @@ -62,7 +62,7 @@ To make a heading appear in a Table of Contents: ******************* Table of Contents -################### +******************* The Table of Contents (TOC) plugin automatically generates a navigation list from headings in your content. From 422438f7b9a41fc19a3552f02f7e2b5ce80831c8 Mon Sep 17 00:00:00 2001 From: Fabian Braun Date: Mon, 25 Nov 2024 16:41:58 +0100 Subject: [PATCH 6/8] Update docs/source/plugins/toc.rst --- docs/source/plugins/toc.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/source/plugins/toc.rst b/docs/source/plugins/toc.rst index 682d254b..c643c561 100644 --- a/docs/source/plugins/toc.rst +++ b/docs/source/plugins/toc.rst @@ -68,9 +68,8 @@ The Table of Contents (TOC) plugin automatically generates a navigation list fro **Important**: The TOC plugin must be placed **after** the headings it references in the content flow. -************* - How it Works -************* +How it Works +============ The TOC plugin: From aefbd11a90c2c4d31a510f3a9216e41b82f584fa Mon Sep 17 00:00:00 2001 From: Fabian Braun Date: Mon, 25 Nov 2024 16:43:22 +0100 Subject: [PATCH 7/8] Apply suggestions from code review --- docs/source/plugins/toc.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/plugins/toc.rst b/docs/source/plugins/toc.rst index c643c561..59fac3d9 100644 --- a/docs/source/plugins/toc.rst +++ b/docs/source/plugins/toc.rst @@ -87,12 +87,12 @@ To create a table of contents: 3. The TOC will automatically generate when the page renders Positioning at Top of Page -========================= +========================== Since the TOC must be placed after headings to collect them, use grid layouts to display it at the top: Two Column Layout Example ------------------------- +------------------------- 1. Create a container 2. Add a row with two columns @@ -117,7 +117,7 @@ Example Structure:: This creates a sidebar layout with the TOC always visible while scrolling through content. Best Practices -============= +============== 1. Always set IDs on headings that should appear in the TOC 2. Use consistent heading levels for proper hierarchy From b1a5bd721246dc694cecd5b2e440e9e03f48b69b Mon Sep 17 00:00:00 2001 From: Fabian Braun Date: Mon, 25 Nov 2024 16:48:15 +0100 Subject: [PATCH 8/8] Update docs/source/plugins/toc.rst --- docs/source/plugins/toc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/plugins/toc.rst b/docs/source/plugins/toc.rst index 59fac3d9..196b1b06 100644 --- a/docs/source/plugins/toc.rst +++ b/docs/source/plugins/toc.rst @@ -78,7 +78,7 @@ The TOC plugin: 3. Generates a nested list of links to those headings Basic Usage -========== +=========== To create a table of contents: