Skip to content

Commit 3ac192c

Browse files
rich-iannonerich-iannone
committed
Enhance Page Tags guide with demos and styles
1 parent 44ab315 commit 3ac192c

1 file changed

Lines changed: 182 additions & 24 deletions

File tree

‎user_guide/26-page-tags.qmd‎

Lines changed: 182 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,110 @@ versions: ">=0.6"
88

99
# Page Tags
1010

11-
Great Docs lets you categorize pages with tags for improved discoverability. Add tags to any user guide, recipe, or custom section page via frontmatter, and Great Docs will generate a tags index page, render tag pills above page titles, and support hierarchical tag organization.
11+
As a documentation site grows, the sidebar and search bar are not always enough to help readers find
12+
what they need. Tags offer a second axis of navigation, organized by topic rather than page order. A
13+
reader looking for everything related to "Testing" can find it in one place, even if those pages are
14+
spread across the User Guide, Recipes, and custom sections.
15+
16+
Great Docs lets you categorize pages with tags for improved discoverability. Add tags to any user
17+
guide, recipe, or custom section page via frontmatter, and Great Docs will generate a tags index
18+
page, render tag pills above page titles, and support hierarchical tag organization.
19+
20+
<style>
21+
.gd-demo-tag-pill, .gd-demo-tag-index, .gd-demo-tag-page-mock {
22+
font-family: "Open Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
23+
}
24+
.gd-demo-tag-pill {
25+
display: inline-flex;
26+
align-items: center;
27+
gap: 0.2rem;
28+
padding: 0.15rem 0.55rem;
29+
font-size: 0.75rem;
30+
font-weight: 500;
31+
line-height: 1.4;
32+
color: #6b7280;
33+
background-color: #f3f4f6;
34+
border: 1px solid #d1d5db;
35+
border-radius: 1rem;
36+
text-decoration: none;
37+
white-space: nowrap;
38+
}
39+
.gd-demo-tag-pills {
40+
display: flex;
41+
flex-wrap: wrap;
42+
gap: 0.4rem;
43+
margin-top: 0.35rem;
44+
margin-bottom: 0.8rem;
45+
}
46+
.gd-demo-tag-page-mock {
47+
border: 1px solid #e5e7eb;
48+
border-radius: 0.5rem;
49+
padding: 1rem 1.25rem;
50+
margin: 1rem 0;
51+
background: transparent;
52+
}
53+
body.quarto-dark .gd-demo-tag-page-mock { border-color: #374151; }
54+
body.quarto-dark .gd-demo-tag-pill {
55+
color: #9ca3af;
56+
background-color: rgba(107,114,128,0.15);
57+
border-color: rgba(107,114,128,0.3);
58+
}
59+
.gd-demo-tag-index {
60+
border: 1px solid #e5e7eb;
61+
border-radius: 0.5rem;
62+
padding: 1rem 1.25rem;
63+
margin: 1rem 0;
64+
background: transparent;
65+
}
66+
body.quarto-dark .gd-demo-tag-index { border-color: #374151; }
67+
.gd-demo-section-badge {
68+
display: inline-block;
69+
font-size: 0.7rem;
70+
font-weight: 500;
71+
color: #6b7280;
72+
background-color: #f3f4f6;
73+
padding: 0.05rem 0.4rem;
74+
border-radius: 0.25rem;
75+
margin-left: 0.4rem;
76+
vertical-align: middle;
77+
}
78+
body.quarto-dark .gd-demo-section-badge { color: #9ca3af; background-color: #1f2937; }
79+
.gd-demo-tag-seg {
80+
display: inline-flex;
81+
align-items: center;
82+
padding: 0;
83+
border-radius: 1rem;
84+
overflow: hidden;
85+
border: 1px solid #d1d5db;
86+
font-size: 0.75rem;
87+
font-weight: 500;
88+
line-height: 1.4;
89+
color: #6b7280;
90+
white-space: nowrap;
91+
}
92+
body.quarto-dark .gd-demo-tag-seg { color: #9ca3af; border-color: rgba(107,114,128,0.3); }
93+
.gd-demo-tag-seg-parent {
94+
display: inline-flex;
95+
align-items: center;
96+
padding: 0.15rem 0.55rem;
97+
background-color: #f3f4f6;
98+
}
99+
body.quarto-dark .gd-demo-tag-seg-parent { background-color: rgba(107,114,128,0.15); }
100+
.gd-demo-tag-seg-child {
101+
display: inline-flex;
102+
align-items: center;
103+
padding: 0.15rem 0.55rem;
104+
background-color: #f9fafb;
105+
}
106+
body.quarto-dark .gd-demo-tag-seg-child { background-color: rgba(107,114,128,0.08); }
107+
.gd-demo-tag-seg-sep {
108+
display: inline-block;
109+
width: 1px;
110+
align-self: stretch;
111+
background-color: #9ca3af;
112+
}
113+
body.quarto-dark .gd-demo-tag-seg-sep { background-color: rgba(107,114,128,0.4); }
114+
</style>
12115

13116
Tags are disabled by default. To enable them, add a `tags` section to `great-docs.yml`:
14117

@@ -34,13 +137,27 @@ tags: [Python, Configuration, Getting Started]
34137
---
35138
```
36139

37-
Tags can be any string. They are case-sensitive, so `Python` and `python` are treated as different tags.
140+
Tags can be any string. They are case-sensitive, so `Python` and `python` are treated as different
141+
tags.
38142

39143
## Tags Index Page
40144

41-
When tags are enabled, Great Docs automatically generates a `tags/index.qmd` page that lists every tag and the pages associated with it. A "Tags" link is added to the site's top navigation bar (positioned before "Reference").
145+
When tags are enabled, Great Docs automatically generates a `tags/index.qmd` page that lists every
146+
tag and the pages associated with it. A "Tags" link is added to the site's top navigation bar
147+
(positioned before "Reference").
42148

43-
Each tag becomes a heading on the index page, with links to all pages that use that tag. Section badges (e.g., "User Guide", "Recipes") appear next to each page link so readers can see where the page lives.
149+
Each tag becomes a heading on the index page, with links to all pages that use that tag. Section
150+
badges (e.g., "User Guide", "Recipes") appear next to each page link so readers can see where the
151+
page lives:
152+
153+
<div class="gd-demo-tag-index">
154+
<div style="font-size:1.1rem; font-weight:600; margin-bottom:0.5rem;"><span class="gd-demo-tag-pill">Configuration</span></div>
155+
<div style="padding-left:1.25rem; padding:0.15rem 0 0.15rem 1.25rem;"><a style="color:inherit; text-decoration:underline;">Configuration</a> <span class="gd-demo-section-badge">User Guide</span></div>
156+
<div style="padding-left:1.25rem; padding:0.15rem 0 0.15rem 1.25rem;"><a style="color:inherit; text-decoration:underline;">Advanced Configuration</a> <span class="gd-demo-section-badge">Recipes</span></div>
157+
<div style="font-size:1.1rem; font-weight:600; margin-top:1rem; margin-bottom:0.5rem;"><span class="gd-demo-tag-pill">Getting Started</span></div>
158+
<div style="padding-left:1.25rem; padding:0.15rem 0 0.15rem 1.25rem;"><a style="color:inherit; text-decoration:underline;">Installation</a> <span class="gd-demo-section-badge">User Guide</span></div>
159+
<div style="padding-left:1.25rem; padding:0.15rem 0 0.15rem 1.25rem;"><a style="color:inherit; text-decoration:underline;">Quickstart</a> <span class="gd-demo-section-badge">User Guide</span></div>
160+
</div>
44161

45162
### Disabling the Index Page
46163

@@ -54,7 +171,13 @@ tags:
54171

55172
## Tag Pills on Pages
56173

57-
By default, tagged pages display small pill-shaped links above the page title. Each pill links to the corresponding tag's section on the tags index page. This helps readers discover related content.
174+
By default, tagged pages display small pill-shaped links below the page title. Each pill links to
175+
the corresponding tag's section on the tags index page, helping readers discover related content:
176+
177+
<div class="gd-demo-tag-page-mock">
178+
<div style="font-size:1.5rem; font-weight:700;">Configuration</div>
179+
<div class="gd-demo-tag-pills"><span class="gd-demo-tag-pill">Python</span> <span class="gd-demo-tag-pill">Configuration</span> <span class="gd-demo-tag-pill">Getting Started</span></div>
180+
</div>
58181

59182
To disable the pills while keeping the tags index page:
60183

@@ -66,7 +189,9 @@ tags:
66189

67190
## Tag Location
68191

69-
By default, tag pills appear at the **top** of the page, just below the title (and subtitle, if present). You can move them to the **bottom** of the page instead, where they appear after the page metadata block (dates and author info) or under a horizontal rule if no metadata is present.
192+
By default, tag pills appear at the **top** of the page, just below the title (and subtitle, if
193+
present). You can move them to the **bottom** of the page instead, where they appear after the page
194+
metadata block (dates and author info) or under a horizontal rule if no metadata is present.
70195

71196
Set the default location globally in `great-docs.yml`:
72197

@@ -90,15 +215,20 @@ tag-location: top
90215
---
91216
```
92217

93-
This is useful when most pages use bottom placement but a few key pages benefit from prominent top placement (or vice versa).
218+
This is useful when most pages use bottom placement but a few key pages benefit from prominent top
219+
placement (or vice versa).
94220

95221
::: {.callout-tip}
96-
When tags are placed at the bottom, they are rendered *after* the page metadata (creation/modification dates and author info). If page metadata is not enabled, tags appear at the end of the main content under a horizontal rule.
222+
When tags are placed at the bottom, they are rendered *after* the page metadata
223+
(creation/modification dates and author info). If page metadata is not enabled, tags appear at the
224+
end of the main content under a horizontal rule.
97225
:::
98226

99227
## Hierarchical Tags
100228

101-
Tags support a hierarchy using the `/` separator. For example, `Python/Testing` creates a parent "Python" group with a "Testing" child. On the tags index page, hierarchical tags are rendered with nested headings:
229+
Tags support a hierarchy using the `/` separator. For example, `Python/Testing` creates a parent
230+
"Python" group with a "Testing" child. On the tags index page, hierarchical tags are rendered with
231+
nested headings:
102232

103233
```yaml
104234
---
@@ -120,11 +250,19 @@ This produces an index page structure like:
120250
- Unit Testing Guide
121251
```
122252

123-
On the page itself, hierarchical tag pills display the leaf name (e.g., "Testing") with the full path shown as a tooltip on hover.
253+
On the page itself, hierarchical tag pills display as segmented pills with the parent and leaf
254+
separated by a vertical divider. The full path is shown as a tooltip on hover:
255+
256+
<div class="gd-demo-tag-pills" style="margin:1rem 0;">
257+
<span class="gd-demo-tag-seg"><span class="gd-demo-tag-seg-parent">Python</span><span class="gd-demo-tag-seg-sep">&nbsp;</span><span class="gd-demo-tag-seg-child">Testing</span></span>
258+
<span class="gd-demo-tag-seg"><span class="gd-demo-tag-seg-parent">Python</span><span class="gd-demo-tag-seg-sep">&nbsp;</span><span class="gd-demo-tag-seg-child">pytest</span></span>
259+
<span class="gd-demo-tag-pill">Best Practices</span>
260+
</div>
124261

125262
### Literal Slashes in Tag Names
126263

127-
If a tag name contains a literal `/` that should **not** be treated as a hierarchy separator, escape it with a backslash: `\/`. For example, `AI\/LLM` displays as "AI/LLM" without creating a hierarchy.
264+
If a tag name contains a literal `/` that should **not** be treated as a hierarchy separator, escape
265+
it with a backslash: `\/`. For example, `AI\/LLM` displays as "AI/LLM" without creating a hierarchy.
128266

129267
```yaml
130268
---
@@ -134,7 +272,8 @@ tags: [AI\/LLM, Getting Started]
134272
```
135273

136274
::: {.callout-note}
137-
In YAML, leave the tag unquoted (e.g., `AI\/LLM`) so the backslash is preserved. Double-quoted YAML strings will consume the backslash as an escape character.
275+
In YAML, leave the tag unquoted (e.g., `AI\/LLM`) so the backslash is preserved. Double-quoted YAML
276+
strings will consume the backslash as an escape character.
138277
:::
139278

140279
To disable hierarchical tag support entirely and treat all `/` characters as literal:
@@ -147,9 +286,13 @@ tags:
147286

148287
## Shadow Tags
149288

150-
Shadow tags are tags used for internal organization that are hidden from public view. Pages with shadow tags are still indexed internally, but the tags themselves are not rendered as pills on pages or shown on the tags index page.
289+
Not all tags are meant for readers. Shadow tags let you use the tagging system for internal
290+
organization without exposing those labels publicly. Pages with shadow tags are still indexed
291+
internally, but the tags themselves are not rendered as pills on pages or shown on the tags index
292+
page.
151293

152-
This is useful for editorial workflows. For example one can tag pages as `needs-review` or `draft` without exposing those labels to readers.
294+
This is useful for editorial workflows. For example, you can tag pages as `needs-review` or `draft`
295+
without exposing those labels to readers.
153296

154297
```{.yaml filename="great-docs.yml"}
155298
tags:
@@ -169,11 +312,14 @@ tags: [Configuration, API, needs-review]
169312
---
170313
```
171314

172-
In this example, "Configuration" and "API" appear as pills and on the index page, while "needs-review" is silently ignored in the public output.
315+
In this example, "Configuration" and "API" appear as pills and on the index page, while
316+
"needs-review" is silently ignored in the public output.
173317

174318
## Tag Icons
175319

176-
You can associate tags with icons from the [Lucide](https://lucide.dev/icons/) icon set (the same icon set used by `nav_icons`). Icons appear inside the tag pill and next to the tag heading on the index page.
320+
You can associate tags with icons from the [Lucide](https://lucide.dev/icons/) icon set (the same
321+
icon set used by `nav_icons`). Icons appear inside the tag pill and next to the tag heading on the
322+
index page.
177323

178324
```{.yaml filename="great-docs.yml"}
179325
tags:
@@ -185,7 +331,8 @@ tags:
185331
Testing: flask-conical
186332
```
187333

188-
The icon names are Lucide icon names (lowercase, hyphenated). Browse the full catalogue at [lucide.dev/icons](https://lucide.dev/icons/).
334+
The icon names are Lucide icon names (lowercase, hyphenated). Browse the full catalogue at
335+
[lucide.dev/icons](https://lucide.dev/icons/).
189336

190337
## Full Configuration Reference
191338

@@ -213,19 +360,30 @@ Great Docs scans for tags in `.qmd` files found in:
213360
- **Recipes** pages (`recipes/`)
214361
- **Custom sections** (any section defined in `sections:` config)
215362

216-
Index pages (`index.qmd`) in these directories are skipped. API reference pages and the changelog are not scanned for tags.
363+
Index pages (`index.qmd`) in these directories are skipped. API reference pages and the changelog
364+
are not scanned for tags.
217365

218366
## Tips
219367

220-
- **Start simple**: begin with a flat list of 5–10 tags and add hierarchy later as your documentation grows.
368+
A few guidelines help keep your tag system useful as your documentation grows.
369+
370+
- **Start simple**: begin with a flat list of 5-10 tags and add hierarchy later as your
371+
documentation grows.
221372
- **Be consistent**: establish a tag naming convention early (e.g., always use title case).
222-
- **Use shadow tags for workflow**: tags like `needs-update` or `v2-migration` help you track editorial tasks without cluttering the reader experience.
223-
- **Combine with search**: tags improve discoverability today, and will integrate with enhanced search in a future release.
373+
- **Use shadow tags for workflow**: tags like `needs-update` or `v2-migration` help you track
374+
editorial tasks without cluttering the reader experience.
375+
- **Combine with search**: tags improve discoverability today, and will integrate with enhanced
376+
search in a future release.
224377

225378
## Next Steps
226379

227-
Tags give readers a second way to navigate your documentation, organized by topic rather than page order. Start with a small set of well-chosen tags and expand as your content grows.
380+
Tags give readers a second way to navigate your documentation, organized by topic rather than page
381+
order. Start with a small set of well-chosen tags and expand as your content grows.
228382

229-
- [Page Status Badges](page-status-badges.qmd) adds lifecycle indicators (new, updated, deprecated) to pages
230-
- [Custom Sections](custom-sections.qmd) covers organizing pages into named groups with sidebar navigation
383+
- [Page Status Badges](page-status-badges.qmd) adds lifecycle indicators (new, updated, deprecated)
384+
to pages
385+
- [Custom Sections](custom-sections.qmd) covers organizing pages into named groups with sidebar
386+
navigation
387+
- [Internationalization](internationalization.qmd) covers language support for tag-related UI
388+
elements
231389
- [Configuration](configuration.qmd) covers all tag settings in `great-docs.yml`

0 commit comments

Comments
 (0)