Migrating from mdsvex 0.x
Layouts are now templates. The idea is the same, a component that wraps documents and replaces their elements, with new names and Svelte 5 components.
Run the migrator
@mdsvex/migrate rewrites your config and documents, and flags what it can't rewrite:
npm i --save-dev @mdsvex/migrate@nextIt is a library of functions. A short script runs them over a project. Commit your work first, then set config to the file that calls mdsvex(), layouts to your layout components, and options to what your documents were written for:
import { readFileSync, writeFileSync, globSync } from 'node:fs';
import { migrate_document, migrate_config, check_template } from '@mdsvex/migrate';
const config = 'svelte.config.js';
const layouts = ['src/lib/layouts/Blog.svelte'];
// smartypants: your old smartypants option, true if you never set it
// math: true if you used remark-math
const options = { smartypants: true, math: false };
function report(file, notes) {
for (const note of notes) console.log(`${file}:${note.line}: ${note.message}`);
}
const { code, notes } = migrate_config(readFileSync(config, 'utf8'));
writeFileSync(config, code);
report(config, notes);
for (const file of globSync('src/**/*.{svx,md}')) {
const { code, notes } = migrate_document(readFileSync(file, 'utf8'), options);
writeFileSync(file, code);
report(file, notes);
}
for (const file of layouts) report(file, check_template(readFileSync(file, 'utf8')));node migrate.jsmigrate_configrewrites the options of a JavaScript or TypeScript config:layoutintotemplates,highlight,smartypantsandextension. It returns the newcodeand a list ofnotes, things to check by hand, each with alineand amessage. Every entry ofremarkPluginsandrehypePluginsgets a note that says what replaces it.migrate_documentconverts a document to mdsvex's markdown and returns itscodeandnotes,migratethe code alone. 0.x read CommonMark, where*text*is emphasis and a===underline makes a heading, so every document needs it. Svelte in the document is kept as written, thelayout:key of the frontmatter becomestemplate:, and GitHub alerts become callouts.check_templatelists what a layout component needs changed. It rewrites nothing.
Read the diff before you commit it. migrate writes each document out again from what it parsed, so list markers, table padding and blank lines come out in one style.
The options stay where they were. SvelteKit 3 has no svelte.config.js, so move the mdsvex() call from preprocess into the plugins of vite.config.js, as in SvelteKit. mdsvex registers its extensions, so they don't need to move with it.
For a document that is already mdsvex's markdown, migrate_frontmatter renames the layout: key and changes nothing else.
What changes
layout: './src/Layout.svelte' templates: { default: './src/Layout.svelte' }
layout: { _: …, blog: … } templates: { default: …, blog: … }
select_template, which the migrator writes for you as a note
layout: blog, layout: false template: blog, template: false
layout: _ template: default
layoutPropForwarding always on, the migrator flags it
<slot /> in a layout {@render children()}
export let title in a layout let { title } = $props()
<script context="module"> exports <script module> exports
{title} in a document {metadata.title}
extension: '.md' extensions: ['.md']
frontmatter: { marker, type } gone, the fences are always --- and frontmatter.parse reads what is between them
rel="nofollow" on every link to another site no rel. external_links({ rel: ['nofollow'] }) from @mdsvex/plugin-external-links keeps it
smartypants, on by default smart_punctuation, off by default, the migrator turns it on
remarkPlugins, rehypePlugins gone. Most of what they did is built in or a first-party plugin, see coming from remark and rehype plugins
mdsvex's own markdown, the migrator converts them
```js file=./a.js#L1-L5 ````, fromremark-code-import` src=, the migrator renames file= on a fence with no code
$x$ and $$x$$, from remark-math math, the migrator rewrites them when you pass math: true
 served from the page's url imported from beside the document, write /a.png for a file in static, or set import_images: false
The migrator handles the layout, smartypants and extension entries and converts the documents. It flags <slot />, layoutPropForwarding, the frontmatter options, the missing nofollow and every entry of remarkPlugins and rehypePlugins, each with what replaces it. The other entries are yours to change.
0.x matched named layouts to folders. Templates aren't matched by folder, so for named layouts the notes include a select_template to paste into your config:
select_template: (id) => (id.includes('/blog/') ? 'blog' : undefined),layout: in frontmatter
mdsvex doesn't read a layout: key any more, and there is no alias for it. The migrator renames it to template:. A document you haven't migrated keeps layout: as ordinary metadata, and gets the default template, or the one select_template picks:
---
title: Hello
layout: blog
---
# Hello<script module>
export const metadata = {
title: 'Hello',
layout: 'blog',
};
</script>
<script>
import Template_MDSVEX from '#lib/templates/Post.svelte';
let __mdsvex_props = $props();
</script>
<Template_MDSVEX
{...metadata}
{...__mdsvex_props}
><h1>Hello</h1></Template_MDSVEX
> Layout components
A layout needs two changes to work as a template:
<!-- before -->
<script>
export let title;
</script>
<h1>{title}</h1>
<slot /><!-- after -->
<script>
let { title, children } = $props();
</script>
<h1>{title}</h1>
{@render children()}check_template finds <slot />, $$props, $$restProps and {...$$props}. npx sv migrate svelte-5 migrates the rest of the component.
Element replacements stay in the module script, now <script module>, and keep working.
Syntax highlighting in 0.x
0.x highlighted with Prism, through a highlight.highlighter that could be async and returned {@html}. Now twinkleplop highlights by default, and mdsvex escapes whatever a highlighter returns.
highlight: false highlight: false
highlight: { alias: { x: 'y' } } highlight: { languages: { x: 'y' } }
highlight: { highlighter(code, lang, meta, filename) }, sync or async highlight: (code, { lang, meta, inline, filename }) => html, sync only
{@html `…`} a highlighter returns plain HTML
highlight.optimise gone, highlighted code is always markup
escapeSvelte gone, mdsvex escapes braces itself
prism-svelte twinkleplop
a twinkleplop theme you import
pre replacement doesn't apply to code blocks it does, see code block components
migrate_config renames alias to languages and removes optimise. Alias targets are now twinkleplop's languages, so it flags Prism names twinkleplop doesn't have, such as markup. It can't rewrite a highlighter, so it leaves a // TODO(mdsvex-migrate) comment above it, and it flags every escapeSvelte import.
A highlighter changes in three ways. It takes an object as its second argument, it returns HTML without escaping it, and it can't be async. A Shiki highlighter goes from the first of these to the second:
// before
import { escapeSvelte } from 'mdsvex';
const shiki = await createHighlighter({ themes: ['github-dark'], langs: ['ts'] });
const config = {
highlight: {
highlighter: async (code, lang = 'text') => {
const html = escapeSvelte(shiki.codeToHtml(code, { lang, theme: 'github-dark' }));
return `{@html \`${html}\` }`;
}
}
};// after
const shiki = await createHighlighter({ themes: ['github-dark'], langs: ['ts'] });
mdsvex({
highlight: (code, { lang, inline }) =>
inline ? null : shiki.codeToHtml(code, { lang: lang || 'text', theme: 'github-dark' })
});Or drop the highlighter and use the default. Either way, import a theme: highlighted code has no colours without one.
Smart punctuation in 0.x
0.x curled quotes and made dashes and ellipses in every document unless you set smartypants: false. Now smart_punctuation does that, and it is off unless you turn it on. migrate_config turns it on for a config that relied on the old default, so your pages keep their typography:
smartypants option smart_punctuation: true is added
smartypants: true smart_punctuation: true
smartypants: false removed, off is the default
smartypants: { quotes, ellipses } smart_punctuation: { quotes, ellipses }
dashes: true, the default: -- is an em dash, --- is left alone -- is an en dash and --- an em dash
dashes: 'oldschool' dashes: true, which now means the same
dashes: 'inverted' dashes: true, and the documents are rewritten
backticks, which curled ``quoted'' gone, the documents are rewritten
The dashes are the one change that shows. With the 0.x default, -- was an em dash. It is an en dash now, as it is in pandoc, cmark and LaTeX. So that pages render what they did, pass your old smartypants value to migrate when it converts your documents, true if you never set it, as the script under run the migrator does:
migrate(source, { smartypants: true });It turns each -- in text into ---, keeps a --- that 0.x left alone as \---, swaps the two for 'inverted', and turns ``quoted'' into "quoted". Code, urls and attributes are not touched. The notes from migrate_config say which of this applies to your config.
- Three things 0.x changed are left alone now, because they are not prose: a string inside a Svelte expression, an attribute such as
--css-var="x"on a component, and the text of an autolinked url. - And
--nameafter a space is read as a command line flag, where 0.x gave it a dash.