Taking notes with Markdown and LaTeX

You can view my public demo for this post here

Recently, I have been on a bit of a mission to improve my school workflow with software. Over the past month, I have built a cleaner student portal for my school and written a tool for automating in-class attendance. Alongside working on these projects, I have also been refining my notetaking system for school.

Since 9th grade, I have been taking notes in a private GitHub repository in markdown, and have been compiling them to HTML using a makefile for each course. While this system has worked ok, It has been far from perfect. Recently, I have been working very hard to give this system a much-needed upgrade. Here is the new tech stack:

• The Bazel buildsystem
• Markdown
• LaTeX
• MathJax
• Beamer
• Tikz & PGF
• Pandoc
• Zathura
• Starlark
• Github Actions CI

The idea is that every course I take becomes its own Bazel package, with subpackages for things like assignments, papers, notes, and presentations. I can compile everything just by running the command bazel build //:all. All builds are cached using Bazel’s build caching system, so when I run the command to compile my notes (I love saying that), I only end up compiling things that have changed since the last run. The setup for all of this is quite simple. All that is really needed is a Bazel workspace with the bazel_pandoc rules loaded (although I have opted to use some custom genrules instead). Using these rules, markdown files can be concatenated, and compiled into a PDF. I also use a modified version of the Eisvogel Pandoc template to make all my documents look a little neater.

In terms of workflow, I write all my notes as markdown files with embedded LaTeX for any equations and charts I may need. All of this is done inside of VSCode, and I have a custom tasks.json file that lets me press Ctrl + Shift + b to re-compile whatever I am currently working on. I also keep Zathura open in a window to the side for a nearly-live preview system.

A screenshot of my workspace

Now, the question came up of “how do you easily distribute notes and assignments to classmates and professors?”. That question got me stuck for a while, but here is the system I have come up with:

1. I write an assignment
2. I push it to the private GitHub repository
3. GitHub Actions picks up the deployment with a custom build script
4. Every document is built into a PDF, and packaged with a directory listing generated by tree -H
5. Everything is pushed to a subdomain on my website via GitHub pages
6. I can share documents via URL to anyone

This is almost entirely accomplished by a shell script and a custom CI script.

If you have any questions about this system, want me to write another post about it, or would like me to walk you through setting up a notes workspace of your own, contact me