Making-Of

I’m occasionally asked how I put my site together. In short: AsciiDoc and MathJax.

On some pages, there’s an Easter egg of sorts. Replace html with lhs in the URL to see its source:

I have a few public Github repos containing the source of entire subsites, such as:

Those who can’t, do anyway

I’m neither a frontend engineer nor a web designer, but I find what I do works well enough.

I write best with a text editor using old-school text file and email conventions, such as minus signs or asterisks for list bullet points, and LaTeX notation for equations. The minimalist distraction-free environment makes me want to churn out line after line. Or maybe it subconsciously reminds me of long and glorious coding sessions, of heated debates on mailing lists, and of rushing to meet thesis deadlines, and I just go with the flow.

AsciiDoc turns classic text file flourishes into pretty HTML, and MathJax turns LaTeX into pretty equations rendered with JavaScript. I first encountered AsciiDoc when looking at Git documentation, and I wound up choosing it over its competitors for the same reasons Linus Torvalds did: it’s fairly well-defined and powerful, yet the source text looks nice. (Though one annoyance is dealing with tildes in URLs, like on this very page!)

A custom script automates building pages. It deals with things like CSS; Google Analytics; including a menu HTML file if appropriate. This lets me acheive my ideal workflow: type, type, type, run script, type, type, type…

I’m unsure about publishing my script because it also performs some egregiously idiosyncratic source transformations. It’s a long story. I once used itex2MML, which defaults to LaTeX delimiters, that is, dollar signs for inline equations and backslash-square brackets for display equations.

AsciiDoc with MathJax is different, and in some ways better. They use characters that clearly indicate whether they’re starting or ending an inline equation as opposed to the same symbol (dollar sign) all the time. If I were starting out today, I would follow their guidelines.

I was too lazy and too stubborn to change existing documents and my habits, so my script translates dollar signs to the correct notation. I’d advise against following my lead because my fragile search-and-replace gets some cases wrong, which I must work around carefully. My script is also tied to Asciidoc; these days there’s Asciidoctor, which I heard improves on the original.

My script changes LaTeX-style code blocks (\begin{code} and \end{code}) into AsciiDoc code blocks, so that the same file can serve as a Haskell program as well as a webpage documenting the program. In some cases, I’ll compile the Haskell to JavaScript or WebAssembly, and have the webpage run the program it describes in the browser.


Ben Lynn blynn@cs.stanford.edu 💡