[Documentation] Contribution/Developer Guide

[thecodechemist99]

Hi there!

As I went deep into this project the last couple of days in an attempt to fix a bug that was (and unfortunately still is) bugging me, I thought it might be helpful to write up a bit of a starter guide for others interested to contribute (as also previously has been discussed in #8). This guide is based on the README files from all mentioned repos, info from several issues in this repo and my own analysis of the source code so far. It is quite the complex project, so please let me know if I got anything wrong and feel free to add information you find to be useful down below.

@artisticat1 if you would like to include this into a readme at some point, to make it more easy to find, feel free to do so.

---

General Functional Overview

This plugin consists of multiple core parts spread out into multiple repositories:

web2js

[!NOTE] I include this part for completeness, but it’s generally not required for contribution to the plugin.

web2js is used to compile the TeX compiler into WebAssembly. This is a fork of kisonecat’s version, with some changes made on the ww-modifications branch which I directly linked above.

It generates the files tex.wasm and core.dump that need to be included into tikzjax (see below).

These files have been previously generated by @artisticat1 and are already included in the source code, so unless you plan to change something specifically about this part of the implementation, it’s not required to compile them yourself.

The currently used files can be found in a previous version of this repo.

tikzjax

tikzjax takes TikZ code from script tags and converts it into SVGs. The version used in this plugin (linked above) is a modified fork of the ww-modifications branch of drgrice1’s version which in turn is a modified fork of kisonecat’s version.

The output-single-file branch is used to generate a tikzjax.js file which in turn is used in this plugin.

dvi2html

dvi2html i used within tikzjax to convert the intermediate dvi output from the TeX compiler to HTML.

obsidian-tikzjax

This plugin is mostly a wrapper around all the previously listed packages to integrate them into obsidian.

Development

[!NOTE] Instead of building web2js and tikzjax as detailed below, the docker configuration provided by @benrbray can be used. It allows to build both packages by running a single command (assuming docker and docker-compose have been installed). Afterwards, obsidian-tikzjax can be built as usual.

Building web2js

[!NOTE] This step can be skipped by using the provided core.dump.gz and tex.wasm.gz files. Also, this part is currently not working for me due to dependency issues.

[!WARNING] For this build a TeX installation on the system is required. Using a different installation than the LaTeX packages in tikzjax were extracted from might also lead to compatibility issues.

# Switch to the correct branch
git checkout ww-modifications

# Install dependencies
npm install

# Generate the pascal parser
npm run build

# Build and optimize the web assembly file
npm run generate-wasm
wasm-opt --asyncify --pass-arg=asyncify-ignore-indirect --pass-arg=asyncify-imports@library.reset -O4 out.wasm -o tex.wasm

# create the core dump file
npm run initex

# Optional: Test the created files
node tex.js sample.tex

The generated core.dump and tex.wasm are copied into the tikzjax repository.

Building tikzjax

# Switch to the correct branch
git checkout output-single-file

# Install depencdencies
npm install

# Build
npm run devbuild
# or
npm run build

This creates a dist folder containing tikzjax.js.

[!NOTE] New versions of the LaTeX packages can be included by running genTexFiles.js and encodeTexFiles.js bevore building tikzjax. However, taking these from another TeX installation than the tex.wasm and core.dump can lead to compatibility issues.

[!WARNING] Most included package files are listed in tex_files.json, but not all of them! Some, e.g. chemfig, were added manually to the tex_files folder by @artisticat1 because of issues with certain package versions. Generally, no packages requiring LuaTex can be used with tikzjax.

[!NOTE] The dist folder contains also a fonts.css file. This can be ignored as it is already included and doesn’t change between versions of obsidian-tikzjax.

The tikzjax.js file from the dist folder is then copied into the obsidian-tikzjax repository.

Building obsidian-tikzjax

# Build
npm run dev

Notes

• tikzjax has gulp as a dev dependency, I updated this to version 5.0.0 without any issues, as previous versions contain several severe vulnerabilities.
• tikzjax also required the fontforge package to be installed, which I did via homebrew (on MacOS): brew install fontforge.
• I was able to build everything successfully without real issues except web2js.
• Currently, the alternative docker build fails on ARM hosts, but this is an easy fix, see my pull request for comparison.

[artisticat1]

Hi - thanks for your work! I've included a link to this guide in the readme.

[thecodechemist99]

That’s great, thanks!