Skip to content

Commit 2314005

Browse files
sourcery-ai[bot]sourcery-ai[bot]
committed
docs: Add documentation for HeadingPlugin and TOCPlugin
Add comprehensive documentation for the HeadingPlugin and TOCPlugin, including their functionality, usage, and best practices. Update the build configuration to include necessary documentation dependencies. Build: - Add Sphinx and sphinx-rtd-theme to the documentation extra requirements in setup.py. Documentation: - Add new documentation for the HeadingPlugin, detailing its purpose, options, and usage examples. - Create documentation for the TOCPlugin, explaining its functionality, rendering dependencies, and customization options. - Include the new heading and TOC documentation files in the main documentation index. Resolves #229
1 parent 1d6a629 commit 2314005

File tree

4 files changed

+227
-0
lines changed

4 files changed

+227
-0
lines changed

‎docs/source/index.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,8 @@ Contents
8383
custom_components
8484
grid
8585
components
86+
plugins/heading
87+
plugins/toc
8688
how-to/index
8789
reference
8890

‎docs/source/plugins/heading.rst‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
#########
2+
Heading
3+
#########
4+
5+
The Heading plugin allows you to add HTML headings (h1-h6) to your content with optional styling and anchors for table of contents integration.
6+
7+
************
8+
Basic Usage
9+
************
10+
11+
The Heading plugin provides the following key features:
12+
13+
- Choose heading level (h1-h6)
14+
- Set heading text
15+
- Add custom ID/anchor for table of contents linking
16+
- Apply text alignment
17+
- Set text color using contextual classes
18+
19+
Example usage:
20+
21+
.. code-block:: html
22+
23+
<h2 id="my-section">My Section Heading</h2>
24+
25+
***********
26+
Settings
27+
***********
28+
29+
Heading Level
30+
============
31+
32+
Select the appropriate heading level (h1-h6) based on your content hierarchy. Use consistent heading levels for proper document structure.
33+
34+
Heading ID
35+
=========
36+
37+
The heading ID field sets the HTML id attribute and is crucial for table of contents functionality:
38+
39+
- Must be unique within the page
40+
- Used by the Table of Contents plugin to generate navigation links
41+
- Should be URL-friendly (e.g., "my-section-name")
42+
43+
Example with ID:
44+
45+
.. code-block:: html
46+
47+
<h2 id="installation">Installation Guide</h2>
48+
49+
Text Alignment
50+
============
51+
52+
Control heading alignment:
53+
54+
- Left (default)
55+
- Center
56+
- Right
57+
58+
Text Color
59+
=========
60+
61+
Apply Bootstrap contextual colors:
62+
63+
- Primary
64+
- Secondary
65+
- Success
66+
- Danger
67+
- Warning
68+
- Info
69+
- Light
70+
- Dark
71+
72+
********************
73+
TOC Integration
74+
********************
75+
76+
To include a heading in the table of contents:
77+
78+
1. Add a unique ID to the heading
79+
2. Place a Table of Contents plugin where you want the navigation to appear
80+
3. Ensure the Table of Contents plugin is rendered after all headings
81+
82+
.. note::
83+
Headings without IDs will not appear in the table of contents.
84+
85+
See the :doc:`Table of Contents </plugins/toc>` documentation for more details.

‎docs/source/plugins/toc.rst‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
###################
2+
Table of Contents
3+
###################
4+
5+
The Table of Contents (TOC) plugin automatically generates a navigation list from headings with IDs in your content.
6+
7+
************
8+
How It Works
9+
************
10+
11+
The TOC plugin:
12+
13+
1. Scans the page for heading plugins with defined IDs
14+
2. Creates a nested list of links to those headings
15+
3. Must be rendered after the headings it references
16+
17+
.. warning::
18+
The TOC plugin can only reference headings that are rendered before it in the page flow.
19+
20+
*********************
21+
Positioning the TOC
22+
*********************
23+
24+
Since the TOC must be rendered after headings to include them, use these strategies to position it at the top of the page:
25+
26+
Using Grid Layout
27+
===============
28+
29+
1. Create a two-column grid layout
30+
2. Place TOC in the first column
31+
3. Place content with headings in the second column
32+
33+
Example structure:
34+
35+
.. code-block:: html
36+
37+
<div class="row">
38+
<!-- TOC Column -->
39+
<div class="col-md-3">
40+
<!-- TOC Plugin -->
41+
</div>
42+
43+
<!-- Content Column -->
44+
<div class="col-md-9">
45+
<!-- Heading Plugins -->
46+
<h2 id="section-1">Section 1</h2>
47+
<p>Content...</p>
48+
49+
<h2 id="section-2">Section 2</h2>
50+
<p>Content...</p>
51+
</div>
52+
</div>
53+
54+
Using CSS
55+
========
56+
57+
Alternatively, use CSS positioning:
58+
59+
1. Place the TOC plugin after your content
60+
2. Use CSS to position it at the top:
61+
62+
.. code-block:: css
63+
64+
.toc-wrapper {
65+
position: fixed;
66+
top: 20px;
67+
left: 20px;
68+
max-width: 250px;
69+
}
70+
71+
***********
72+
Settings
73+
***********
74+
75+
The TOC plugin offers several customization options:
76+
77+
List Style
78+
=========
79+
80+
- Ordered list (numbers)
81+
- Unordered list (bullets)
82+
- Custom classes for styling
83+
84+
Link Attributes
85+
=============
86+
87+
- Add custom classes to TOC links
88+
- Set active link styling
89+
- Configure hover effects
90+
91+
***********
92+
Examples
93+
***********
94+
95+
Basic TOC
96+
========
97+
98+
.. code-block:: html
99+
100+
<!-- Content -->
101+
<h2 id="install">Installation</h2>
102+
<p>Installation content...</p>
103+
104+
<h2 id="config">Configuration</h2>
105+
<p>Configuration content...</p>
106+
107+
<!-- TOC Plugin will generate: -->
108+
<ul class="toc">
109+
<li><a href="#install">Installation</a></li>
110+
<li><a href="#config">Configuration</a></li>
111+
</ul>
112+
113+
Styled TOC with Grid
114+
==================
115+
116+
.. code-block:: html
117+
118+
<div class="row">
119+
<div class="col-md-3">
120+
<!-- TOC Plugin with Bootstrap styling -->
121+
<nav class="sticky-top">
122+
<ul class="nav flex-column">
123+
<li><a href="#install">Installation</a></li>
124+
<li><a href="#config">Configuration</a></li>
125+
</ul>
126+
</nav>
127+
</div>
128+
129+
<div class="col-md-9">
130+
<h2 id="install">Installation</h2>
131+
<p>Installation content...</p>
132+
133+
<h2 id="config">Configuration</h2>
134+
<p>Configuration content...</p>
135+
</div>
136+
</div>

‎setup.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,10 @@
1919
"static-ace": [
2020
"djangocms-static-ace",
2121
],
22+
"docs": [
23+
"sphinx>=4.0.0",
24+
"sphinx-rtd-theme>=1.0.0",
25+
],
2226
"djangocms-link": [
2327
"djangocms-link>=5.0.0",
2428
],

0 commit comments

Comments
 (0)