Categories, icons, and ordering
Categories are the sidebar's spine. Each one needs a label, an icon, a position, and a one-line description. Get those four right and the sidebar reads itself.
Picking icons
Docsio uses Phosphor icons — there are about 1500 of them, in six weights. We use regular weight site-wide for sidebar categories.
Rules of thumb:
- The icon should hint at the category, not duplicate it. "Editor" + a pencil icon = good. "Editor" + a literal "ED" letterform = redundant.
- Avoid icons with thin strokes. They blur at the 14–16px size we render at. Stick with solid or chunky outline icons.
- Visually distinct icons. "Wrench" and "screwdriver" both mean "settings"; using both confuses readers. Pick one and use it for the meaning.
A short list of icons we use often, with the meaning we've settled on:
| Phosphor icon | We use it for |
|---|---|
rocket | Getting started, onboarding |
pencil-simple | The editor, writing, content |
paint-brush | Branding, theming, colors |
rocket-launch | Publishing, deployment, releasing |
git-branch | Version control, GitHub, repos |
plug | Integrations, MCP, embeds |
sparkle | AI features |
users-three | Team, permissions, collaboration |
chart-bar / chart-line | Analytics, dashboards |
book-open | Reference, technical detail |
lifebuoy | Help, support, troubleshooting |
magnifying-glass | Search |
Ordering categories
The default Docsio order is roughly: setup → use → ship → operate → reference → help. That's the journey a new user takes through your product. Don't shuffle into an alphabetical or arbitrary order — readers don't have your mental model of the codebase.
For a SaaS docs site, order looks like:
- Get started
- The product itself (editor, dashboard, whatever the core surface is)
- Branding / customization
- Integrations
- Plans / billing
- Reference
- Help / FAQ
Adjust as appropriate, but resist the urge to lead with billing or with the most "advanced" feature.
One-line category descriptions
Every category gets a description in _category_.json. It's used:
- On the auto-generated category index page.
- In the in-page search results.
- In
llms.txtfor AI assistants.
Aim for ~20 words. Promise what's inside, don't sell it. Example:
"Connect any GitHub repo. Edits in Docsio commit on publish; pushes to your branch rebuild your site automatically. Two-way sync, free on every plan."
That tells a reader: this category is about GitHub Sync, what it does, and that they can read it without paywalls. That's the work you want the description to do.
What we don't do
- We don't have an "Other" or "Misc" category. If a page doesn't fit somewhere, the page is the problem, not the structure.
- We don't make the sidebar emoji-heavy. Phosphor icons are cleaner across themes; emoji rendering varies wildly across operating systems.
- We don't show a sidebar icon and the category label having different colors. Pick one or the other.