I am a big-time and longtime fan of Obsidian- it is my note-taking tool of choice both for its usability and, just as importantly, its ethos of avoiding the travails of lock-in. However, my use of it recently plateaued- perhaps, even dropped off a cliff- when I started working on creating a personal static website using Jekyll. This seemed absurd to me as the reason to build the website was that it generated pages from Markdown.

Part of the reason was that I was a novice website builder who had the tools but not the wisdom to integrate them. To move fast at getting a website running that wasn’t merely Obsidian Publish (which is excellent¹!), I used the Academic Pages template- again, a great open source template to get oneself out there. I then started working with ChatGPT and Claude to start tweaking that template to get it to have more of a Tufte-style using the excellent example of clayh53’s Jekyll site. Merging this work into my template continued to drive my Obsidian use and, more generally, my writing as my focused turned to battling CSS and HTML in Vim with LLMs. I had never been further from my vision of a seamless writing and publication workflow that integrated Obsidian to Jekyll- all of that code wrangling had also not got me closer to a site whose appearance matched my taste ². I was lamenting the loss of Obsidian and knew deep down that I had to embark on a second disparate journey that let go of this template. The current site is the result of this effort.

In January 2025, I happened to stumble into a tweet that linked to this post by Steph Ango on how he had was building his website from Obsidian leveraging Obsidian’s Git plugin, Jekyll, Github, and Netlify- this sounds like a lot but believe me, reader, the initial setup is worth it and can be done under one hour³. I also like thinkg that one day, what I write could be circulated- I saw Steph Ango uses ButtonDown to send out newsletters of some posts so thought why not put in the overhead now to get the potential for circulation out even if I never use it. This blogpost made ButtonDown sound like a nice alternative to other options and used the guidance for integration into Jekyll is here.

With the site built and ready for publication, I can officially say that my writing to publication workflow matches the friction-free vision I had. I am currently writing this post in markdown in Obsidian- no more use of Vim or Cursor for editing Markdown⁴. Anyone who has written notes in Obsidian for a while knows why it’s a desirable tool to work with. I can’t place my finger on it but I think it is fantastic as a place to think, even without all the bells and whistles- an IDE-style writing vibes that’s also minimal is criminally undervalued.

Tufte customizations

The Jekyll customisations of the Tufte theme of this site is an attempt to create a design with the look and feel of Edward Tufte’s books and handouts but with my own twist. My core philosophy is to get the good parts of Tufte by maximising the use of Markdown while minimising the use of Liquid tags which are really irritating to work with for fast writing. However, I am not directly lifting the Tufte style as I think there are things it could do better; instead, I am working with Cursor to adapt clayh53’s SCSS⁵ to meet my needs.

Fundamentals

Headings

Like Tufte, I am trying to work with three levels of headings, tops- though more specific headings are not encouraged, I do have the option to go 6 levels deep. The following passage from Tufte is pretty interesting to consider:

[It is] notable that the Feynman lectures (3 volumes) write about all of physics in 1800 pages, using only 2 levels of hierarchical headings: chapters and A-level heads in the text. It also uses the methodology of sentences which then cumulate sequentially into paragraphs, rather than the grunts of bullet points. Undergraduate Caltech physics is very complicated material, but it didn’t require an elaborate hierarchy to organize.

Tufte site

The headings all make us of the Aniron font, which is free for non-commercial use, which this site is.

Text

Inspired by Gwern, I have instead made use of the Aniron font and make all the content of the first line of any post in all caps; the first character of any post makes use of dropcaps () That’s because I wish to minimise my use of Liquid tags. Much of this was setup for me by Claude in Cursor- some css tweaking and a little bit of javascript and html magic. Instead Tufte starts each section with a bit of vertical space, a non-indented paragraph, and sets the first few words of the sentence in small caps. http://www.edwardtufte.com/tufte/books_be . Outside of that body of the text currently makes use of GIll Sans.

Epigraphs

The following are examples of epigraphs, generated on this website without Liquid tags.

The English language . . . becomes ugly and inaccurate because our thoughts are foolish, but the slovenliness of our language makes it easier for us to have foolish thoughts.’

George Orwell

Politics and the English Language

For a successful technology, reality must take precedence over public relations, for Nature cannot be fooled.

Richard P. Feynman

What Do You Care What Other People Think?

This first of these examples is generated using Markdown formatting with the following snippet:

> The English language . . . becomes ugly and inaccurate because our thoughts are foolish, but the slovenliness of our language makes it easier for us to have foolish thoughts.'
> 
> George Orwell
> 
> Politics and the English Language

Note that this is created using Markdown; the first example of my getting rid of using Liquid tags thanks to Claude and Cursor. This allows a nice readable version of the epigraph in Obsidian as and a reasonably informative version on the site.

Lists

Lists can be generated in standard markdown syntax but Tufte CSS points discourages using lists

while lists have valid uses, they tend to promote ineffective writing habits due to their “lack of syntactic and intellectual discipline”. He is particularly critical of hierarchical and bullet-pointed lists.

Tufte CSS

It says that a writer must, instead, ask themselves:

• Would my idea be better expressed as sentences in paragraphs?
• Is my message causally complex enough to warrant a flow diagram instead?

More excerpts from Tufte CSS:

A better way to understand Tufte’s thoughts on lists would be to read “The Cognitive Style of PowerPoint: Pitching Out Corrupts Within,” a chapter in Tufte’s book Beautiful Evidence, excerpted at some length by Tufte himself on his website. The whole piece is information-dense and therefore difficult to summarize. He speaks to web design specifically, but in terms of examples and principles rather than as a set of simple do-this, don’t-do-that prescriptions. It is well worth reading in full for that reason alone.
For these reasons, Tufte CSS encourages caution before reaching for a list element, and by default removes the bullet points from unordered lists.

Tufte CSS

Sidenotes

Tufte’s style is well known for its extensive use of notes in margins- this was one of the driving forces for me modifying my previous site’s template. My sense is that footnotes are disorienting for readers (this is how I feel but YMMV). Tufte’s sidenotesThis is a sidenote and displays a superscript display a superscript, similar to numbered footnotes but make for a much more pleasant reading experience; they lack the disorienting scrolling behaviours of footnotes. However, I have to be very judicious with using sidenotes as it requires using Liquid tags, which looks like this in markdown

<label for='sn-id-xx' class='margin-toggle sidenote-number'></label><input type='checkbox' id='sn-id-xx' class='margin-toggle'/><span class='sidenote'>This is a sidenote and *displays a superscript* </span>

I might work on getting this addressed in the future; but this is quite a low priority item as it is not just a matter of converting footnotes into sidenotes via Jekyll but also requires personal judgment. Is it worth never having footnotes? Longer form content in such tangential notes work better as footnotes than sidenotes. Perhaps footnotes are the kind of thing that become longer posts. And sidenotes are essentially some kind of staging for footnotes? And perhaps in there lies a virtuous cycle of writing short form with the vision of making it long form.

Margin notes with Figures

The following Liquid tag snippet in my markdown file renders the margin note to the right ⊕This is a margin note.

 <label for='mn-id-whatever' class='margin-toggle'> &#8853;</label><input type='checkbox' id='mn-id-whatever' class='margin-toggle'/><span class='marginnote'>This is a margin note. </span>

As you can see, this uses Liquid tags which makes for poor reading my markdown file and I am trying to eliminate their use as much as possible, even though the reading experience can be superior. So, at this moment, I am optimising for my writing process over reading⁶. Thus, I use such notes sparingly.

Main Column Figures

One place that you will see margin notes appear is when I insert an image, like of this rhino:

which is generated using Markdown as so:

<figure><img src='/assets/OldSite/rhino.png'/><figcaption class='marginal-caption'>F.J. Cole, “The History of Albrecht Dürer’s Rhinoceros in Zoological Literature,” <em>Science, Medicine, and History: Essays on the Evolution of Scientific Thought and Medical Practice</em> (London, 1953), ed. E. Ashworth Underwood, 337-356. From page 71 of Edward Tufte’s <em>Visual Explanations</em>.</figcaption></figure>

Within Obsidian, this gives me an image (without captions, which I can live with for my writing). On the website, I have been able to build in some nifty behaviour with Claude: on bigger screens, captions appear on the right margin of an image but, on mobile screens, defaults to being beneath the image. I think this optimises for both writing and reading experiences. I think the beauty of this can be best experienced in The winds have been howling for a hundred years at NASA’s Virginia Research Center, a photographic celebration of NASA Langley’s centenary year )translated from Hungarian to English ⁷).

Full Width Figures and Margin Figures

Ultra wide images and images in the margin are also possible but I don’t have a good Liquid tags-free solution for either. There is probably a time and place to use these types of figures. The below is a great example of when full width looks great and is useful:

This needs custom liquid tag but is unwieldy to write:

{% fullwidth 'assets/OldSite/napoleons-march.png' 'Napoleon's March *(Edward Tufte’s English translation)*'  %}

⊕
From Edward Tufte, Visual Display of Quantitative Information, page 92

Using Liquid tags permits margin figures which again reads poorly and is a pain to write in Obsidian (or any editor for that matter⁸):

{% marginfigure 'mf-id-whatever' 'assets/OldSite/rhino.png' 'F.J. Cole, “The History of Albrecht Dürer’s Rhinoceros in Zoological Literature,” *Science, Medicine, and History: Essays on the Evolution of Scientific Thought and Medical Practice* (London, 1953), ed. E. Ashworth Underwood, 337-356. From page 71 of Edward Tufte’s *Visual Explanations*.'  %}

So, I think in most cases, I will be using the general markdown <figure><img src='/Image_file_or_link'/><figcaption class='marginal-caption'>Caption</figcaption></figure> syntax, and let Jekyll convert that into images with margin captions.

Equations

The Markdown parser being used by this Jekyll theme is Kramdown, which contains some built-in Mathjax support. The only thing I am unhappy about is the way inline math currently works. For instance, the following inline sequence:

When \(a \ne 0\), there are two solutions to \(ax^2 + bx + c = 0\)

is written by enclosing a Mathjax expression within a matching pair of double dollar signs: $$ like so:

When $$ a \ne 0 $$, there are two solutions to $$ ax^2 + bx + c = 0 $$

This renders poorly in Obsidian; where the equation is shown in a new line. Not a huge deal breaker but Obsidian is well capable of handling the more standard $ a \ne 0 $ with single dollar signs either side of he equation. Outside of that, equations work about as expected.

Similarly, this block-level Mathjax expression is written by enclosing the expression within a pair of $$ with an empty line above. You can get pretty fancy, for instance, the wave equation’s nabla is no big thing:

All of the standard L^aT_eX equation markup is available to use inside these block tags so I won’t go into that here. Do note that the block-level Mathjax expressions must be on their own line, separated from content above and below the block by a blank line for the Kramdown parser and the Mathjax javascript to play nicely with one another. As clayh53 notes:

The Mathjax integration is tricky, and some things such as the inline matrix notation simply do not work well unless allowances are made for using the notation for a small matrix. Bottom line: If you are using this to document mathematics, be super careful to isolate your L^aT_eX blocks by blank lines!

Clearly much room for improvement here- my main gripe being the handling of inline math.

Tables

Tables can be done in many ways so I have lifted the below directly from clayh53 Tables are, frankly, a pain in the ass to create. That said, they often are one of the best methods for presenting data. Tabular data are normally presented with right-aligned numbers, left-aligned text, and minimal grid lines.

Note that when writing Jekyll Markdown content, there will often be a need to get some dirt under your fingernails and stoop to writing a little honest-to-god html. Yes, all that hideous <table>..<thead>..<th> nonsense. And you must wrap the unholy mess in a <div class="table-wrapper"> tag to ensure that the table stays centered in the main content column.

Tables are designed with an overflow:scroll property to create slider bars when the viewport is narrow. This is so that you do not collapse all your beautiful data into a jumble of letters and numbers when you view it on your smartphone.

⊕Table 1: A table with default style formatting

This is not the One True Table. Such a style does not exist. One must craft each data table with custom care to the narrative one is telling with that specific data. So take this not as “the table style to use”, but rather as “a table style to start from”. From here, use principles to guide you: avoid chartjunk, optimize the data-ink ratio (“within reason”, as Tufte says), and “mobilize every graphical element, perhaps several times over, to show the data.Page 139, The Visual Display of Quantitative Information, Edward Tufte 2001. Furthermore, one must know when to reach for more complex data presentation tools, like a custom graphic or a JavaScript charting library.

As an example of alternative table styles, academic publications written in L^aT_eX often rely on the booktabs package to produce clean, clear tables. Similar results can be achieved in Tufte CSS with the booktabs class, as demonstrated in this table:

⊕Table 2: A table with booktabs style formatting

The table above was written in HTML as follows:

<div class="table-wrapper">
<table class="booktabs">
          <thead>
            <tr><th colspan="2" class="cmid">Items</th><th class="nocmid"></th></tr>
            <tr><th class="l">Animal</th><th>Description</th class="r"><th>Price ($)</th></tr>
          </thead>
          <tbody>
            <tr><td>Gnat</td>     <td>per gram</td><td class="r">13.65</td></tr>
            <tr><td></td>         <td>each</td>    <td class="r">0.01</td></tr>
            <tr><td>Gnu</td>      <td>stuffed</td> <td class="r">92.50</td></tr>
            <tr><td>Emu</td>      <td>stuffed</td> <td class="r">33.33</td></tr>
            <tr><td>Armadillo</td><td>frozen</td>  <td class="r">8.99</td></tr>
          </tbody>
</table>
</div>

I like this style of table, so I have made it the default for unstyled tables. This allows use of the Markdown Extra features built into the Kramdown parser. Here is a table created using the Markdown Extra table syntax to make a nice table which has the side benefit of being human readable in the raw Markdown file:

⊕Table 3: a table created with Markdown Extra markup using only the default table styling

Using the following Markdown formatting:

|                 |mpg  | cyl  |  disp  |   hp   |  drat  | wt  |
|:----------------|----:|-----:|-------:|-------:|-------:|----:|
|Mazda RX4        |21   |6     |160     |110     |3.90    |2.62 |
|Mazda RX4 Wag    |21   |6     |160     |110     |3.90    |2.88 |
|Datsun 710       |22.8 |4     |108     |93      |3.85    |2.32 |
etc...

The following is a more simple table, showing the Markdown-style table markup. Remember to label the table with a marginnote Liquid tag, and you must separate the label from the table with a single blank line. This markup:

{% marginnote 'Table-ID4' 'Table 4: a simple table showing left, center, and right alignment of table headings and data'  %}

|**Left** |**Center**|**Right**|
|:--------|:--------:|--------:|
 Aardvarks|         1|$3.50
       Cat|   5      |$4.23
  Dogs    |3         |$5.29

Yields this table:

⊕Table 4: a simple table showing left, center, and right alignment of table headings and data

Code

Again, I am lifting this from clayh53’s section as I haven’t touched this much. But likely need to in the future. Code samples use a monospace font using the ‘code’ class. The Kramdown parser has the ‘GFM’ option enabled, which stands for ‘Github Flavored Markdown’, and this means that both inline code such as #include <stdio.h> and blocks of code can be delimited by surrounding them with 3 backticks:

(map tufte-style all-the-things)

is created by the following markup:

```(map tufte-style all-the-things)```

To get the code highlighted in the language of your choice like so:

module Jekyll
  class RenderFullWidthTag < Liquid::Tag
  require "shellwords"

    def initialize(tag_name, text, tokens)
      super
      @text = text.shellsplit
    end

    def render(context)
      "<div><img class='fullwidth' src='#{@text[0]}'/></div> " +
      "<p><span class='marginnote'>#{@text[1]}</span></p>"
    end
  end
end

Liquid::Template.register_tag('fullwidth', Jekyll::RenderFullWidthTag)

Enclose the code block in three backticks, followed by a space and then the language name, like this:

 ``` ruby
    module Jekyll
    blah, blah...
   ```