Zum Hauptinhalt springen

Naming pages and categories

Naming feels low-stakes until you have 60 pages and three of them are called "Overview". Then it's the difference between a docs site that's searchable and one that isn't. Some rules that hold up.

Page titles

The page title is in the frontmatter, in the browser tab, and in search results. It also feeds into your llms.txt.

  • Sentence case, not Title Case. "Configure your custom domain", not "Configure Your Custom Domain".
  • Verb-first when teaching, noun-first when referencing. "Set up GitHub Sync" (a guide) vs "GitHub Sync overview" (reference).
  • Don't end with a period. Page titles aren't sentences.
  • Avoid version numbers in titles. Put them in the page body or a versioned folder.

The sidebar label can differ from the page title — sidebar_label in frontmatter overrides it. Use this when:

  • The page title is long and the sidebar gets cluttered. Page title: "Configure your custom domain with automatic SSL". Sidebar label: "Custom domains".
  • The page is referenced from multiple categories. Slightly different sidebar labels can help disambiguate.

Don't use it to be cute. The sidebar label should be a noun or short noun phrase that matches what the reader expects to find under that category.

Slugs

Slugs become URLs. Choose carefully — changing them later means redirects (or, worse, broken inbound links).

  • Lowercase, hyphen-separated, no underscores.
  • Match the page title's intent, but shorter. "Configure your custom domain" → custom-domains.
  • Don't include the parent category. Slug publishing/custom-domains already implies category from the folder.
  • Avoid stop words ("the", "a", "to", "for") unless removing them creates ambiguity.

In Docsio, slugs come from the file name and folder structure by default. Override with the slug frontmatter field:

---
title: "Configure your custom domain"
slug: /publishing/custom-domains
---

Naming categories

Categories are containers, so they're nouns:

  • Editor, not "Editing"
  • Branding, not "How to brand"
  • Publishing, not "Publish"
  • Team, not "Working with your team"

Resist the urge to over-explain. The category description in _category_.json is the place for nuance — the label is a one-word signpost.

Avoid these patterns

  • "Introduction" in three different categories. Pick a more specific name for at least two of them.
  • "Advanced" as a sidebar label. Most readers don't know if they're "advanced" yet. Be specific: "Custom CSS", "Webhooks", "API rate limits".
  • The word "Overview" by itself. "GitHub Sync overview", "Editor overview" — fine. Just "Overview" — vague.
  • Trailing parentheticals. "Custom domains (Pro)" in the title — strip the parenthetical, mark Pro-only via the <span className="pro-tag">Pro</span> component on the page itself.

When you're stuck

Ask the agent:

What pages on our site have ambiguous names that could be clearer?

The agent walks the sidebar, looks at frontmatter, and surfaces patterns you've stopped seeing.