Code Blocks

Pagesmith uses a built-in Shiki-backed code renderer for code blocks. The renderer ships with @pagesmith/core, while the shared CSS and browser runtime live in @pagesmith/site. Include @pagesmith/site/css/content or @pagesmith/site/css/standalone so the shared frame, layout, and tab styles are present; theme colors and frame markup are generated during markdown processing, and the shared content runtime enables copy, collapse, and tab interactions in the browser.

Basic Syntax Highlighting

Use standard fenced code blocks with a language identifier:

1```js2const greeting = "Hello, world!";3console.log(greeting);4```

Rendered sample:

1const greeting = "Hello, world!";2console.log(greeting);

The built-in renderer supports 100+ languages through Shiki (the same syntax highlighting engine used by VS Code).

Dual Themes

Code blocks automatically support light and dark themes based on the user’s system preference (prefers-color-scheme). The default themes are github-light and github-dark.

Configure custom themes in your markdown config:

1const config = defineConfig({2  collections: { posts },3  markdown: {4    shiki: {5      themes: {6        light: "github-light",7        dark: "github-dark",8      },9    },10  },11});

Or in pagesmith.config.json5 for @pagesmith/docs:

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

File Titles

Add a title to show a filename or label above the code block:

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

Rendered sample:

1import { defineConfig } from "vite";2export default defineConfig({});

Line Numbers

Line numbers are shown by default. Hide them for a specific block:

1```bash showLineNumbers=false2npm install @pagesmith/core3```

Rendered sample:

npm install @pagesmith/core

Or start line numbers from a specific number:

1```ts startLineNumber=422const answer = getAnswer();3```

Rendered sample:

42const answer = getAnswer();

To change the default for your entire site, set defaultShowLineNumbers in the markdown config:

1const config = defineConfig({2  collections: { posts },3  markdown: {4    shiki: {5      defaultShowLineNumbers: false,6    },7  },8});

Line Highlighting

Mark specific lines to draw attention:

1```ts mark={3}2const name = "Pagesmith";3const version = "0.8.0";4const highlighted = true; // this line is highlighted5```

Rendered sample:

1const name = "Pagesmith";2const version = "0.8.0";3const highlighted = true; // this line is highlighted

Diff-Style Highlighting

Show inserted and deleted lines:

1```ts ins={2} del={1}2const old = "before";3const updated = "after";4```

Rendered sample:

1const old = "before";2const updated = "after";

Range Syntax

Highlight multiple lines or ranges:

1```ts mark={1, 3-5}2const a = 1;3const b = 2;4const c = 3;5const d = 4;6const e = 5;7```

Rendered sample:

1const a = 1;2const b = 2;3const c = 3;4const d = 4;5const e = 5;

Collapsible Sections

Collapse long sections of code that are not the focus:

1```ts collapse={1-5}2// These lines are collapsed by default3import { defineConfig } from "vite";4import { pagesmithContent, pagesmithSsg } from "@pagesmith/site/vite";5import collections from "./content.config";6// This line is visible7export default defineConfig({8  plugins: [pagesmithContent(collections), pagesmithSsg()],9});10```

Rendered sample:

Show 5 hidden lines6export default defineConfig({7  plugins: [pagesmithContent(collections), pagesmithSsg()],8});

Users can click to expand the collapsed section.

Text Wrapping

Enable word wrapping for long lines:

1```json wrap2{3  "name": "@pagesmith/core",4  "description": "Headless content layer — schema-validated collections, lazy markdown rendering, and the Vite content plugin",5  "version": "0.8.0"6}7```

Rendered sample:

1{2  "name": "@pagesmith/core",3  "description": "Headless content layer — schema-validated collections, lazy markdown rendering, loaders, and the Vite content plugin",4  "version": "0.8.0"5}

Frame Styles

The built-in renderer automatically detects terminal languages (bash, sh, zsh, shell, powershell) and renders them with a terminal-style frame. All other languages use an editor-style frame.

Override the frame style explicitly:

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

Rendered sample:

1npm install @pagesmith/core

Available frame values: "code" (editor), "terminal", "none" (plain, no chrome). When omitted, the frame is auto-detected from the language (bash/sh/shell/console/zsh use "terminal", everything else uses "code").

Copy Button

Every code block includes a copy button by default. Users can click it to copy the code to their clipboard. Copy, collapse, and tabs are progressively enhanced by the shared Pagesmith content runtime.

Code Tabs

Consecutive titled code blocks are automatically grouped into a tabbed interface. This is useful for showing the same concept across package managers, languages, or configurations. Just 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```

Rendered sample:

1npm install @pagesmith/core

1pnpm add @pagesmith/core

1yarn add @pagesmith/core

The title value becomes the tab label. The first tab is active by default and readers can click to switch between them. Without JavaScript, all blocks stack vertically as a fallback.

You can also use code tabs to show the same logic in different languages:

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```rust title="Rust"16struct Config {17    host: String,18    port: u16,19}20```

Rendered sample:

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

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

1struct Config {2    host: String,3    port: u16,4}

Any non-code content (a paragraph, heading, or untitled code block) between titled blocks breaks the group — each group is independent.

How It Works

The diagram below shows the package split that matters most here: @pagesmith/core turns fenced code into themed HTML markup, while @pagesmith/site provides the shared CSS and browser runtime that make tabs, copy, and collapse interactions work.

Pagesmith’s built-in code renderer runs inside the unified markdown pipeline. During markdown processing, it:

1. Finds fenced code blocks in the HTML AST after remark-rehype
2. Applies syntax highlighting using Shiki
3. Builds Pagesmith-owned frame markup for titles, line numbers, tabs, copy buttons, diff markers, and collapse controls
4. Adds inline theme variables for light/dark token colors
5. Relies on the shared Pagesmith content runtime for tabs, copy, and collapse interactions

Shared code-block styling ships in the Pagesmith CSS bundles published from @pagesmith/site, and interactive behavior ships in the shared Pagesmith content runtime. Custom layouts and framework integrations should load those shared assets instead of recreating per-block JavaScript.

Meta String Reference

All meta properties are added after the language identifier in the opening fence:

Multiple properties can be combined:

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```

Rendered sample:

Show 2 hidden lines3const posts = defineCollection({4  loader: "markdown",5  directory: "content/posts",6  schema: z.object({ title: z.string() }),7});