Stripping dollar signs from equations in Documenter.jl

First post here, and I don’t ask many questions in forums cause most of the time I find what I am looking for somewhere, but now I am stuck and couldn’t find a suitable solution in another topics. I’ve been using Julia daily for 1-2 years, but I am not as versed at it as I am in Python or C++, etc. I tried to solve what I am going to describe below by reading the sources of Documenter.jl but I found myself unable to find a workaround.

The problem

  • I have a toolbox where I pack modules with reusable code for my personal projects. These modules are documented with Documenter.jl and published as GitHub pages.

  • In this toolbox I also happen to take my study notes which are full of math (often these notes serve or will serve as theory guide to the implemented functionalities, so their logical place is in the toolbox).

  • Because it is awesome for managing internal links and real-time rendering of equations, I edit my notes with Obsidian. But Obsidian renders math with standard syntax, i.e., using $ and $$ for inline and blocks (already tried to solve with Obsidian extensions without success).

I cannot find a way of preprocessing my markdown files within Documenter’s make.jl and avoid extra steps to compile (generate HTML) my study notes and code documentation together.

(Possibly) related topics

My understanding is that I should add a layer of preprocessing to strip the files from $$ (single $ are properly recognized by documenter, not as a string interpolation for some reason). It seems that using Literate.jl would be the best way, but I can’t find a way to integrate it into my workflow.

I also considered generating stripped files on the fly, but I am trying to avoid that. I could prepend my file names with an underscore and generate the final files used by Documenter.jl during generation but managing .gitignore and the project structure would not be nice (out-of-standard).

Thanks for your help!

1 Like

I came up with a solution. For reference: here you have the make.jl for building the documentation and the module that implements the solution. I finally ended up with a simple regex, still need to improve it.