Skip to main content

Frontmatter

Every Docsio page begins with a YAML frontmatter block. It controls the page's title, position in the sidebar, meta description, slug, and optional icon.

Minimum required

---
title: My page title
---

That's it. Title is the only required field; everything else has sensible defaults.

Common fields

---
title: Quickstart
sidebar_position: 1
description: "Get up and running in five minutes."
slug: /quickstart
sidebar_custom_props:
  icon: rocket
---

Field reference

title (required)

Used as the page's <h1> and as the sidebar label.

title: API Reference

Order in the sidebar within its category. Lower numbers come first.

sidebar_position: 2

If omitted, pages sort alphabetically by filename.

description

Used as the page's <meta name="description"> and in social previews. Aim for 140-160 characters.

description: "How to authenticate against the Acme API using API keys, OAuth 2.0, or short-lived JWTs."

If omitted, search engines will use a snippet from the first paragraph.

slug

Override the URL path. Default: derived from the file path.

slug: /api-auth

docs/api/auth.md would normally be /docs/api/auth. Setting slug: /api-auth makes it /api-auth instead. Useful for short, memorable URLs.

Override the sidebar label without changing the page title.

title: API Reference: Authentication
sidebar_label: Authentication

The page's <h1> is the long form; the sidebar shows the short form.

Add a class to the sidebar item. The most common use:

sidebar_class_name: hidden

Hides the page from the sidebar but keeps it accessible at its URL. Useful for landing pages, deep links, or in-progress drafts.

Custom properties used by the theme. Most commonly:

sidebar_custom_props:
  icon: rocket

The icon shows next to the page in the sidebar. Use any Phosphor icon name (e.g. rocket, book-open, git-branch, lock).

keywords

Custom keywords for SEO meta tags. Comma-separated string or array.

keywords: ["api", "authentication", "oauth"]

image

Custom social preview image for this page. Defaults to your project's logo.

image: /img/api-auth-banner.png

draft

Hides the page from the sidebar AND from search. Useful for in-progress pages.

draft: true

(Different from sidebar_class_name: hidden — that hides only from sidebar but stays searchable. draft: true hides everywhere.)

pagination_prev and pagination_next

Override the prev/next links at the bottom of the page (which default to the previous and next pages in the sidebar).

pagination_prev: getting-started/quickstart
pagination_next: api/auth

Use the file path (without .md) of the target page.

Category metadata

Categories (folders) have their own metadata in _category_.json:

{
  "label": "Getting Started",
  "position": 1,
  "customProps": { "icon": "rocket" },
  "link": {
    "type": "generated-index",
    "description": "Start here. Five minutes to a published docs site."
  }
}

→ Sidebar configuration

Tips

  • Keep titles tight. "Get started" is better than "Getting started: a comprehensive guide to onboarding."
  • Description matters for SEO. Both Google and the AI chat widget use it.
  • Set sidebar_position for any page where ordering matters. Don't rely on alphabetical for important sequences (Quickstart → Configuration → Examples).
  • Pick icons that match the page's role. Phosphor has 1500+ icons. Browse phosphoricons.com.