Overview

• About
• Installation
• Usage
• API
• Best Practices
• Frequently Asked Questions
• Contributing
• Acknowledgments
• License

About

This package is a SvelteKit preprocessor that allows you to write Svelte in Markdown files. It uses unified.js under the hood to transform Markdown content and is fully customizable with remark and rehype plugins.

Installation

[!note] This is a pure ESM package. Please install on Node.js v16 or newer.

npm install -D @paperfeel/preprocessor

Usage

To use this preprocessor, make the following changes to your svelte.config.js file:

1. Replace vitePreprocess() with paperfeel()
2. Add .md to the list of allowed file extensions

import adapter from "@sveltejs/adapter-auto";
import { paperfeel } from "@paperfeel/preprocessor";

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

export default config;

Then add pages or components that end in .md:

---
title: My First Page
---

<script lang="ts">
    import Foo from "./Foo.svelte";
</script>

# {meta.title}
This is some example content!

<div>
    <Foo/>
</div>

[!tip] The front matter is automatically parsed and is available via the meta variable. It can also be imported from a Svelte component.

<script>
    import Foo, { meta } from "./Foo.svelte";
</script>

API

This package exports the function paperfeel. There is no default export.

paperfeel(options)

Paperfeel preprocessor.

Parameters

• options (PaperfeelOptions)

Returns

Preprocessor (PreprocessorGroup[]).

Options

Paperfeel preprocessor options.

Fields

• plugins ((Plugin | [ Plugin, PluginSettings ])[], optional) — Plugins passed to unified.js. This preprocessor automatically sorts plugins and puts remark plugins in front of rehype plugins.
• escape (string[], optional) — List of selectors for nodes in which curly braces must be escaped. The content of code nodes is automatically escaped by this preprocessor.
• frontMatter (GrayMatterOptions, optional) — Options passed to gray-matter.
• svelte (VitePreprocessOptions, optional) — Options passed to @sveltejs/vite-plugin-svelte.

Best Practices

Avoid Self-Closing Tags

Due to the underlying HTML parser that is used, it is best to either avoid self-closing HTML tags or to wrap them in a div. Otherwise, everything after the self-closing tag will not be rendered.

<!-- bad -->
<MyComponent/>

<!-- good -->
<MyComponent></MyComponent>

<!-- good -->
<div>
    <MyComponent/>
</div>

Keep State Handling Minimal

Markdown is primarily for writing content — if you need to handle state, it's best to put it in a separate Svelte component and import it into your Markdown.

<!-- bad -->
<script>
    let counter = 0;
    
    const increment = () => {
        counter++
    };
</script>

<button on:click={increment}>Clicks: {counter}</button>

<!-- good -->
<script>
    import Counter from "./Counter.svelte";
</script>

<div>
    <Counter/>
</div>

Frequently Asked Questions

How can I use rehype-katex with Paperfeel?

1. In the Paperfeel preprocessor config, add rehype-katex (and optionally remark-math) to the list of plugins.
2. Add span.katex-display to the list of nodes in which to escape the curly brackets.

[!caution] If span.katex-display is not added to escape in the config, Svelte will try to parse content inside curly brackets as JavaScript, which will ultimately fail to render.

paperfeel({
    plugins: [
        remarkMath,
        rehypeKatex
    ],
    escape: [
        "span.katex-display"
    ]
}

Contributing

Your contributions are greatly appreciated. If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue.

Acknowledgments

• Logo taken from Lucide
• README inspired by unified.js

License