You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Great Docs lets you mark pages with a lifecycle status such as "New", "Beta", or "Deprecated". Status badges appear as colored indicators in two places:
11
+
Documentation pages have a lifecycle. Some pages describe brand-new features, others cover APIs that
12
+
are experimental and subject to change, and some document capabilities that are being phased out.
13
+
Communicating this status helps readers set expectations before they invest time in a page.
14
+
15
+
Great Docs lets you mark pages with a lifecycle status such as "New", "Beta", or "Deprecated".
16
+
Status badges appear as colored indicators in two places:
12
17
13
18
1.**Below the page title**: a full badge with icon, label, and description
14
19
2.**In sidebar navigation**: a compact icon next to the link, with a tooltip on hover
15
20
16
-
Status badges are disabled by default. To enable them, add a `page_status` section to `great-docs.yml`:
21
+
Status badges are disabled by default. To enable them, add a `page_status` section to
22
+
`great-docs.yml`:
17
23
18
24
```{.yaml filename="great-docs.yml"}
19
25
page_status:
@@ -37,11 +43,13 @@ status: deprecated
37
43
---
38
44
```
39
45
40
-
The value must match one of the defined status keys (see below). Pages without a `status` key display no badge.
46
+
The value must match one of the defined status keys (see below). Pages without a `status` key
47
+
display no badge.
41
48
42
49
## Built-in Statuses
43
50
44
-
Great Docs ships with five built-in statuses, each with a [Lucide](https://lucide.dev/icons/) icon, color, and description:
51
+
Great Docs ships with five built-in statuses, each with a [Lucide](https://lucide.dev/icons/) icon,
@@ -51,10 +59,76 @@ Great Docs ships with five built-in statuses, each with a [Lucide](https://lucid
51
59
|`deprecated`| Deprecated |`triangle-alert`| Red | May be removed in a future release |
52
60
|`experimental`| Experimental |`beaker`| Purple | API may change without notice |
53
61
54
-
All built-in status labels and descriptions are automatically translated when the site uses a non-English language (see [Internationalization](internationalization.qmd)).
62
+
Here is how these five statuses look as page-level badges:
<divclass="gd-demo-badge"style="color:#ef4444; background:rgba(239,68,68,0.08); border:1pxsolidrgba(239,68,68,0.25);"><spanclass="gd-demo-lbl">⚠ Deprecated</span> <spanclass="gd-demo-dsc">— May be removed in a future release</span></div>
123
+
<divclass="gd-demo-badge"style="color:#8b5cf6; background:rgba(139,92,246,0.08); border:1pxsolidrgba(139,92,246,0.25);"><spanclass="gd-demo-lbl"><svgxmlns="http://www.w3.org/2000/svg"width="12"height="12"viewBox="0 0 24 24"fill="none"stroke="currentColor"stroke-width="2"stroke-linecap="round"stroke-linejoin="round"aria-hidden="true"><pathd="M4.5 3h15"></path><pathd="M6 3v16a2 2 0 0 0 2 2h8a2 2 0 0 0 2-2V3"></path><pathd="M6 14h12"></path></svg> Experimental</span> <spanclass="gd-demo-dsc">— API may change without notice</span></div>
124
+
</div>
125
+
126
+
All built-in status labels and descriptions are automatically translated when the site uses a
127
+
non-English language (see [Internationalization](internationalization.qmd)).
55
128
56
129
## Custom Statuses
57
130
131
+
The five built-in statuses cover common lifecycle stages, but your team may have its own workflow.
58
132
You can add your own statuses or override built-in ones via the `statuses` map in `great-docs.yml`:
59
133
60
134
```{.yaml filename="great-docs.yml"}
@@ -82,9 +156,10 @@ Each custom status definition accepts:
82
156
|`color`| string | No | CSS color for the badge (defaults to `#6b7280`) |
83
157
|`description`| string | No | Short explanation shown on the page badge and as a tooltip |
84
158
85
-
Custom statuses use their literal `label` and `description` values in all languages. Only the five built-in statuses are translated automatically.
159
+
Custom statuses use their literal `label` and `description` values in all languages. Only the five
160
+
built-in statuses are translated automatically.
86
161
87
-
Then use the custom key in frontmatter:
162
+
Use the custom key in frontmatter just like a built-in status:
88
163
89
164
```{.yaml filename="user_guide/10-new-api.qmd"}
90
165
---
@@ -95,7 +170,8 @@ status: draft
95
170
96
171
## Overriding Built-in Statuses
97
172
98
-
To change a built-in status (for example, switching the icon or color for `deprecated`), redefine it in `statuses`:
173
+
To change a built-in status (for example, switching the icon or color for `deprecated`), redefine
174
+
it in `statuses`:
99
175
100
176
```{.yaml filename="great-docs.yml"}
101
177
page_status:
@@ -108,11 +184,13 @@ page_status:
108
184
description: "Superseded by a newer approach"
109
185
```
110
186
111
-
Your definition fully replaces the built-in default for that key.
187
+
Your definition fully replaces the built-in default for that key. Any fields you omit fall back to
188
+
their defaults (gray color, title-cased label, no icon).
112
189
113
190
## Controlling Where Badges Appear
114
191
115
-
By default, badges are shown both below page titles and in the sidebar. You can disable either location independently:
192
+
By default, badges are shown in both locations. You can disable either one independently if you
193
+
prefer a subtler approach.
116
194
117
195
### Sidebar Only
118
196
@@ -136,23 +214,28 @@ page_status:
136
214
137
215
### On the Page
138
216
139
-
The page-level badge appears directly below the title (and subtitle, if present). It displays the status icon, label, and description in the status color:
217
+
The page-level badge appears directly below the title (and subtitle, if present). It displays the
218
+
status icon, label, and description in the status color:
Sidebar links for pages with a status show a small colored icon after the link text. Hovering over the icon displays a tooltip with the full label and description:
228
+
Sidebar links for pages with a status show a small colored pill after the link text. Hovering over
229
+
the pill displays a tooltip with the full label and description:
150
230
151
-
```
152
-
▸ Getting Started ✦ ← icon with tooltip
153
-
▸ Migration Guide ⚠
154
-
▸ Configuration
155
-
```
231
+
<divclass="gd-demo-sidebar-list">
232
+
<divclass="gd-demo-sidebar-item">Getting Started <spanclass="gd-demo-sidebar-pill"style="color:#10b981; background:rgba(16,185,129,0.1);"title="New — Recently added">✦</span></div>
233
+
<divclass="gd-demo-sidebar-item">Migration Guide <spanclass="gd-demo-sidebar-pill"style="color:#ef4444; background:rgba(239,68,68,0.1);"title="Deprecated — May be removed in a future release">⚠</span></div>
<divclass="gd-demo-sidebar-item">New API Design <spanclass="gd-demo-sidebar-pill"style="color:#8b5cf6; background:rgba(139,92,246,0.1);"title="Experimental — API may change without notice"><svgxmlns="http://www.w3.org/2000/svg"width="11"height="11"viewBox="0 0 24 24"fill="none"stroke="currentColor"stroke-width="2"stroke-linecap="round"stroke-linejoin="round"aria-hidden="true"><pathd="M4.5 3h15"></path><pathd="M6 3v16a2 2 0 0 0 2 2h8a2 2 0 0 0 2-2V3"></path><pathd="M6 14h12"></path></svg></span></div>
236
+
</div>
237
+
238
+
Pages without a status display no indicator, keeping the sidebar clean.
156
239
157
240
## Which Pages Are Scanned?
158
241
@@ -162,7 +245,8 @@ Great Docs scans for `status` frontmatter in `.qmd` files found in:
162
245
-**Recipes** pages (`recipes/`)
163
246
-**Custom sections** (any section defined in `sections:` config)
164
247
165
-
API reference pages, the changelog, and index pages are not scanned.
248
+
API reference pages, the changelog, and index pages are not scanned. This keeps badges focused on
249
+
content pages where lifecycle status is meaningful.
166
250
167
251
## Full Configuration Reference
168
252
@@ -203,15 +287,23 @@ page_status:
203
287
204
288
## Tips
205
289
206
-
-**Use statuses sparingly**: a page should carry a status only when it communicates something actionable. If every page is "New", the badge loses its value.
207
-
-**Remove stale statuses**: revisit `status: new` and `status: updated` periodically and remove them once the content is no longer recent.
208
-
-**Combine with tags**: statuses and tags serve different purposes. Tags categorize content by topic; statuses communicate lifecycle. A page can have both.
209
-
-**Custom statuses for workflows**: define statuses like `draft` or `review` to track editorial progress while keeping the documentation published.
290
+
A few guidelines help keep status badges effective across your documentation.
291
+
292
+
-**Use statuses sparingly**: a page should carry a status only when it communicates something
293
+
actionable. If every page is "New", the badge loses its value.
294
+
-**Remove stale statuses**: revisit `status: new` and `status: updated` periodically and remove
295
+
them once the content is no longer recent.
296
+
-**Combine with tags**: statuses and tags serve different purposes. Tags categorize content by
297
+
topic; statuses communicate lifecycle. A page can have both.
298
+
-**Custom statuses for workflows**: define statuses like `draft` or `review` to track editorial
299
+
progress while keeping the documentation published.
210
300
211
301
## Next Steps
212
302
213
-
Status badges communicate lifecycle information at a glance. They work best when used selectively for pages that are genuinely new, recently updated, or approaching deprecation.
303
+
Status badges communicate lifecycle information at a glance. They work best when used selectively
304
+
for pages that are genuinely new, recently updated, or approaching deprecation.
214
305
215
306
-[Page Tags](page-tags.qmd) categorizes pages by topic with filterable tag listings
216
307
-[API Evolution](api-evolution.qmd) tracks changes across releases at the API level
308
+
-[Internationalization](internationalization.qmd) covers how built-in badge labels are translated
217
309
-[Configuration](configuration.qmd) covers all status badge settings in `great-docs.yml`
0 commit comments