Code blocks

Highlight lines, mark diffs, focus, flag errors, and highlight words.

Every fenced code block is highlighted by Shiki at build time. On top of that, you annotate lines and words with comment markers written right in the code. The marker comment is stripped from the rendered output, so what readers see stays clean.

Each section below shows the markdown you write, then how it renders.

Highlight a line

Append // [!code highlight] to a line (a real comment in the fence’s language) to give it a highlighted background.

You write:

			const config = defineConfig({
	title: 'My Library' // [!code highlight]
});

Which renders as:

			const config = defineConfig({
	title: 'My Library'
});

Additions and deletions

Mark a line with // [!code ++] for an addition or // [!code --] for a deletion. They render with a colored background and a + / - gutter marker.

You write:

			export default {
	preprocess: [vitePreprocess()],             // [!code --]
	preprocess: [vitePreprocess(), docsmith()], // [!code ++]
};

Which renders as:

			export default {
	preprocess: [vitePreprocess()], 
	preprocess: [vitePreprocess(), docsmith()] 
};

Focus

// [!code focus] dims the other lines so the eye lands on what matters. Hover the rendered block to bring the rest back.

You write:

			function setup() {
	const app = createApp();
	app.use(docsmith()); // [!code focus]
	return app;
}

Which renders as:

			function setup() {
	const app = createApp();
	app.use(docsmith()); 
	return app;
}

Errors and warnings

// [!code error] and // [!code warning] tint a line red or amber, for call-outs like a deprecated call or a footgun.

You write:

			const ok = readFile('./page.md');
const bad = readFile();                  // [!code error]
const risky = readFileSync('./page.md'); // [!code warning]

Which renders as:

			const ok = readFile('./page.md');
const bad = readFile(); 
const risky = readFileSync('./page.md');

Highlight a word

// [!code word:name] highlights every occurrence of name on the next line. Add a count like word:name:2 to limit how many.

You write:

			const name = frontmatter.title; // [!code word:name]

Which renders as:

			const name = frontmatter.title;

Markers use the fence's language

Write the marker inside a comment your language understands: // for JS/TS/Svelte, # for bash or YAML,  for HTML. Shiki strips the comment along with the marker, so it never ships to the reader. (To show a marker literally instead of applying it, as the “You write” blocks above do, put it in a plain text block.)