Configuration

Code Blocks

How to configure code blocks in markdown.

Overview

SvelDocs uses rehype-pretty-code in the markdown pipeline to transform fenced code blocks into themed, styleable HTML. The plugin uses shiki behind the scenes.

Theme

Edit the code block theme in the src/lib/markdown/markdown.config.ts. By default it uses the GitHub color theme, but you can use any theme supported by shiki.

import rehypePrettyCode from 'rehype-pretty-code';
 
const markdownConfig = defineConfig({
	...
	rehypePlugins: [
		[
			rehypePrettyCode,
			{
				theme: {
					light: 'github-light',
					dark: 'github-dark'
				},
				keepBackground: false,
				transformers: [transformerNotationDiff()]
			}
		]
	]
});

.ts

Component

src/lib/markdown/components/code/pre.svelte is the component that replaces the default html <pre> element. This allows for:

Language Badge
Code Copy Button
CSS Styling

Styling

Styling is configured within the component. You can style the component elements themselves inline, but rehype-pretty-code and shiki styling must be configured in the style section using :global.

Here is the provided default:

src/lib/markdown/components/code/pre.svelte

<style lang="postcss">
	@reference "$css";
 
	:global {
		code[data-theme*=' '],
		code[data-theme*=' '] span {
			color: var(--shiki-light);
		}
 
		.dark code[data-theme*=' '],
		.dark code[data-theme*=' '] span {
			color: var(--shiki-dark);
		}
 
		[data-rehype-pretty-code-figure] {
			@apply has-[pre:focus-visible]:ring-accent/50 has-[pre:focus-visible]:border-accent overflow-hidden rounded-md border shadow-xs transition-[border-color,box-shadow] has-[pre:focus-visible]:ring-2;
		}
		[data-rehype-pretty-code-title] {
			@apply bg-primary border-b p-2 text-sm font-bold;
		}
		[data-rehype-pretty-code-caption] {
			@apply text-muted-foreground bg-primary border-t p-2 text-sm;
		}
		[data-line] {
			@apply inline-block px-4 hover:bg-[color-mix(in_oklch,currentColor,transparent_90%)];
		}
		[data-line].diff.remove {
			@apply bg-red-500/10 opacity-75 hover:bg-[color-mix(in_oklch,var(--color-red-500),transparent_80%)];
		}
		[data-line].diff.add {
			@apply bg-green-500/10 hover:bg-[color-mix(in_oklch,var(--color-green-500),transparent_80%)];
		}
		[data-line-numbers] {
			counter-reset: line;
		}
		[data-line-numbers] > [data-line] {
			@apply pl-0;
		}
		[data-line-numbers] > [data-line]::before {
			counter-increment: line;
			content: counter(line);
			@apply text-muted-foreground/75;
		}
		[data-line-numbers-max-digits] {
			& > [data-line]:hover::before {
				@apply text-foreground bg-[color-mix(in_oklch,currentColor,transparent_90%)];
			}
			& > [data-line]::before {
				width: calc(var(--lineNumbersMaxDigits) + 2rem);
				@apply bg-secondary sticky left-0 mr-4 inline-block border-r px-4 text-right;
			}
		}
		[data-highlighted-line] {
			@apply bg-accent/10! hover:bg-[color-mix(in_oklch,var(--color-accent),transparent_80%)]!;
		}
	}
</style>

.svelte

Markdown Features

Use fenced-code metadata to control each block from markdown:

```ts
console.log('hello world');
```

.md

console.log('hello world');

.ts

You can declare the language at top. ts is shortened for typescript.

Title

You can add a title to the code block by adding title="your title here":

```ts title="src/lib/my-awesome-file.ts"
console.log('hello world');
```

.md

src/lib/my-awesome-file.ts

console.log('hello world');

.ts

Footer (Caption)

You can add a caption to the code block by adding caption="your caption here":

```ts caption="This runs during page load"
console.log('loaded');
```

.md

console.log('loaded');

.ts

This runs during page load

Highlight Lines

You can highlight specific lines by using curly-brace ranges after the language:

```ts {2,4-6}
const one = 1;
const two = 2;
const three = 3;
const four = 4;
const five = 5;
const six = 6;
```

.md

const one = 1;
const two = 2;
const three = 3;
const four = 4;
const five = 5;
const six = 6;

.ts

Line Numbers

You can show line numbers by using showLineNumbers:

```ts showLineNumbers
const one = 1;
const two = 2;
const three = 3;
const four = 4;
const five = 5;
const six = 6;
```

.md

const one = 1;
const two = 2;
const three = 3;
const four = 4;
const five = 5;
const six = 6;

.ts

You can start the line number at a specific number by using a curly-brace and a number:

```ts showLineNumbers{5}
const one = 1;
const two = 2;
const three = 3;
const four = 4;
const five = 5;
const six = 6;
```

.md

const one = 1;
const two = 2;
const three = 3;
const four = 4;
const five = 5;
const six = 6;

.ts

Diff Notation

You can show added and removed lines using notation diff comments.

```ts
const text = 'hi world!'; // [!code --]
const text = 'hello world!'; // [!code ++]
```

.md

const text = 'hi world!';
const text = 'hello world!';

.ts

Kitchen Sink

Here is an example of all the markdown features combined.

```ts {2,4-6} title="kitchen-sink-example.ts" showLineNumbers
const one = 1;
const two = 2;
const three = 3;
const four = 4;
const five = 5;
const six = 6;
const text = 'hi world!'; // [!code --]
const text = 'hello world!'; // [!code ++]
```

.md

kitchen-sink-example.ts

const one = 1;
const two = 2;
const three = 3;
const four = 4;
const five = 5;
const six = 6;
const text = 'hi world!';
const text = 'hello world!';

.ts

example caption

File to Code Block

You can generate a code block from a file using the File Reader component.