I switched from Emacs to Vim recently, and with that my beloved org-mode wasn’t really an option anymore, so I had to look for alternatives.
Furthermore I started to read more about digital gardens, wikis and general note-taking and knowledge-fostering.

Because of all this reading and my own preferences I had following criteria for my note-taking solution:

1. Notes should be easy to export
2. support
   • math equations (because school and because I want to have the ability to write math equations)
   • formatting like bold, italic, …
   • tables
3. Plain Text, so I could easily convert it to other formats, edit it in scripts,…
4. The filetype should be integrated in my editor, e.g. spell-checking, syntax-highlighting,… should be supported

Because I am in Vim and looking for a wiki software, I found VimWiki and I thought:

Hmm, that looks nice, I like the link thing they have going on and I like the ability to export my wiki to html. I am just gonna use this for my notes/wiki/stuff!

But I noticed, that they have their own syntax going on. I am not a very big fan of things like this, because criteria point 1.

But one language/fileformat has the ability to fulfill all my needs.

Drum roll

Markdown, who would have thought^^

It is super easy to export, because it’s just files on my filesystem and a well established format, it supports math equations, more on that later, formatting, tables, it is plain text and it is easily integrated into every editor.

Fortunately VimWiki also supports markdown syntax, but unfortunately it does not support exporting for markdown. Because I now wanted to have this feature, because it supports that for VimWiki syntax and I want to be able to read my notes on a nicely formatted webpage I had to find a way to convert VimWiki files in markdown to a webpage.

And as we all know, there rarely are firsts, so other people already had this problem and wrote a solution.

I tried one after another, but none of them worked, namely because of python2 or some other obscure errors.

I found one script that worked, tho. I even edited the source code for that to support stuff like a table of contents or math equations (I only had to add the extensions to the markdown formatter, so no big deal).

The thing is, that script displays math equations on the webpage using Katex. And I am not that big of a fan of javascript or external dependencies, because I want to be able to view my notes/wiki offline. So I set out to fix that myself.

I once heard, that Pandoc supports math formulas for markdown, so I took a test case, put it in my wiki and converted that file using pandoc. Opened it in my browser and:

Hmm, those infinity signs do look a bit off, but eyy, it works. Let’s try fractions.

Well fuck, why doesn’t this work?

One quick internet search later and we have the answer:

Pandoc supports latex math formulas for markdown, but no without external dependencies for html. The first test case worked, because it found a unicode char for every char in the formula. But you can’t properly display fractions or roots with unicode.

So I had to bite the bullet and use Katex after all.

Gave Pandoc the --katex argument and tada:

Everything looks good now.

But if you think: “Alright, so he’s just gonna use that original script for VimWiki”, you thought wrong. Because I am me I had to write my own script, to have complete control.

My criteria for my script:

1. convert my wiki to html and pdf
2. no external dependencies
3. have VimWiki links work

For point three:

Vimwiki has a thing going, where if you write a link in markdown syntax and you press Return, it takes you to that file. I write those links like that:

[Test](misc/test)

Without file extension.

If Pandoc were to convert that to a html link, something like this would come out:

href="misc/test".

This of course doesn’t work, so I had to sed the hell out of those files to make them convertible. And of course there are special cases. For example:

[Test](misc/test.html)

We don’t want to add a .html there, because then that link is broken.

Or:

![Test](/assets/images/test.png)

This would also break, because a .html would be appended.

So behold my glorious link detection regex:

\[.+\]\((?!https?:\/\/).*(?<!\.html|\.png|\.svg|\.jpg)\)

It matches every string with the following format: [text](link), but discards the ones where the link starts with https, or ends with .html, .png, .svg, .jpg.

I basically loop through ever match, and replace the detected link with a proper link.

For point 2:

I have to rely on Katex to render my math, so there we have an external dependency. There isn’t really anything I can do about that, if I want to have beautiful math, and I want to have beautiful math. The only thing that I can do:

I downloaded the Katex fonts, the CSS and the javascript and stored it locally. So, at least, I don’t need internet connection.

For point 1:

I want to be able to convert my notes/wiki to two different formats. One is html and the other one is pdf (this is only for my university notes).

For both I use Pandoc with a “custom” template (I basically just adjusted the default one a bit) and my custom CSS.

Because I also use this setup for note-taking in class, I want to be able to export all my notes to one single pdf, so that I can easily print it, if I choose so. This is relatively easy with pdfunite. So I first convert all the pages and then feed them all to pdfunite, resulting in one single pdf file with all my notes.

The only thing with the pdf export is, that internal links don’t work, but this also could be fixed with a bit of regex I wager, and will probably be fixed in a future iteration.

The script can be found here.

If you want to use it, change the cd dir in the run script to your notes directory, you can probably remove the last rm line and change the path after the exec arg in the find command to the path of the build.sh script.

In the build.sh script, set the appropriate output dir and change the path for the template arg for pandoc to the appropriate location. The style.css file has to reside in the html output dir.

You can find my css and template file together with the scripts in the git repo.

To get katex working, download this tarball, extract it, create a assets folder in the html output dir, with css and js as a subdir, copy katex.min.css and the fonts folder from the tarball to assets/css and katex.min.js to assets/js.

Now everything should work.

Conclusion

I hope you could follow the post, and I hope it wasn’t to confusing. I might rework it in the future, but I just want to get it out a now and not sit on if for an eternity and don’t release it at all.

If you have any question, feel free to email me, you can find my email in the footer of this page, or send me a message on Mastodon.