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 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:
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
liam4.github.io.gitor a repository with that name, so GitHub pages considers it to not exist. What we want is
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. (citation: option 1).
The right way (which takes too long to explain in a single list item). Use
<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. Basically,
<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
It's really easy to embed
<base>on every page, just by having it be in the
<head>-part of my generic blog page template.
<base>also works on things like links, which makes it really easy to link to any page on the blog, from any page on the blog. (Example: the navigation bar has the same HTML on every page of the blog, but the links still work irregardless of what page the navigation bar actually shows up on. Another: linking to a blog post from anywhere on the site – even other post pages – is easy; just link to
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. (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
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.
 This isn't actually true; I'm pretty sure I'm following the intended use of
<base>. See option 3.
 See option 1.
 "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).
 I get to say that because nobody else says it (since nobody knows about
<base>). (Cheesy "all right I'll leave now" here.)
 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.