Markdown Reference

Every feature listed here is enabled by default in @pagesmith/core. No configuration or additional plugins are required unless noted otherwise.

GitHub Flavored Markdown

Enabled via remark-gfm. All GFM extensions are available out of the box.

Tables

1| Feature       | Syntax        |2| ------------- | ------------- |3| Bold          | `**bold**`    |4| Italic        | `*italic*`    |5| Strikethrough | `~~deleted~~` |

Alignment is controlled by colons in the separator row:

1| Left | Center | Right |2| :--- | :----: | ----: |3| text |  text  |  text |

Strikethrough

1~~removed text~~

Task Lists

1- [x] Completed task2- [ ] Pending task3- [ ] Another todo

Autolinks

Bare URLs are automatically converted to clickable links:

1Visit https://example.com for details.

Footnotes

1This claim needs a source[^1].23[^1]: The source for this claim.

The footnote content renders at the bottom of the page with a back-link.

GitHub Alerts

Five alert types are available using blockquote syntax. This is the same format used by GitHub itself.

1> [!NOTE]2> Useful information the reader should know.34> [!TIP]5> Helpful advice for doing things better.67> [!IMPORTANT]8> Key information the reader must not miss.910> [!WARNING]11> Something that needs immediate attention.1213> [!CAUTION]14> Negative potential consequences of an action.

Math

LaTeX math is processed by remark-math (parsing) and rehype-mathjax (SVG rendering). remark-math only runs when markdown.math is true or when the default 'auto' mode detects math markers in the page. MathJax runs before the built-in code renderer so math blocks are not mistakenly treated as code.

Inline Math

Wrap expressions in single dollar signs:

1The equation $E = mc^2$ changed physics.

Display Math

Wrap expressions in double dollar signs for centered block equations:

1$$2\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}3$$

Smart Typography

ASCII punctuation is automatically upgraded to proper typographic characters by remark-smartypants. Code blocks and inline code are never affected.

External Links

Any link pointing to an absolute URL (http:// or https://) automatically receives target="_blank" and rel="noopener noreferrer". Internal links (relative paths, anchors) are unaffected.

1[External](https://example.com) <!-- new tab, noopener -->2[Internal](../../guide/getting-started/README.md) <!-- same tab -->3[Anchor](#math) <!-- same tab -->

Images

All markdown images are automatically wrapped in <figure class="ps-figure ps-figure-zoomable"> and given a hidden expand button (<button class="ps-img-zoom-btn" hidden data-ps-img-zoom-btn>). Raster images (PNG, JPEG, WebP, GIF) also get a <picture> element with WebP and AVIF <source> variants. SVG images get figure wrapping but no <picture> element. Images inside links are not figure-wrapped and do not receive a zoom button. The image carries data-zoom-src (raster → <stem>.zoom.webp, SVG → original src); themed light/dark pairs carry data-zoom-src-light / data-zoom-src-dark. Pair with @pagesmith/site/runtime/image-zoom for the modal.

The title attribute from markdown syntax becomes a <figcaption>:

1![Dashboard metrics](./hero.png "Production monitoring dashboard")

Produces:

1<figure class="ps-figure ps-figure-zoomable">2  <picture>3    <source srcset="./hero.avif" type="image/avif" />4    <source srcset="./hero.webp" type="image/webp" />5    <img6      src="./hero.webp"7      alt="Dashboard metrics"8      width="..."9      height="..."10      data-zoom-src="./hero.zoom.webp"11      data-zoom-type="image/webp"12    />13  </picture>14  <figcaption>Production monitoring dashboard</figcaption>15  <button type="button" class="ps-img-zoom-btn" hidden data-ps-img-zoom-btn>...</button>16</figure>

Automatic Light/Dark Pair Merging

Consecutive images whose filenames end with -light and -dark suffixes are automatically merged into a single themed figure. No manual HTML is needed:

1![Architecture overview](./diagrams/arch-light.svg)2![Architecture overview](./diagrams/arch-dark.svg)

Produces a <figure class="ps-figure ps-figure-themed ps-figure-zoomable"> with <source media="(prefers-color-scheme: dark)"> so the correct variant displays without JavaScript. The inner <img> carries data-zoom-src-light and data-zoom-src-dark so the zoom modal swaps source on theme change.

Theme-Aware Images

Images and other elements can respond to the active color scheme. The pipeline handles figure wrapping and light/dark pairing automatically for markdown images (see above). Prefer markdown image syntax over raw HTML for all images.

Light/dark image pairs

Place light and dark variants consecutively using standard markdown images. The pipeline auto-merges them:

1![Architecture overview](./diagrams/arch-light.svg "Build pipeline architecture")2![Architecture overview](./diagrams/arch-dark.svg)

The title on the first (light) image becomes the <figcaption>. In color-scheme-auto (the default), the switch follows the OS preference. In explicit light or dark mode, the matching variant is forced.

Generic show/hide helpers

1<span class="show-on-light">Light content</span> <span class="show-on-dark">Dark content</span>

Works on any element, not just images.

Invert on dark

1![Request path from client through API gateway to database and back](./simple-diagram.invert.svg "Request lifecycle")

Images with .invert. in their filename receive the invert-on-dark class automatically, which applies invert(1) hue-rotate(180deg) in dark mode.

Accessible Emojis

Emoji characters are wrapped in <span role="img" aria-label="..."> so screen readers announce the emoji name.

1Build complete! 🎉

Produces:

1Build complete! <span role="img" aria-label="party popper">🎉</span>

Heading IDs and Anchors

Every heading gets a URL-safe id (via rehype-slug) and the heading text is wrapped in an anchor link (via rehype-autolink-headings).

1## Getting Started

Produces:

1<h2 id="getting-started"><a href="#getting-started">Getting Started</a></h2>

These IDs power the table-of-contents sidebar and enable deep-linking to any section.

Code Blocks

Code blocks are rendered by the built-in Pagesmith renderer on top of Shiki with syntax highlighting, dual themes, copy/collapse controls, and shared Pagesmith chrome.

Basic Highlighting

Use a fenced code block with a language identifier:

1```ts2const greeting = "Hello, world!";3```

Over 100 languages are supported via Shiki.

File Titles

Add title="..." to show a filename or label above the block:

1```ts title="vite.config.ts"2import { defineConfig } from "vite";3export default defineConfig({});4```

Line Numbers

Line numbers are shown by default. Control them per-block:

1```bash showLineNumbers=false2npm install @pagesmith/core3```45```ts startLineNumber=426export function resolve() {7  /* ... */8}9```

Configure the site-wide default:

1markdown: {2  shiki: { defaultShowLineNumbers: false },3}

Line Highlighting

Mark, insert, or delete lines to draw attention:

1```ts mark={2-3}2const name = "Pagesmith";3const version = "0.8.0";4const highlighted = true;5```67```ts ins={2} del={1}8const old = "before";9const updated = "after";10```

Range syntax supports individual lines and ranges: mark={1, 3-5, 8}.

Diff Highlighting

Use the diff language for unified diff format:

1```diff2- const port = 30003+ const port = process.env.PORT || 30004```

Collapsible Sections

Hide boilerplate that readers can expand on click:

1```ts collapse={1-5}2import { defineConfig } from "vite";3import { pagesmithContent, pagesmithSsg } from "@pagesmith/site/vite";4import collections from "./content.config";5import path from "node:path";6export default defineConfig({7  plugins: [pagesmithContent(collections), pagesmithSsg()],8});9```

Text Wrapping

Enable word wrapping for long lines:

1```json wrap2{3  "name": "@pagesmith/core",4  "description": "A very long description that would overflow",5  "version": "0.8.0"6}7```

Frame Styles

Terminal languages (bash, sh, zsh, shell, powershell) use a terminal frame. Override explicitly:

1```bash frame="none"2npm install @pagesmith/core3```

Values: "code" (editor frame), "terminal", or "plain" (alias "none"). When frame= is omitted, terminal-style languages auto-select "terminal" and everything else auto-selects "code".

Meta String Quick Reference

All properties go after the language identifier in the opening fence:

Combine multiple properties on the same fence:

1```ts title="example.ts" mark={3} ins={5} collapse={1-2}2import { z } from "zod";3import { defineCollection } from "@pagesmith/core";4const posts = defineCollection({5  loader: "markdown",6  directory: "content/posts",7  schema: z.object({ title: z.string() }),8});9```

Code Tabs

Consecutive titled code blocks are automatically grouped into a tabbed interface. Write titled fenced blocks one after another with no other content between them:

1```bash title="npm"2npm install @pagesmith/core3```45```bash title="pnpm"6pnpm add @pagesmith/core7```89```bash title="yarn"10yarn add @pagesmith/core11```1213```bash title="bun"14bun add @pagesmith/core15```

Rendered sample:

1npm install @pagesmith/core

1pnpm add @pagesmith/core

1yarn add @pagesmith/core

1bun add @pagesmith/core

The title value becomes the tab label. The first tab is active by default.

Rules

• Every block in the group must have a title — an untitled block breaks the group.
• Any non-code content (paragraph, heading, list) between titled blocks breaks the group.
• Each group is independent; a page can have multiple tab groups.
• Without JavaScript, all blocks stack vertically as a no-JS fallback.

Multi-Language Example

1```ts title="TypeScript"2interface Config {3  host: string;4  port: number;5}6```78```python title="Python"9@dataclass10class Config:11    host: str = "localhost"12    port: int = 300013```1415```go title="Go"16type Config struct {17    Host string18    Port int19}20```

Rendered sample:

1interface Config {2  host: string;3  port: number;4}

1@dataclass2class Config:3    host: str = "localhost"4    port: int = 3000

1type Config struct {2    Host string3    Port int4}

Language Aliases

Some languages that Shiki does not recognize natively are aliased to a supported language for highlighting:

Add custom aliases via markdown.shiki.langAlias:

1markdown: {2  shiki: {3    langAlias: {4      myLang: 'typescript',5    },6  },7}

User aliases take precedence over the defaults.

Dual Themes

Code blocks support light and dark themes simultaneously. The default pair is github-light / github-dark. A prefers-color-scheme media query switches between them automatically.

Configure custom theme pairs:

1markdown: {2  shiki: {3    themes: {4      light: 'catppuccin-latte',5      dark: 'catppuccin-mocha',6    },7  },8}

Pagesmith maps themes to .color-scheme-light and .color-scheme-dark CSS classes on <html>, so theme switching integrates with the site-wide color scheme toggle.

Custom Plugins

Extend the pipeline with your own remark or rehype plugins:

1import remarkToc from "remark-toc";2import rehypeFigure from "rehype-figure";34const config = defineConfig({5  collections: { posts },6  markdown: {7    remarkPlugins: [remarkToc],8    rehypePlugins: [[rehypeFigure, { className: "figure" }]],9  },10});

Tuple form [plugin, options] is supported for both remark and rehype.

Injection points:

• Remark plugins run after the built-in remark plugins (GFM, frontmatter, alerts, smartypants, and conditional math) but before remark-rehype.
• Rehype plugins run after the built-in rehype plugins (built-in code renderer, code tabs, scrollable tables, slug, autolink, external links, emojis, local images) and after the separate heading-extraction pass, but before rehype-stringify.

Content plugins (ContentPlugin.remarkPlugin / ContentPlugin.rehypePlugin) are appended after the config-level plugins.

allowDangerousHtml defaults to true, so raw HTML is preserved unless you explicitly disable it. math defaults to 'auto', which enables remark-math and rehype-mathjax only for content that contains math markers.

Pipeline Order

The full unified pipeline, in execution order:

1remark-parse              Parse markdown to MDAST2remark-gfm                Tables, strikethrough, task lists, autolinks, footnotes3remark-frontmatter        Strip YAML frontmatter from AST4remark-github-alerts      > [!NOTE], > [!TIP], etc.5remark-smartypants        Smart quotes, dashes, ellipses6remark-math               Math syntax ($...$, $$...$$) when enabled or auto-detected7[user remark plugins]     From MarkdownConfig.remarkPlugins8lang-alias transform      Map fenced-code language tags via shiki.langAlias9remark-rehype             Markdown AST → HTML AST10rehype-mathjax            Render math to SVG (before the built-in code renderer)11applyPagesmithCodeRenderer Syntax highlighting, code frames, copy button12rehype-code-tabs          Group consecutive titled blocks into tabs13rehype-scrollable-tables  Wrap markdown tables for horizontal scrolling14rehype-slug               Add id="" to headings15rehype-autolink-headings  Wrap heading text in anchor links16rehype-external-links     target="_blank" on external URLs17rehype-accessible-emojis  aria-label on emoji characters18rehype-local-images       Figure wrapping, picture element for raster images, light/dark pair merging19heading extraction        Collect headings for TOC data20[user rehype plugins]     From MarkdownConfig.rehypePlugins21rehype-stringify          HTML AST → HTML string