markdoc-svelte

Process Markdown and Markdoc files into Svelte components using Markdoc.
Use Markdoc defaults out of the box or configure Markdoc schema to your needs.

Table of Contents

- Install
- Basic example
- Frontmatter
- Customize Markdoc
- Direct definitions
- Configuration folder
- Relative imports
- Preprocessor Options
- Functions
- Heading IDs
- Nodes
- Partials
- Tags
- Typographer
- Validation level
- Variables
- Advanced
- Markdoc limitations
- @sveltejs/enhanced-img
- Page table of contents
- Index page example

Install

Install markdoc-svelte in your SvelteKit project.

``bash
npm install markdoc-svelte
`

Amend your SvelteKit config in svelte.config.js to:

- Process files with the extensions you choose (such as .mdoc and .md).
- Include the preprocessor.

`javascript
import { markdocPreprocess } from "markdoc-svelte";

/* @type {import('@sveltejs/kit').Config} /
const config = {
extensions: [".svelte", ".mdoc", ".md"],
preprocess: [markdocPreprocess()],
};
`

Basic example

Create a directory to hold your markdoc files: src/lib/markdoc

In that directory (at src/lib/markdown/content.md), add an example with basic Markdown syntax:

`markdown
---
title: Hello World
---

Hello World

This is a file that is processed by markdoc-svelte.

!Alt text
`

Dynamically import all files in the directory using a catchall route at src/routes/[...catchall]/+page.ts:

`typescript
import { error } from "@sveltejs/kit";
import type { MarkdocModule } from "markdoc-svelte";

export const load = async ({ params }) => {
const slug = params.catchall;
try {
const page = (await import($lib/markdown/${slug}.md)) as MarkdocModule;
return { page };
} catch {
throw error(404, No corresponding file found for the slug "${slug}");
}
};
`

Render the imported file as a Svelte component in a file at src/routes/[...catchall]/+page.svelte:

`svelte







`

Run your dev server and visit /content to see the rendered file.

Frontmatter

Optionally define YAML frontmatter in your file.
Then use it in your content with the $frontmatter variable.

`markdown
---
title: Why I switched to Markdoc
description: What the benefits of Markdoc are and how to take advantage of them.
---

{% $frontmatter.title %}

You can also access the frontmatter in your Svelte page components.
Get it from the data you defined in +page.ts:

`svelte








`

Customize Markdoc

To add additional features to the syntax of your files, customize your Markdoc schema.
Use any of the following extensions:

- Nodes
- Tags
- Variables
- Functions
- Partials

Customize schema in one of two ways:

- For a single extension or simple extensions, pass directly to the preprocessor options.
- For multiple extensions at once or more complex configurations,
create a configuration folder with schema definitions.

For each extension (such as nodes),
schema definitions passed directly overwrite configuration from a folder.

$3

To define any of the extension points directly,
pass it to the preprocessor options as the name of the extension.
For example, to define a $site.name variable, pass the following:

`javascript
import { markdocPreprocess } from "markdoc-svelte";

/* @type {import('@sveltejs/kit').Config} /
const config = {
extensions: [".svelte", ".mdoc"],
preprocess: [
markdocPreprocess({
variables: {
site: {
name: "Markdoc Svelte",
},
},
}),
],
};
`

$3

For multiple extensions or more complex configurations, create a folder with your entire Markdoc schema.

By default, the preprocessor looks for a schema in the ./markdoc and ./src/markdoc directories.

Define each extension point as a single file
or as a directory with an index.ts or index.js file that exports it.
Partials must be a directory holding Markdoc files.

All extension points are optional.

Example structure:

`
markdoc
├── functions.ts
├── nodes
│ ├── heading.ts
│ ├── index.ts
│ └── callout.ts
├── partials
│ ├── content.mdoc
│ └── more-content.mdoc
├── tags.ts
└── variables.ts
`

For example, create custom nodes in markdoc/nodes.ts:

`typescript
import type { Config } from "markdoc-svelte";
import { Markdoc } from "markdoc-svelte";

const nodes: Config["nodes"] = {
image: {
render: "EnhancedImage",
attributes: {
...Markdoc.nodes.image.attributes, // Include the default image attributes
},
},
};

export default nodes;
`

Or create an index file to export all custom nodes from markdoc/nodes/index.ts
(remember to use relative imports):

`typescript
import image from "./image.ts";
import link from "./link.ts";
import paragraph from "./paragraph.ts";
import type { Config } from "markdoc-svelte";

const nodes: Config["nodes"] = {
image,
link,
paragraph,
};

export default nodes;
`

$3

Use relative imports to import definitions from either .js or .ts files.
Just remember to include the file extension.

For example, if you define custom functions in src/lib/functions.js,
add them to your schema as follows:

`javascript
import { markdocPreprocess } from "markdoc-svelte";
import functions from "./src/lib/functions.js";

/* @type {import('@sveltejs/kit').Config} /
const config = {
preprocess: [
markdocPreprocess({
functions: functions,
}),
],
};
`

Preprocessor Options

| Option | Type | Default | Description |
| ----------------- | ---------------------------------------- | -------------------------------- | ------------------------------------------------------------------------- |
| comments | boolean | true | Enable Markdown comments |
| components | string | "$lib/components" | Svelte components directory for custom nodes and tags |
| extensions | string[] | [".mdoc", ".md"] | Files to process with Markdoc |
| functions | Config['functions'] | - | Functions config |
| headingIds | boolean \| ((value: string) => string) | false | Add IDs to headings without them and include them in export |
| layout | string | - | Default layout for all processed Markdown files |
| linkify | boolean | false | Auto-convert bare URLs to links |
| nodes | Config['nodes'] | - | Nodes config |
| partials | string | - | Partials directory path |
| schema | string | ["./markdoc", "./src/markdoc"] | Schema directory path |
| tags | Config['tags'] | - | Tags config |
| typographer | boolean | false | Enable typography replacements |
| validationLevel | ValidationLevel | "error" | Validation strictness level |
| variables | Config['variables'] | - | Variables config |

$3

Functions enable you to add custom utilities to Markdown
so you can transform content and variables.

For example, you could add a function for transforming strings to uppercase to markdoc/functions.ts:

`javascript
import type { Config } from "markdoc-svelte";

const functions: Config["functions"] = {
uppercase: {
transform(parameters) {
const string = parameters[0];

return typeof string === "string" ? string.toUpperCase() : string;
},
},
};

export default functions;
`

Then use the custom function in a Markdown file:

`markdown
---
title: Hello World
---

This is a {% uppercase(markdown) %} file that is processed by markdoc-svelte.
`

$3

If you want to build a table of contents for a page or just have links to specific headings, set headingIds to true.
Add unique IDs in the original file with annotations
or have them generated automatically.
Each heading element in the generated HTML has an id attribute to link to directly.

Each page then also exports a headings property: a list of all headings with their text, level, and ID.
Use the list to generate a table of contents.

#### Custom ID creator (slugifier)

By default, the preprocessor uses the slug package.
If you have requirements for ID creation, pass a function to the headingIds option.
This function is used to generate the IDs.

`javascript
import { markdocPreprocess } from "markdoc-svelte";

const customSlugger = (str: string): string => str.replaceAll(/[^a-z]/gi, "-");

/* @type {import('@sveltejs/kit').Config} /
const config = {
extensions: [".svelte", ".mdoc"],
preprocess: [
markdocPreprocess({
headingIds: customSlugger,
}),
],
};
`

$3

Nodes are elements built into Markdown from the CommonMark specification.
Customizing nodes enables you to change how existing elements from Markdown are rendered using Svelte components.
The components are automatically loaded from the components directory defined in your configuration.

For example, you might want to customize how images are displayed using the @sveltejs/enhanced-img plugin.
First, define a custom node in markdoc/nodes.ts:

`typescript
import type { Config } from "markdoc-svelte";
import { markdocPreprocess } from "markdoc-svelte";

const nodes: Config["nodes"] = {
image: {
render: "EnhancedImage",
attributes: {
// Include the default image attributes
...Markdoc.nodes.image.attributes,
},
},
};
`

Then add an EnhancedImage component in src/lib/components/EnhancedImage.svelte:

`svelte


{#if image}


{:else}

{/if}
`

Now your EnhancedImage component handles images added through standard Markdown syntax:

`markdown
!A cat sleeping on a balcony
`

#### Relative paths to images

If you're using relative paths to your images in Markdoc,
adjust the custom node to account for this.
For example, you could have the custom node as follows:

`typescript
import type { Config } from "markdoc-svelte";
import { markdocPreprocess } from "markdoc-svelte";

const nodes: Config["nodes"] = {
image: {
render: "EnhancedImage",
attributes: {
// Include the default image attributes
...Markdoc.nodes.image.attributes,
},
transform(node, config) {
// Get the original src
let src = node.attributes.src;

// Use base path if passed as variable
const basePath = config.variables.basePath || "";

// Rewrite relative paths to absolute
if (src.startsWith("./") || src.startsWith("../")) {
src = path.posix.join(basePath, src);
}

// Return a new node with modified src attribute
return new Markdoc.Tag("EnhancedImage", {
...node.attributes,
src,
});
},
},
};
`

$3

Partials are ways to reuse content across files (through transclusion).
The partials defined in your configuration must be a directory of Markdoc files.

For example, you could have a file structure like the following:

`
| markdoc/
|-- partials/
| |-- content.mdoc
| └── post.mdoc
`

These files can be included in other files as follows:

`markdown
---
title: Hello World
---

Hello World

This is a file that is processed by markdoc-svelte.

{% partial file="content.mdoc" %}

{% partial file="post.mdoc" %}
`

$3

Tags are ways to extend Markdown syntax to do more.
Use them to add functionality through Svelte components.

For example, you might want to create a custom Callout tag to highlight information on a page
(these are also known as admonitions).
First, define the tag in markdoc/tags.ts:

`javascript
import type { Config } from "markdoc-svelte";

const tags: Config["tags"] = {
callout: {
// The Svelte component to render the tag
render: "Callout",
// What tags it can have as children
children: ["paragraph", "tag", "list"],
// Define the type of callout through an attribute
attributes: {
type: {
type: String,
default: "note",
matches: ["caution", "check", "note", "warning"],
errorLevel: "critical",
},
title: {
type: String,
},
},
},
};

export default tags;
`

Then create a Callout component for tag in src/lib/components/Callout.svelte:

`svelte