SvelTeX

Theme

Overview ​

Summary ​

SvelTeX is a preprocessor for Svelte that allows you to write markdown and LaTeX directly in your .svelte files. It does so by escaping special syntax and parsing content into four categories:

  • Markdown: Processed by a markdown processor: unified (remark + rehype), markdown-it, micromark, or marked.
  • Code: Processed by a syntax highlighter: Shiki, starry-night, or highlight.js.
  • Math: Processed by a math renderer: MathJax or KaTeX.
  • TeX: Processed by your local TeX distribution.

It then runs these processors on the corresponding content, and stitches the output of each back together into a single Svelte file and unescapes previously escaped special syntax. After this, the Svelte compiler or the next Svelte preprocessor can take over.

Highlights ​

  • Markdown-in-Svelte: Intersperse markdown and Svelte syntax for a better developer and authoring experience. Pick your favorite markdown processor and use plugins to fine-tune the output, or let SvelTeX take care of the details for you.

  • LaTeX-in-Svelte: Take advantage of your local TeX distribution and generate highly optimized SVGs for complex graphics using familiar syntax, all without leaving your Svelte files.

  • Batteries included: Sensible defaults and helpful features such as automatic CSS injection for MathJax and KaTeX make it easy to get started with SvelTeX.

  • Zero runtime: Being a preprocessor, SvelTeX runs entirely at build-time, so there's no need for client-side JavaScript.

  • Customizable: SvelTeX is extremely customizable. It supports multiple different backends for markdown, syntax highlighting, and math rendering, letting you work with your favorite ecosystem of plugins. Furthermore, it also allows you to inject your own custom transformers into the pipeline for each of these processors.

  • SvelTeX language support: A TextMate grammar, a tree-sitter grammar, and a dedicated language server — bundled with the VS Code extension and shipped as a Zed extension too — give .sveltex files first-class syntax highlighting, hover, completion, diagnostics, and frontmatter intellisense in any LSP-aware editor.

  • Extensive documentation: With these docs and the extensive IntelliSense and hints that 9,000+ lines of comments provides, you'll find that almost every function or type in SvelTeX is documented, be it user-facing or internal.

  • Small codebase: At just under 11,000 lines of code[1], SvelTeX's core is relatively small, making it easier to maintain and contribute to.

  • TypeScript-first: SvelTeX is exclusively written in TypeScript. Consistent use of generics and precise types make SvelTeX not only type-safe and easier to maintain, but also ensures that the right IntelliSense is provided in any given situation.

  • HMR support: None of SvelTeX's functionality interferes with Vite's excellent hot module replacement (HMR) support; in fact, it's a joy to watch the output of your TeX code update on your dev server as you go.

  • Robust: Fuzzy testing with fast-check, E2E visual regression tests with Playwright (1,800+ snapshots), and 8,200+ unit tests with Vitest provide 100% code coverage.

  • Helpful error messages: A lot of effort has gone into trying to make error messages as helpful as possible, offering suggestions and context where possible.

  1. Counted by cloc over the @nvl/sveltex package's src directory (excluding src/data): the summed code lines of every language except Markdown — which, being a code count, omits comments and blank lines — rounded up to the nearest thousand. ↩︎