Configuration

Rucola requires three configuation files:

• config.toml: The main TOML configuration file. See below for its entries.
• <style>.toml: A TOML style file to customize the appearance of rucola itself. The exact name is given in config.toml. See Style for its entries.
• <cssstyle>.css: A CSS style file to customize the appearance of the HTML files created when converting markdown notes.

Defaults

One default config file, 2 TOML style files (light & dark theme) and 2 CSS style files (light & dark theme) can be found in this repository's default_config folder. These files should be installed on your system by any install method into rucola's default config folder, which should be:

• ~/.config/rucola on Linux
• C:\Users\<User>\AppData\Roaming\rucola on Windows
• /Users/<User>/Library/Application Support/rs.rucola on MacOS

On update or reinstall, already existing files will not be replaced.

Options

This describes the options in the main config.toml file.

File management

• vault_path is the path to your default root path to open on launch. All notes in this folder will be indexed and shown in the initial Select Screen. Can be overridden with a positional argument.
• file_types lists all types of files to be indexed by rucola when opening a folder. Per default, this is set to ["markdown"], tracking files with the extions .md, .markdown, ... A full list of available file types can be found here. It is currently not possible to define your own file types. Note that your files still need to contain valid markdown or at least plaintext to be parsed, even with a differing extension.
• default_extension is the default extension to append to newly created notes, .md by default.

Looks

• theme specifies the name of .toml file that contains information about the look and colors of rucola. This file has to be contained in the config folder desribed in the initial paragraph. This option can be overridden by passing the -s flag along with another file name to the application. See Style for more information.
• stats_show specifies which statistics to show on the Select Screen. It can have one of three values:
  • Both: Always show both local and global stats.
  • Local: Always show only local stats. Note that you can still see the same values as global stats when using an empty filter.
  • Relevant: Show global stats if there is no filter applied and local if there is. This setting therefore avoids showing duplicating stats at all times.

External programs

• editor configures the command to edit your notes. This is a list of strings. The first entry will be treated as an application name, all further entries represent arguments to that command. The special argument %p will be replaced by the path of the note to be opened. If this value is not set, rucola tries to use your $EDITOR environment variable or system default application.
• viewer configures the command for your HTML viewing application. The first entry will be treated as an application name, all further entries represent arguments to that command. The special argument %p will be replaced by the path of the note whose HTML is to be opened. If this is not set, rucola tries to use your systems default application for HTML files.

Tip

For some inspiration and useful tricks such as opening notes in an existing editor instance, take a look at the examples provided in External Applications.

HTML conversion

• enable_html is set to true by default. When enabled, HTML versions of your files will be created and updated on launch and continuously in the background. Set this to false if you do not want to use the view-as-HTML-feature, shutting down all automatic creation of HTML files. In this case, you can still open single HTMLs (which will be created on demand), but no follow links in those files.
• css is the name of your css style sheet, which has to be located in your rucola config folder. The .css file extension can be omitted. If not set, no css file will be added to your HTML files.
• katex is set to true by default, but can be set to false to never prepend a KaTeX preamble to HTML files. If set to true, KaTeX-headers are appended to all files in which math (delimited by single or double $-signs) was detected, causing this math to be rendered as LaTeX.
• math_replacments is a map from strings to strings, respectively the name and value of a KaTeX macro, only in TOML instead of JSON format. This allows you to use small LaTeX convenience macros, such as replacing $\field{R}$ with $\mathbb{R}$ or similar. See HTML conversion for more details .
• html_prepend can contain any text you want to prepend to all your HTML files in addition to the KaTeX, css and title.

Important

If you do not wish for rucola to continuously create HTML files of your notes, remember to set enable_html to false.