Writing Pages — Sourcey

Every documentation page is a markdown file with YAML frontmatter. Sourcey handles the rest: syntax highlighting, heading anchors, table of contents, and responsive layout.

Frontmatter

Each page starts with a YAML block between --- markers.

---
title: Getting Started
description: Install and configure your first project.
---

Page content starts here.

Field	Required	Purpose
`title`	Yes	Page heading, sidebar label, and search result title
`description`	No	SEO meta description and search result snippet

Tip

Write descriptive titles and descriptions. They appear in the sidebar navigation and in search results; good metadata makes your docs navigable at a glance.

Headings

Standard markdown headings work as expected. Sourcey extracts h2 and h3 headings for the table of contents sidebar.

## Section Heading (appears in TOC)

### Subsection Heading (also appears in TOC)

#### Deeper headings (not in TOC, still rendered)

If your first heading is an h1 that matches the title in frontmatter, sourcey strips it to avoid duplication. The title from frontmatter is always rendered as the page heading.

Code blocks

Fenced code blocks get syntax highlighting via Shiki. Specify the language after the opening backticks.

```typescript
const config = defineConfig({
  name: "My Docs",
});
```

Shiki supports most languages out of the box: TypeScript, JavaScript, Python, Go, Rust, Ruby, Java, PHP, C, C++, Bash, JSON, YAML, and many more.

Standard markdown

All standard markdown features work as expected:

Bold and italic text
Links (external links open in a new tab)
Ordered and unordered lists
Tables with standard pipe syntax
Inline code and block code
Images via ![alt](url)
Blockquotes via >

Rich components

Beyond standard markdown, sourcey supports directives for richer content: callouts, steps, tabs, code groups, cards, and accordions. See the Components page for the full reference.