Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nvlang/sveltex
Svelte + Markdown + LaTeX
https://github.com/nvlang/sveltex
latex markdown svelte
Last synced: 3 months ago
JSON representation
Svelte + Markdown + LaTeX
- Host: GitHub
- URL: https://github.com/nvlang/sveltex
- Owner: nvlang
- License: mit
- Created: 2024-02-25T00:23:27.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-09-01T15:59:09.000Z (4 months ago)
- Last Synced: 2024-09-29T05:04:34.747Z (3 months ago)
- Topics: latex, markdown, svelte
- Language: TypeScript
- Homepage: https://sveltex.dev
- Size: 77.6 MB
- Stars: 4
- Watchers: 1
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
[
](https://github.com/nvlang/sveltex)
[
)
](https://npmjs.com/@nvl/sveltex)
[
](https://jsr.io/@nvl/sveltex)
[
](https://jsr.io/@nvl/sveltex)
[
](https://codecov.io/gh/nvlang/sveltex)
## Getting Started
**Note:** See the [docs](https://sveltex.dev/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:
```sh
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
```sh
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
```js
// 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.
[SvelTeX extension]: https://marketplace.visualstudio.com/items?itemName=sveltex-preprocessor.sveltex
[TextMate grammar]: https://github.com/nvlang/sveltex/tree/main/extras/vscode-extension/syntaxes
[request forwarding]: https://code.visualstudio.com/api/language-extensions/embedded-languages#request-forwarding
## 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.
[acknowledgments]: https://sveltex.dev/docs/acknowledgments
## 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"`, and `text` may not be
the same. In particular, I had `workflow_run` events not triggering because
the needed workflow's name wasn't in quotes, but the `workflow_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.
[`fast-check`]: https://fast-check.dev
[`plop`]: https://github.com/plopjs/plop
[Shiki]: https://shiki.style
[`twoslash`]: https://twoslash.netlify.app
[VitePress]: https://vitepress.dev
[SSG]: https://en.wikipedia.org/wiki/Static_site_generator
[`node-poppler`]: https://github.com/Fdawgs/node-poppler
[ESM-only]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
[`create-sveltex`]: https://www.npmjs.com/package/create-sveltex
[Knip]: https://github.com/webpro-nl/knip