Writing content

Overview

File format, frontmatter fields, MDX components, and organization.

Write docs as .mdx (or .md) files under content/docs and list each page in docs.json navigation.

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 `<title>` tag
`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, GFM (tables, task lists, strikethrough), and React components inline:

<Note>
  You can mix Markdown and components in the same page.
</Note>

See Text, Lists, Images, and Code blocks for Markdown 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:

<Card title="Installation" icon="rocket" />

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 (# permalink on each heading)
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.mdx → /docs/components/tabs)
keep slugs stable; when a page must move, add a redirect

Last updated on Aug 8, 2026

Troubleshooting Text