TexConfiguration

types/handlers/Tex.ts:546-575

Configuration options for the TeX backend.

Properties

caching? CachingOptionstypes/handlers/Tex.ts:552

Options relating to Sveltex's caching mechanism for the compilation (TeX → DVI/PDF/XDV) and conversion + optimization (DVI/PDF → SVG → Svelte) steps.

cacheDirectory?string | undefinedtypes/handlers/Tex.ts:388

Directory in which to cache auxiliary files.

Default

`node_modules/.cache/@nvl/sveltex`

The default value indicated above is somewhat untrue. The actual default value is determined by the findCacheDirectory function from the find-cache-directory package, which will look for a package.json file in the current working directory or its parent directories, and will return the absolute path to the directory that the default value from above shows, relative to the parent directory of the package.json it found. If it doesn't find a package.json, or if the node_modules directory is unwritable, it will return undefined. In this case, SvelTeX will fall back to using XDG_CACHE_HOME via $XDG_CACHE_HOME/sveltex, or ~/.cache/sveltex if XDG_CACHE_HOME isn't set.

enabled?boolean | undefinedtypes/handlers/Tex.ts:364

If true, auxiliary files of named TeX blocks won't be removed from the cache directory after compilation. Auxiliary files of unnamed TeX blocks will still be removed from the cache directory after compilation.

If false, all auxiliary files will be removed from the cache directory after compilation.

Default true

compilation? CompilationOptionstypes/handlers/Tex.ts:557

Options relating to the compilation of TeX content to DVI/PDF files.

engine?"pdflatexmk" | "lualatex" | "lualatexmk" | "pdflatex" | "xelatex" | unde…types/handlers/Tex.ts:248

TeX engine to use to render TeX code. Possible values, alongside with the commands they use to compile the TeX code (depending on intermediateFiletype):

• 'pdflatexmk': Uses LaTeXmk, a Perl script which aims to simplify the compilation of complex LaTeX files which would usually require multiple compilation steps by determining the necessary steps and number of compilations, and performing them automatically.
  • latexmk -dvi to output DVI using pdfLaTeX.
  • latexmk -pdf to output PDF using pdfLaTeX.
• 'lualatex': Uses LuaLaTeX,
  • lualatex --output-format=dvi to output DVI.
  • lualatex --output-format=pdf to output PDF.
• 'lualatexmk': Uses LaTeXmk.
  • latexmk -dvilua to output DVI using LuaLaTeX.
  • latexmk -pdflua to output PDF using LuaLaTeX.
• 'pdflatex': Uses pdfLaTeX.
  • pdflatex -output-format=dvi to output DVI.
  • pdflatex -output-format=pdf to output PDF.
• 'xelatex': Uses XeLaTeX.
  • xelatex -no-pdf to output XDV.
  • xelatex to output PDF.

Default 'pdflatex'

Despite its name, pdflatex can indeed also output DVI files.

Why is pdflatex the default? — Speed. LuaLaTeX was significantly slower in my testing, LaTeXmk was marginally slower (but the working assumption is that the LaTeX files Sveltex will be dealing with will usually be simple enough to be compiled in a single step, limiting the benefit of LaTeXmk), and XeTeX was also marginally slower and is less wide-spread.

Disclaimer: my testing was very limited; in particular, I tested the different compilation commands on just four different TeX files, each of which were single-page documents (this is because single-page documents is the main use-case for Sveltex). See the benchmarks section of the SvelTeX docs for more info.

intermediateFiletype?"pdf" | "dvi" | undefinedtypes/handlers/Tex.ts:292

Intermediate filetype to use when compiling the TeX block. Possible values:

• 'dvi' (strongly recommended): The DVI (device independent file format) is TeX's original output format, and presents many advantages over PDF for the purposes of SVG conversion.
• 'pdf': If for some reason you need to use PDF as the intermediate filetype, you can set this property to 'pdf', which dvisvgm or Poppler can then convert to an SVG.

Default 'dvi'

This option is only relevant when conversion.converter is set to 'dvisvgm', as Poppler doesn't support DVI/XDV files.

If engine is set to 'xelatex', then setting this property to 'dvi' will result in the generation of XDV (extended DVI) files instead of DVI files.

Not all TeX engines and conversion libraries support all intermediate filetypes. All of the currently supported engines support PDF and DVI (or, in the case of XeTeX-based engines, PDF and XDV). The conversion library dvisvgm can handle PDF, DVI, and XDV, while Poppler can, of these formats, only handle PDF. In a table:

TeX Engine	dvisvgm	poppler
latexmk	dvi/pdf	pdf
lualatex	dvi/pdf	pdf
lualatexmk	dvi/pdf	pdf
pdflatex	dvi/pdf	pdf
xelatex	xdv/pdf	pdf

When using dvisvgm, it is almost always better to use 'dvi' as the intermediate filetype, since this is where dvisvgm really shines: it will produce much more optimized SVGs from DVI/XDV files than from PDF files, and has more features available when converting DVI/XDV files.

overrideCompilation?CompilationCliInstruction | null | undefinedtypes/handlers/Tex.ts:319

Override the compilation command for this component.

Default null

Warning Make sure that the command either generates a DVI/XDV (if intermediateFiletype is 'dvi') or PDF (if intermediateFiletype is 'pdf') file at opts.output.path.

Warning The following properties will be useless if this property is set:

• engine.
• shellEscape.
• saferLua.

Note The intermediateFiletype property will still be relevant, as it will help Sveltex determine how to convert the intermediate file to SVG. In particular, you should make sure that the command you set here generates a file of the type specified by the intermediateFiletype property.

saferLua?boolean | undefinedtypes/handlers/Tex.ts:334

Note This setting is only relevant if the engine property is set to 'lualatex' or 'lualatexmk'. Otherwise, it has no effect.

If true, some easily exploitable Lua functions will be disabled.

Warning luaotfload won't work if this setting is set to true, meaning that OTF font support may be limited.

Default false

shellEscape?boolean | "restricted" | undefinedtypes/handlers/Tex.ts:350

If false, shell escape is disabled, meaning that the TeX engine will not be able to execute shell commands (i.e., e.g., the minted LaTeX package won't work).

If equal to 'restricted', shell escape will be enabled, but only for a restricted set of commands; these are defined by the texmf.cnf file of the TeX distribution.

If true, shell escape is enabled without restrictions. Use this option with caution, and only if you trust the TeX code you are compiling.

Default false

conversion? ConversionOptionstypes/handlers/Tex.ts:562

Options relating to the conversion of DVI/PDF output to SVG files.

converter?Converter | undefinedtypes/handlers/Tex.ts:109

Library to use to convert PDF or DVI files to SVG.

• 'dvisvgm': Performant and feature-rich converter, bundled with TeX live. Produces high-quality, highly optimized SVGs.
• 'poppler' (PDF only): Robust library which relies on Cairo for its PDF to SVG conversion. Sveltex interacts with it via the node-poppler package. Poppler produces high-quality — if sometimes rather large — SVGs.

Default 'dvisvgm'

Warning For the 'poppler' option to work, you should install the node-poppler package, which isn't a regular dependency of Sveltex (it's a peer dependency instead, given its large size and the fact that Sveltex won't use it by default). Depending on your package manager, you can do this with one of the following commands:

pnpm add -D node-poppler # if using PNPM
bun add -D node-poppler # if using Bun
npm add -D node-poppler # if using NPM
yarn add -D node-poppler # if using Yarn

Furthermore, depending on your operating system, you may need to install some additional dependencies:

• Linux: Install poppler-utils and poppler-data:

  sudo apt-get install -y poppler-data
  sudo apt-get install -y poppler-utils

• macOS: Install the poppler formula from Homebrew:

  brew install poppler

• Windows: Binaries are already included with node-poppler, so no additional steps are needed.

---

Links

dvisvgm:

• Website: https://dvisvgm.de/
  • Manual page ("manpage"): https://dvisvgm.de/Manpage
• Repository: https://github.com/mgieseki/dvisvgm

Poppler & related:

• node-poppler on NPM: https://www.npmjs.com/package/node-poppler
• node-poppler repository: https://github.com/Fdawgs/node-poppler
• Poppler website: https://poppler.freedesktop.org
• Poppler repository: https://gitlab.freedesktop.org/poppler/poppler
• Cairo website: https://www.cairographics.org

dvisvgm?DvisvgmOptions | undefinedtypes/handlers/Tex.ts:135

Options to pass to dvisvgm when converting PDF or DVI files to SVG.

The documentation of the options herein are adapted from the official dvisvgm manpage.

Setting any given option to null defers its assignment to dvisvgm, meaning that dvisvgm's default value for the option will be used. Meanwhile, setting an option to undefined will set it to Sveltex's default value for the option, as specified in the @defaultValue TSDoc tag for the option. Note that Sveltex's default value will often be null itself, in which case setting the option to undefined will have the same effect as setting it to null. Sveltex's default value may also sometimes coincide with dvisvgm's default value for the option, even if Sveltex's default value isn't null.

These options will only have an effect if the converter property is set to 'dvisvgm'.

See: https://dvisvgm.de/Manpage/

See: https://github.com/mgieseki/dvisvgm

outputDirectory?string | undefinedtypes/handlers/Tex.ts:179

Output directory. This is where the generated SVG files will be placed, in the form of Svelte components. The first part of the path should be src, or at least a directory from which Svelte components can be imported via import Example from 'outputDirectory/example.svelte'.

Default 'src/sveltex'

Each SVG component will be written to ${outputDirectory}/${name}/${ref}.svelte, where:

• outputDirectory: the value of this property.
• name is the name of the component, usually the same as the HTML tag used for the component. In particular, this does not refer to the name of any one given instance of the component, but rather the name of a given class of TeX components.
• ref is the (mandatory) ref attribute of the component.

overrideConversion?ConversionCliInstruction | null | undefinedtypes/handlers/Tex.ts:197

Override the DVI/PDF/XDV to SVG conversion command for this component.

Default null

Warning Make sure that the command generates an SVG file at opts.output.path.

Warning The following properties will be useless if overrideConversion is set:

• dvisvgm;
• poppler;
• converter.

poppler?PopplerSvgOptions | undefinedtypes/handlers/Tex.ts:158

Options to pass to poppler when converting PDF or DVI files to SVG.

Setting any given option to null defers its assignment to node-poppler, meaning that the external library's default value for the option will be used. Meanwhile, setting an option to undefined will set it to Sveltex's default value for the option, as specified in the @defaultValue TSDoc tag for the option. Note that Sveltex's default value will often be null itself, in which case setting the option to undefined will have the same effect as setting it to null. Sveltex's default value may also sometimes coincide with node-popler's default value for the option, even if Sveltex's default value isn't null.

These options will only have an effect if the converter property is set to 'poppler'.

See: https://www.npmjs.com/package/node-poppler

debug? DebugOptionstypes/handlers/Tex.ts:569

Options relating to the console output produced by Sveltex while dealing with TeX content.

ignoreLogMessages?(string | RegExp)[] | undefinedtypes/handlers/Tex.ts:470

Log messages to ignore.

Default

[
    'Package shellesc Warning: Shell escape disabled',
    'LaTeX Warning: Package "xcolor" has already been loaded: ignoring load-time option "dvisvgm".',
    'Package epstopdf Warning: Shell escape feature is not enabled.',
]

The strings (resp. regular expressions) are checked for inclusion in (resp. matched against) the message that SvelTeX would print to the console (excl. filepath and line number), which may differ from the message as it appears in the original LaTeX log.

verbosity?"none" | "all" | "info" | "box" | "warn" | "error" | { onFailure?: "all"…types/handlers/Tex.ts:496-540

Lowest severity level of messages from LaTeX log to print.

• 'all': All messages will be printed.
• 'info': Print all info messages (incl. under- and overfull box messages), warnings, and error messages.
• 'box': Print under- and overfull box messages, warnings, and error messages.
• 'warn': Print warnings and error messages.
• 'error': Only print error messages.
• 'none': No messages will be printed.

This property can also be set to an object with onFailure and onSuccess properties, each of which can take the same values as the string values above, and will determine the verbosity of the log printed to the console on failed and successful compilations, respectively.

Default 'box'

If 'all' is selected, the entire log generated by LaTeX will be printed to the console, and the ignoreLogMessages property will be ignored.

optimization? OptimizationOptionstypes/handlers/Tex.ts:574

Options relating to the optimization of SVG files (SVG → .svelte step).

currentColor?{ … }types/handlers/Tex.ts:419

Try to make the SVG use currentColor as its default color by replacing all occurrences of the given color in the SVG code with 'currentColor'.

Default '#000'

Set this property to null to disable this feature.

Suppose this property is set to '#000'. Sveltex will then replace all occurrences of '#000', '#000000', and 'black' with 'currentColor'.

If conversion.converter is set to 'poppler', it will add fill="currentColor" to the (outermost) <svg> tag by default.

dvisvgm already includes options to achieve the behavior that this property aims to achieve (namely, the DvisvgmOptions.svg.currentColor). However, this present option can still be useful to take care of any potential edge cases that dvisvgm's currentColor option might not cover.

overrideOptimization?((svg: string, tc: TexComponent) => string) | null | undefinedtypes/handlers/Tex.ts:439-442

Override the SVG optimization function for this component.

Default null

Warning The following properties will be useless if overrideOptimization is set to anything other than null or undefined:

• svgo.

---

Function parameters

svgo?Omit<SvgoOptions, "path"> | undefinedtypes/handlers/Tex.ts:448

Options to pass to SVGO's optimize function when optimizing SVG files.