Being sad about how images don't work on the blog's GitHub page

(AKA: An explanation of the <base> HTML tag)

Case in point: this.

The issue is that I cheat[1] and use the <base> tag to have easier embed URLs for things like images.

For example, suppose I write my-fancy-post.md, and I want to include the image cool-image.png. My options:

  1. The easy way. Use absolute paths: ![Cool image!](/static/media/cool-image.png). But what if the blog's root path isn't /? In fact, it isn't – my blog's currently presented at https://liam4.github.io/blog/. We'd be embedding https://liam4.github.io/static/media/cool-image.png. And that doesn't exist, of course; I don't have a static folder under liam4.github.io.git or a repository with that name, so GitHub pages considers it to not exist. What we want is https://liam4.github.io/blog/static/cool-image.png.

  2. The (just slightly) less easy way. Use relative paths: ![Cool image!](../static/media/cool-image.png). That should work, right? The post HTML documents are stored at (site root)/posts/blah.html, so we'd be referencing (site root)/posts/../static/media/cool-image.png, or, simplified, (site root)/static/media/cool-image.png. Great! It works. Except – hold on. We display the most recent post on the homepage, at (site root)/index.html. That means, from index.html, we'll be loading (site root)/../static/media/cool-image.png. And that's not right.[2] (citation: option 1).

  3. The right way (which takes too long to explain in a single list item). Use <base>: <base href='https://liam4.github.io/blog/'> (..) ![Cool image!](static/media/cool-image.png).

<base> seems like magic at first, but it isn't really black magic, because it's in the spec.[3] Basically[4], <base> changes where relative paths are relative to. So by changing it to https://liam4.github.io/blog/, all relative paths are loaded according to that. foo/bar.html will always refer to https://liam4.github.io/blog/foo/bar.html, as long as there's a <base> tag that href's to https://liam4.github.io in the document.

Bonus points for using <base>:

The only problem with <base> is that when you're viewing an HTML preview of your markdown file, you don't get to see the images, since the <base> is ignored while the HTML preview is compiled.[5] (It should be pretty clear why – ![](static/media/foo.png no longer refers to https://liam4.github.io/static/media/foo.png, but rather, (current directory)/static/media/foo.png, which won't appear correctly unless (current directory) happens to be the site root (i.e. the directory containing static).)

I don't really see a way to solve that, though. The benefits greatly outweigh that cost, so <base> is what I'm using.


PS, did anybody here by chance know me by my art and not my code?

..Nah, I'm the only person who follows my blog anyways. And the only other people that do probably know me from (generally) code-writing-based communities, for the stuff I've programmed, not my art.


[1] This isn't actually true; I'm pretty sure I'm following the intended use of <base>. See option 3.

[2] See option 1.

[3] "It's in the spec" doesn't really make something not magic, if nobody can understand what the spec is saying, which is sometimes the case (citation needed). What makes it not magic is that it actually does make sense when I explain it to you (citation needed).

[4] I get to say that because nobody else says it (since nobody knows about <base>). (Cheesy "all right I'll leave now" here.)

[5] Markdown is supposed to let you embed any HTML tags you want into your document, but GitHub doesn't follow that rule and gets rid of <base> tags (and every tag except for what's on their whitelist) when it compiles markdown previews. So, sure enough, setting the <base> within the markdown document doesn't work for GitHub markdown previews, which is the use case in which our issue practically lies.