An integrated book and website

Over the past year, I wrote and compiled - literally hundreds of times - a textbook on making music with SuperCollider. The book, “Komposition og lydproduktion med SuperCollider”, was published in June, 2025, under the CC BY-SA 4.0 license.

In this series of blog posts I’ll explain how I set up a system that produces a nicely typeset PDF version of the book integrated with a full web version with audio examples. What makes this setup unique is the close integration between the PDF and web versions. Readers can jump directly from a code example in the PDF to the corresponding audio example on the website, where they can listen to it and explore it interactively.

I taught composition with SuperCollider at Aalborg University for the better part of a decade. Much of the book’s content came from lecture notes I had written and shared with students over the years. A few years ago, I collected these notes, converted them to markdown, and put them on a website using mkdocs.

Using the site as reference material in classes, it became clear to me that the site’s introductions to composition and audio synthesis techniques filled a gap in the Danish-language literature on computer music. With the included cheat sheets and exercises in SuperCollider, the site was a useful resource for my students.

Then, in the summer of 2024, I was introduced to AAU OPEN, an Open Access publication platform for the faculty of Aalborg University. I had been thinking of turning the website into a textbook, and AAU OPEN was the right place to finally make this happen.

While I would not recommend this developer-oriented workflow for everyone, there are compelling reasons for this decision:

• Fine-grained integration between website and PDF: In the PDF, I can automagically link to the exact location on the website of an audio example related to piece of code. This might not seem like a big deal, but compared to what most publishers of academic books with online audio examples, this is by far the most reader-friendly integration I have seen so far.
• Both formats available: Readers can switch between formats and use whichever version is more suitable for the reading situation.
  • A PDF is great for in-depth studies. The linear format of a PDF document makes it easier to read and reference large amounts of material.
  • The web excels at interactive features like scrubbable audio examples and code examples which can easily be copied.

• Combining the power of LaTeX and the simplicity of markdown: I write the content in the simple markdown format, but the PDF is produced with LaTeX’s powerful typesetting engine. While some authors have to write in LaTeX directly, it’s a much more verbose markup language that I’d prefer to not write in directly (the exception here is about writing math, where LaTeX’s syntax actually has been adopted by various other frameworks).
• A single source of truth: The two versions are produced from the markdown source files and attached media. As an author, I only need to change the source in one place if I want to correct a typo or add a section.
• The benefits of version control: All changes to the source files are tracked with git, which makes listing changes between successive future editions of the book trivial.
• Recognition and circulation: The book’s official ISBN record allows my work to be recognized and circulated widely in academic search engines and indexes.

The book’s sections exist as a set of markdown files, accompanied by image and audio files, which mkdocs uses to generate the web version as a static site. While there are ways of converting markdown documents to PDF directly, I chose to use LaTeX as an intermediary format. LaTeX is widely used in academia, and when set up with care, it can produce beautifully typeset publications without the hassle of WYSIWIG editors. However, maintaining both LaTeX and markdown versions of the source files seemed inefficient. Unless…

What if we could automate the conversion from markdown to LaTeX, and from there to a PDF file? Markdown’s syntactical categories are relatively simple and should, at least in theory, have corresponding structures in LaTeX. So I set out to build a system that would produce a nicely typeset and fully functional PDF using LaTeX, from the same sources that mkdocs uses to produce the website. This approach is similar to Continuous Integration, allowing the web and PDF versions to remain synchronized and up-to-date.

In the next part of this series, I’ll go over how I automated the conversion of markdown to LaTeX with a Python library called md2tex.