Aller au contenu principal

Pages and categories

Your docs are organized as folders. Each folder is a sidebar category. Each markdown file inside is a page.

File structure

docs/
├── intro.md                                  → /docs/intro
├── getting-started/
│   ├── _category_.json                       → category metadata
│   ├── quickstart.md                         → /docs/getting-started/quickstart
│   └── installation.md
├── features/
│   ├── _category_.json
│   └── search.md
└── api/
    ├── _category_.json
    └── reference.md

Adding a page

The easiest way: ask the agent.

"Add a page on rate limits under API Reference."

The agent creates the file, sets the right frontmatter, places it in the sidebar, and you see it in the live preview within seconds.

If you prefer to do it manually: create a new file in the right folder. The sidebar updates automatically. See Markdown reference for the page format.

Categories (folders)

A category is a folder containing pages. Every category needs a _category_.json file at its root with at least:

{
  "label": "API Reference",
  "position": 3
}
  • label — what shows in the sidebar.
  • position — order among other categories.

Optional fields:

  • customProps.icon — Phosphor icon name (e.g. "sparkle", "rocket", "plug"). Renders next to the category label.
  • link.type: "generated-index" and link.description — auto-generates a category landing page.
  • collapsed: true — start collapsed in the sidebar.

See Sidebar configuration for the full schema.

Reordering

Two ways:

  • Drag in the sidebar — drag pages or categories up/down. Saved instantly.
  • Edit sidebar_position in frontmatter for pages, or position in _category_.json for categories.

Lower numbers come first. If you don't set positions, items sort alphabetically.

Renaming

Rename a page or category from the sidebar — right-click → Rename. The slug (URL path) updates and Docsio fixes any internal links automatically.

If you want the slug to differ from the filename (e.g. file is intro.md but URL should be /welcome), set the slug frontmatter:

---
title: Welcome
slug: /welcome
---

Deleting

Right-click → Delete. Pages can be restored from the project's version history (Pro) for up to 90 days.

Common patterns

  • Single-page section. A category with one page is a flat sidebar item with no sub-items.
  • Section overview. Set link.type: "generated-index" on the category — Docsio writes a landing page automatically.
  • Hidden pages. Set sidebar_class_name: "hidden" in frontmatter to hide a page from the sidebar but keep it accessible at its URL (useful for deep-link landing pages).