Blog

My math-intensive learning notes are hosted in this blog. Built with:

• Hugo: a popular static site generator for blogs, with PaperMod as base template, MathJax support, and hugo-cite for citation support.
• Quarto (example post): via hugo-md support, with Pandoc as the universal converter, for:
  • academic writing
  • Jupyter and Observable JS notebook integration
• Typst (example post)
  • PDF rendering
  • SVG rendering for a more friendly Web experience.

The illustrative diagrams in this blog aim to be reproduceable, they are made by one of:

• Pikchr: an open-source text-to-diagram tool, the language is simple yet has great support for relative positioning and flexible path guiding.
• D2, a modern diagram scripting language, preferred over PlantUML, Mermaid, and Graphviz, for its great layout support for complex diagrams and its declarative design.
• draw.io: an open-source semi-auto feature-rich diagram tool, using .drawio.svg format to be both editable and web-presentable.
• TODO: TiKZ with static generation powered by TinyTeX that comes with Quarto.

Local Development

Install the following tools per instructions:

• Hugo: 0.125.2+
• Quarto: 1.5.39+
• D2
• Watchexec

Or simply run the following on MacOS if you have Homebrew installed:

brew install hugo quarto d2 watchexec

Particularly, Pikchr will be installed from source by scripts/make_pikchr.sh on first run.

Find out which Python Quarto is using:

quarto check

and use it as python3 in the following commands:

python3 -m pip install jupyter --break-system-packages
python3 -m IPython kernel install
python3 -m pip install -r requirements.txt --break-system-packages

--break-system-packages is needed if you are using a system Python installation, installed by brew for example, which is the one used by quarto for me under MacOS, despite that I'm already using pyenv to manage Python versions.

Install Julia for Quarto notebook support:

brew install julia

Initialize the submodules for Hugo themes and extensions:

git submodule update --init --recursive

Run the following to make D2, Pikchr diagrams and Typst documents for the first time:

./scripts/make_all.sh

Finally, run ./scripts/dev.sh to do the following 3 tasks in on go.

If you are simply working on a vanilla markdown post, just run:

hugo serve -w --forceSyncStatic --disableFastRender --ignoreCache --noHTTPCache # --gc --cleanDestinationDir

then navigate to something like http://localhost:1313/blog/ in your browser, as prompted.

If you are authoring with Quarto, run in a separate terminal:

quarto preview --no-serve --no-browser --render all

If you are authoring with Typst/D2/Pikchr/Bibliography, run in a separate terminal:

# watchexec --ignore-nothing -vvv --project-origin . -w content/posts/math-2024 -e d2,pikchr,typ,bib --only-emit-events --emit-events-to json-stdio --print-events --notify --poll 500ms
watchexec --on-busy-update queue --poll 500ms -e d2,pikchr,typ,bib --emit-events-to=stdio -- ./scripts/make_changed.sh