Detailed guides to painful problems, treatments & more

How Works

A behind-the-scenes tour of the quirky, custom tech of (especially the “bibliography first” design principle)

Paul Ingraham • 10m read readers often ask things like:

I have been publishing webpages since the dawn of the web in the early 90s, and is entirely based on custom code written either by me or contractors, a thick stew of technologies that facilitate efficient production of heavily referenced content, and highly automated ecommerce. I use a free Mac app, BibDesk, to manage a huge BibTeX bibliography; custom PHP extracts citations from that database for use on — an exotic setup, and the technological heart of the website.

I chuckle when people ask, “How can I get a website like yours?” It’s quirky and exclusive, by design. It could be imitated, but not easily!

Bibliography-first design: powering good footnotes

Top-notch referencing is so important to me that it has driven much of the design and technology of I manage a huge bibliographic database using an obscure database format used by academics, BibTeX. I manage the bibliography using a terrific Mac app BibDesk. My own articles are also stored in that database, and so they can be cited like any other reference.

The code for parses the BibTeX database and then uses the data to make web-ready citations in a variety of styles. For instance, I can create an concise inline citation or one with full bibliographic details for a footnote, all pulled from the BibTeX database and turned into complex HTML. (Footnote formatting is all automated too.1) If I tweak a citation format, every usage on the site changes in one stroke. Or, if I change the summary of a scientific paper, that update is reflected everywhere that summary is used — important when it has been cited a dozen times around the website!

This clever system was originally written by a friend of mine in about 2005, a programming prodigy who works for Apple and remains a coding tutor/mentor to me. We still get together for lunch regularly. Well, not so much since the pandemic. •sad trombone• •sigh•

And so I can write like a writer and cite on the fly with efficiency that would make a scholar envious. It’s a thing of highly abstract beauty. I get fan mail from librarians. I am not kidding.

The need for speed (and security)

I am obsessed with efficiency and automation, which is the only way one person can make a project like this financially viable. And so I have dozens of custom programs for automation of all kinds of common publishing chores: lots of shell, Perl, and PHP scripts.

A major goal is to have a publishing system that really gets out of my way and lets me write, write, write. Making websites is so complex and tricky that even the best tools available — and there are some amazing ones — are missing many features I consider essential (like the footnoting and referencing features), and include much more that I don’t need or like. There has always been a serious disconnect between my priorities and the nature of most web publishing tools.

After years of getting irritated by blogging platforms of every description, I decided the only hope was to write my own — as every writerly geek must eventually do. And so my production workflow is now lower friction than any other blogging platform I’ve ever used or heard of. Many publishing and formatting chores have been reduced to a few keystrokes.

The code weirdness — security by obscurity — also it makes the site much more trouble to hack than it’s worth. will never be directly harmed by a script kiddie, or probably even a sophisticated hacker — tempting fate!

The result of all this is fast, secure pages made of pure, organic, free-range HTML5 and CSS and little else — barely even any jQuery, which is extremely rare on the modern web.2

The tools

I’m old school: everything is hand-crafted. I write PHP, HTML, Javascript, Perl, and prose all in the venerable Mac text editor, BBEdit (“it doesn’t suck”), now sometimes in Nova as well, plus a bunch of other power-user tools:

Related Reading

Appendix: The making of a footnote (many hours of science wrangling to create one small footnote about hot kneecaps)

As you can see from the above, I take my footnoting really seriously technologically. But I also take them very seriously as a matter of scholarship.3 There are a lot of ways to do referencing wrong,4 so I work hard to understand and correctly explain relevant science. Preparing a new footnote — just a single, “minor” footnote for my IT band syndrome book — I was struck by what a huge process/ordeal it is for one teensy little number, both technologically and in terms of scholarship.

They’re like icebergs: there’s a lot more to them than you can see.

So this is the life cycle of a typical show-me-the-science footnote: one that’s interesting enough to deserve some real effort, but still not important enough to end up as anything much more than a wee footnote. It begins easily enough …

I do something like this two or three times per week, and have for many years now. And that’s how a typical footnote is born — in this case, one which shows (among other things) that about half of people with unexplained anterior knee pain have “hot” kneecaps.5


  1. And, of course, the footnote itself links nicely back to the document body. You can imagine what a headache it would be to “manually” create and rearrange thousands of footnotes. Imagine a large, heavily footnoted document … and then trying to add a new footnote somewhere in the middle! Yikes. Software handles all that: specifically, a custom Perl filter, quite powerful, inserting and renumbering new footnotes with the press of a button. Return to text.
  2. I do still use jQuery, but only in a couple key places. My articles are enhanced by just a handful of custom, vanilla Javascript (carefully avoiding the need for frameworks). For instance, my footnotes naturally just live in simple lists at the bottoms of pages, but with some special Js sauce, they can be displayed in the body of the document when you click a footnote number. In 2021, I started using some Alpine, an excellent and extremely light-weight alternate to jQuery for many common use cases.
  3. For an example, here’s a very serious citation:

    Patton D, McIntosh A. Head and neck injury risks in heavy metal: head bangers stuck between rock and a hard bass. BMJ. 2008;337:a2825. PubMed #19091761 ❐

    It turns out that head-banging, “a popular dance form,” constitutes “a definite risk of mild traumatic brain injury” and the study “helps to explain why metal concert goers often seem dazed, confused, and incoherent.” I can think of other reasons! Part of the reason I wanted to share this beautiful piece of science is that I grew up in a youth culture dominated by heavy metal — a small industry town in northern Canada, Prince George. I was surrounded by head bangers, and they were definitely dazed, confused, and incoherent. And worse! But there is a strong possibility that the daze preceded the heavy metal in many cases.

    The risk of neck injury also increases with head banging intensity — although less than one might expect, which we can infer from the way people are able to keep doing it.

  4. Ingraham. 13 Kinds of Bogus Citations: Classic ways to self-servingly screw up references to science, like “the sneaky reach” or “the uncheckable”.  ❐ 5807 words.
  5. Näslund J, Näslund UB, Odenbring S, Lundeberg T. Comparison of symptoms and clinical findings in subgroups of individuals with patellofemoral pain. Physiotherapy Theory and Practice. 2006 Jun;22(3):105–18. PubMed #16848349 ❐

    Researchers bone scanned and x-rayed 80 patients diagnosed with PFPS and with many common similar diagnoses eliminated, a nice “pure” selection of unexplained knee pain patients. They divided them into three groups: 17 with pathology, 29 with “hot” kneecaps (metabolically active), and 29 without any findings (5 dropped out). All patients and 48 healthy subjects without any knee pain were then interviewed and examined by a surgeon and a physical therapist.

    They could not diagnose the pathologies without the scans — all patients with pain tested about the same, and their symptoms were indistinguishable. Q-for-quadriceps angles were about 4˚ bigger in the afflicted, but the authors carefully explain that 4˚ too small to be reliably detected. The most interesting result of the study is that almost half the PFPS patients had kneecaps throbbing with metabolic activity — that’s a fairly strong pattern.