@nvl/sveltex
v0.4.1
Published
Svelte + Markdown + LaTeX
Downloads
112
Maintainers
Readme
Getting Started
Note: See the docs for more information. Note: This package is ESM-only.
Creating a new project
You can use the create-sveltex
package to create a new project using SvelTeX:
pnpm dlx create-sveltex # If using PNPM
bunx create-sveltex # If using Bun
npx create-sveltex # If using NPM
yarn dlx create-sveltex # If using Yarn
...and follow the prompts.
Adding to existing project
Installation
pnpm add -D @nvl/sveltex # If using PNPM
bun add -D @nvl/sveltex # If using Bun
npm add -D @nvl/sveltex # If using NPM
yarn add -D @nvl/sveltex # If using Yarn
Basic steup
// svelte.config.js
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
import { sveltex } from '@nvl/sveltex';
/** @type {import('@sveltejs/kit').Config} */
const config = {
// ...
preprocess: [
vitePreprocess(), // (optional)
await sveltex({
markdownBackend: 'unified',
codeBackend: 'shiki',
mathBackend: 'mathjax',
}, {
// Options
}),
// ...
],
extensions: ['.svelte', '.sveltex'],
// ...
};
export default config;
Now, install the backends (cf. IntelliSense or the error message you'd get if
you tried to run the above code without installing the backends), and you should
be good to go. Create a +page.sveltex
file in your src/routes
directory, and
start adding markdown, math, code blocks, and even TeX components.
Editor integration
For VS Code, you can install the official SvelTeX extension from the
marketplace. This will provide syntax highlighting for .sveltex
files.
For other editors, you'd need to configure syntax highlighting yourself using the SvelTeX TextMate grammar provided within the VS Code extension.
Proper LSP-style language support is not currently implemented. Doing so via e.g. request forwarding could be an immense enrichment to the developer experience, but it's not something I can currently commit to. Contributions for this would be extremely welcome.
Acknowledgments
See acknowledgments on the project site.
Note: The TSDoc comments for many of this project's interfaces, particularly those describing options to be passed to external libraries, may be copies, paraphrasings, or adaptations of the official documentations of the respective libraries. Some notable examples are MathJax and TikZ.
Addendum: Some lessons learned
Tips
- Always run your linter before you run your tests. In particular, note that VSCode's ESLint extension only runs on files that are currently open, so even if the problems pane is clear, you might still have linting errors in files that are not currently open.
- Generally speaking, don't combine
.ts
and.d.ts
files. In short, it's either.ts
or it's.js
+ (optionally).d.ts
. This is almost certainly an egregious oversimplification, but it's the feeling I got after spending a bunch of time trying to debug issues caused by me mixing.ts
and.d.ts
files. - In YAML files for GitHub actions,
'text'
,"text"
, andtext
may not be the same. In particular, I hadworkflow_run
events not triggering because the needed workflow's name wasn't in quotes, but theworkflow_run
element was.
Cool software I didn't know before
fast-check
, for fuzzy testing.plop
, for code generation with templates and CLI prompts.- Shiki, for code highlighting.
twoslash
, for IntelliSense in markdown code blocks.- VitePress, a great SSG for docs.
node-poppler
, a Node.js wrapper for Poppler, which can used to convert PDFs to SVGs.- Knip, a tool for detecting unused files, dependencies, and exports.