Make your docs useful to someone who isn't you
A published page is a start. Your customer also needs to find the right page, understand the words on it, and know what to do next.
This tutorial adds structure, search, and definitions to the Slot docs from part one. Keep working in that project. The finished example includes everything shown here.
1. Separate the first task from the lookups
The guide already helps someone retrieve a booking. Two questions deserve their own pages: how to authenticate and what the returned status means.
Create docs/authentication.md:
---
title: Authentication
---
The local demo accepts one bearer token: `demo-key`.
```http
Authorization: Bearer demo-key
```
Include this header on every request. A missing or different token returns HTTP `401`.
This public token only unlocks the local fixture. Real credentials belong in your application's server-side configuration.
Create docs/booking-statuses.md:
---
title: Booking statuses
---
A booking has one of these statuses:
| Status | Meaning |
| ----------- | ------------------------------------------------------- |
| `pending` | The booking has been requested and isn't confirmed yet. |
| `confirmed` | The booking is confirmed. |
| `canceled` | The booking has been canceled. |
The demo returns a confirmed booking. It doesn't implement transitions between states.
HTTP `200` means the lookup succeeded. Read the status field to determine the booking's state.
At the end of docs/find-a-booking.md, add links to both pages:
Read [Authentication](./authentication.md) if the request returns `401`.
See [Booking statuses](./booking-statuses.md) for the meaning of each state.
The tutorial remains a short route to a result. The lookup pages answer questions readers return with later. You don't need a separate page for every heading, but these two have independent uses.
2. Name the navigation after the work
Replace sidebars.ts:
import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
const sidebars: SidebarsConfig = {
guides: [
'intro',
{
type: 'category',
label: 'Start building',
items: ['find-a-booking', 'authentication'],
},
'booking-statuses',
],
};
export default sidebars;
Add links to the new pages in docs/intro.md too:
- [Authentication](./authentication.md): send the demo token with a request.
- [Booking statuses](./booking-statuses.md): understand the returned state.
“Find a booking” tells a reader what a page helps them do. Your internal service names and team boundaries rarely make good navigation labels. Use the words customers bring to the task.
3. Add search without a search account
Install the local search theme:
npm install --save-exact @easyops-cn/docusaurus-search-local@0.55.3
In docusaurus.config.ts, add themes alongside presets:
themes: [
[
'@easyops-cn/docusaurus-search-local',
{ hashed: true, indexBlog: false, docsRouteBasePath: '/' },
],
],
If your configuration already has a themes array, add this entry to it. docsRouteBasePath matches the / route configured in part one. The theme builds an index from the site's content, and the browser searches it. See the project's setup documentation for its options.
Check search against a production build. A development server doesn't generate the finished search index:
npm run build
npm run serve
Search for booking, confirmed, and bearer. Open a result and check that it reaches the expected page. Try the search field with a keyboard and at a phone-sized width.
This removes a hosted search dependency. The index still has to be generated and downloaded, so watch its size as the site grows. Choose a different approach if the customer's experience calls for one.
4. Explain the terms in place
The authentication page uses “bearer token.” A reader can follow the curl command without knowing the phrase, but a short definition helps them understand what they're sending.
I built docusaurus-plugin-glossary to add these explanations without manually marking every occurrence. Install it:
npm install --save-exact docusaurus-plugin-glossary@3.4.0
mkdir glossary
Create glossary/glossary.json:
{
"title": "Glossary",
"description": "Terms used in the Slot example.",
"terms": [
{
"term": "API",
"definition": "An interface that software uses to make requests to another system."
},
{
"term": "bearer token",
"definition": "A credential sent in the Authorization header. Anyone who has it can use it."
}
]
}
In your existing presets array, replace 'classic' with 'docusaurus-plugin-glossary/preset'. Keep the docs and blog options from part one, and add glossary:
presets: [
[
'docusaurus-plugin-glossary/preset',
{
docs: { routeBasePath: '/', sidebarPath: './sidebars.ts' },
blog: false,
glossary: {
glossaryPath: 'glossary/glossary.json',
routePath: '/glossary',
},
},
],
],
This preset wraps the classic preset and wires up the glossary. Replace the existing preset; don't run both. Keep the search themes entry alongside it.
Replace the minimal themeConfig from part one with:
themeConfig: {
navbar: {
title: 'Slot docs',
items: [
{ to: '/', label: 'Guides', position: 'left' },
{ to: '/glossary', label: 'Glossary', position: 'left' },
],
},
},
Rebuild the site. Open /authentication/ and inspect “bearer token,” then follow its link to the full definition at /glossary. The glossary has its own term search. It complements the site search you installed above.
With these pinned versions, Docusaurus can warn about /glossary/#... anchors even though the generated glossary contains the definitions. Check the rendered term links. Keep the broken-link checks enabled so other missing pages still fail the build.
Define unfamiliar product language as well as generic technical terms. If a term needs a paragraph of conditions, link to a page that explains it. A tooltip shouldn't carry an entire concept.
5. Watch another person use it
Give someone the homepage and ask them to find the demo booking. Let them work without explaining the navigation. Note where they hesitate, what they search for, and whether they recognize success.
Fix the first point where the page leaves them guessing. A missing prerequisite can matter more than a new component or a longer explanation.
Before you publish, check that the original curl request still works, search finds the new pages, glossary definitions appear, and links survive a direct page refresh. Commit the content, configuration, and updated lockfile, then push to deploy.
Cost and maintenance
Search and glossary data ship with the static site. Neither needs a separate hosted service in this setup. Your hosting limits still apply, and someone needs to maintain the definitions and check search results as the content changes.