Writing content overview
File format#
Each page usually starts with YAML frontmatter:
---
title: "Title of page"
description: "Optional description"
---
Welcome to Shiso.Frontmatter fields#
| Field | Purpose |
|---|---|
title |
Page heading, sidebar fallback label, and browser tab title |
description |
Intro text under the title and meta description |
noindex |
When true, marks the page noindex and excludes it from sitemap.xml |
timestamp |
Overrides site-wide metadata.timestamp — true shows last-updated, false hides it |
Markdown and MDX#
Pages support standard Markdown, GitHub-flavored Markdown (tables, task lists, strikethrough), and React components inline. See Text, Images, and Code blocks for details.
Built-in components#
Shiso injects docs components into every page — no imports required: Tabs, Callout, Note, Card, Steps, CodeGroup, ResponseField, and more. Browse the full set under Components.
Icons#
Components with an icon prop (and icon fields in docs.json) take names from the lucide set. Names are collected from your content at build time, so an icon resolves as soon as it appears in a source file.
Heading anchors and right rail#
Heading IDs are generated for in-page anchor links and the right-side "On this page" outline. Use clear heading text so anchors stay readable and stable.
File organization#
- one concept per page
- nested folders become nested routes —
components/tabs.mdxbecomes/docs/components/tabs - keep slugs stable; when a page must move, add a redirect
Back to Introduction.