Taking notes with Markdown and LaTeX
Using a lot of tech to replace a piece of paper
2020-08-23 pandoc latex bazel
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:
- I write an assignment
- I push it to the private GitHub repository
- GitHub Actions picks up the deployment with a custom build script
- Every document is built into a PDF, and packaged with a directory listing generated by
tree -H - Everything is pushed to a subdomain on my website via GitHub pages
- 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
Thank you for reading this post. If you enjoyed the content, and want to let me know, or want to ask any questions, please contact me via one of the methods listed here. If you would like to be notified about future posts, feel free to load my rss feed into your favorite feed reader, or follow me on Twitter for notifications about my work and future posts.
If you have the time to read some more, I recommend checking out one of the following posts: