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`
`search`	When `false`, hides the header search control on this page
`timestamp`	Overrides site-wide `metadata.timestamp` — `true` shows last-updated, `false` hides it
`related`	Pages listed under "Related topics" at the bottom of the page

List related pages in frontmatter to render a "Related topics" section above the previous/next links. Entries are page paths — titles come from the page — or objects with an explicit title (required for external URLs):

---
title: Navigation
related:
  - /docs/site-details
  - href: /docs/components
    title: Components overview
  - href: https://example.com/spec
    title: External specification
---

Internal paths that don't match a page are skipped, so moved or deleted pages never leave dead links.

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, Tables, Images, and Code for Markdown details.

Built-in components#

Shiso injects docs components into every page — no imports required: Tabs, Callout, Note, Card, Steps, CodeGroup, PropertiesTable.Row, 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 Sep 5, 2026

Edit this page

PreviousTroubleshooting NextText