Configuration

Markdown

How to configure and write in markdown files.

Writing Markdown

Markdown is basically split into two sections, one for the metadata of the file or frontmatter, and the other for the actual content.

Frontmatter

Frontmatter is metadata defined at the top of a markdown file:

---
title: Example Title
description: Example Description
keywords: config, markdown
icon: file-text
private: admin
---
 
**Content goes here**.

.md

Content

Content can include markdown, HTML, and svelte components. If you are new to markdown syntax, please refer to the Markdown Syntax page to see what can be done.

Configure Rendering

You can configure how markdown is rendered in the src/lib/markdown/markdown.config.ts file. This allows you to configure the following:

type MarkdownConfig = {
	extensions: string[];
	remarkPlugins?: PluggableList;
	rehypePlugins?: PluggableList;
};

.ts

Extensions

You can configure and add your own file extensions to be considered for the markdown rendering process. For example:

src/lib/markdown/markdown.config.ts

const markdownConfig = defineConfig({
	extensions: ['.md', '.mdx'],
	...
});

.ts

Remark Plugins

You can configure and / or add your own remark plugins that run on the markdown (MDAST) stage. Here is the provided default:

src/lib/markdown/markdown.config.ts

const markdownConfig = defineConfig({
	...
	remarkPlugins: [
		remarkGfm,
		[
			remarkRehype,
			{
				footnoteBackContent: '↩\uFE0E'
			}
		]
	],
	...
});

.ts

Rehype Plugins

You can configure and / or add your own rehype plugins that run on the HTML-like (HAST) stage. Here is the provided default:

src/lib/markdown/markdown.config.ts

const markdownConfig = defineConfig({
	...
	rehypePlugins: [
		rehypeSlug,
		[
			rehypePrettyCode,
			{
				theme: {
					light: 'github-light',
					dark: 'github-dark'
				},
				keepBackground: false
			}
		],
		...rehypeMarkdownAstPlugins
	]
});

.ts

How It Is Used

The markdown config is consumed by the plugins/processed-docs/markdown-to-ast.ts file to process markdown at build time. Here is the rundown:

Parses frontmatter and markdown.
Applies configured remark plugins.
Applies configured rehype plugins.
Produces an AST used by the docs page renderer.

The generated AST is then rendered by src/lib/markdown/BlueprintRenderer.svelte.