HTML Conversion - Linus-Mussmaecher/rucola GitHub Wiki

Rucola can convert markdown notes to HTML documents, which are stored in the .html subfolder of your vault directory. This allows you to view 'compiled' versions of you notes that are nicer to read using your configured HTML viewing application (see Configuration).

This feature uses comrak for the markdown-HTML conversion and supports most of the usual markdown syntax.

Conversion

Conversions happen at the start of the program for any note (because otherwise, rucola cannot be sure there have been no external changes since then) and then whenever rucola detects a content change to a note file within its vault folder.

If you do not wish for these automatic conversions to happen, the automatic HTML feature can be disabled in the Configuration.

CSS

HTML files are automatically prepended with a .css stylesheet reference if you have configured a source .css file in your Configuration. Two default .css files are provided with rucola, for dark and light mode respectively.

LaTeX support

If rucola detects math in your note (delimited by either $...$ or $$...$$), it will append a KaTeX preamble to the HTML file, causing this code to be rendered as LaTeX. This feature can be turned off in the Configuration.

Additionally, you can define a set of KaTeX macros that closely imitate LaTeX macros. See here for a description of syntax and functionalities. The only difference between rucola and raw KaTeX is that you will need to give the map of macros in TOML format, i.e.

{"\\field": "\\mathbb", "\\liealg": "\\mathfrak"}

becomes

[math_replacements]
'\field' = '\mathbb'
'\liealg' = '\mathfrak'

Note in particular that backslashes do not need to be escaped in TOML as they do in JSON.

Syntax Highlighting

If rucola detects code blocks in your note (delimited by one or more backticks `...`), it will append a highlightjs preamble, causing code to be rendered with syntax highlighting in the HTML.

View HTMLs

The created HTMLs can be viewed from within the application, both from the Select Screen (with M+V) or from the Display Screen (with V). Alternatively, the HTMLs are saved in the .html subfolder of your vault and can be accessed from there.