From 8592e25b4d36a83ca1c81d49e24c12e0315085cb Mon Sep 17 00:00:00 2001 From: Florrie Date: Tue, 5 Jun 2018 19:53:57 -0300 Subject: "Initial" commit --- site/posts/9-blog-images-on-gh-and-the-base-tag.md | 59 ++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 site/posts/9-blog-images-on-gh-and-the-base-tag.md (limited to 'site/posts/9-blog-images-on-gh-and-the-base-tag.md') diff --git a/site/posts/9-blog-images-on-gh-and-the-base-tag.md b/site/posts/9-blog-images-on-gh-and-the-base-tag.md new file mode 100644 index 0000000..9947cf3 --- /dev/null +++ b/site/posts/9-blog-images-on-gh-and-the-base-tag.md @@ -0,0 +1,59 @@ + title: "Being sad about how images don't work on the blog's GitHub page (AKA: An explanation of the 'base' HTML tag)" + permalink: '9-blog-images-on-gh-and-the-base-tag' + date: {m: 5, d: 17, y: 2017} + categories: + - 'dev' + - 'text' + +--- + + + +# Being sad about how images don't work on the blog's GitHub page +## (AKA: An explanation of the `` HTML tag) + +Case in point: [this.](https://github.com/towerofnix/blog/blob/38a7b7e0a52e92474ce215b5eae87cf30cf9becd/posts/8-a-snake-maybe.md) + +The issue is that I cheat[1] and use the [``][base-tag] 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://towerofnix.github.io/blog/`. We'd be embedding `https://towerofnix.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`](https://github.com/towerofnix/towerofnix.github.io) or [a repository with that name](https://github.com/towerofnix/static/), 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](https://github.com/towerofnix/blog/issues/1), 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-tag]: ` (..) ![Cool image!](static/media/cool-image.png)`. + +`` seems like magic at first, but it isn't really [black magic](http://www.catb.org/jargon/html/B/black-magic.html), because it's in the spec.[3] Basically[4], `` 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 `` tag that href's to `https://liam4.github.io` in the document. + +Bonus points for using ``: + +* It's really easy to embed `` on every page, just by having it be in the ``-part of my generic blog page template. + +* `` 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 `posts/post-file.html`!) + +The only problem with `` is that when you're viewing an HTML preview of your markdown file, you don't get to see the images, since the `` 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 `` 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 ``. See option 3. + +[2] See option 1. + +[3] "It's in the spec" doesn't really make something *not* [magic](http://www.catb.org/jargon/html/M/magic.html), 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 ``). (Cheesy "all right I'll leave now" here.) + +[5] [Markdown is *supposed* to let you embed any HTML tags you want into your document](https://daringfireball.net/projects/markdown/syntax#html), but GitHub doesn't follow that rule and gets rid of `` tags (and *every* tag except for what's on [their whitelist](https://github.com/jch/html-pipeline/blob/1b5058918eeb0507ac225934cd3e9238f0b94139/lib/html/pipeline/sanitization_filter.rb#L42-L49)) when it compiles markdown previews. So, [sure enough](https://gist.github.com/towerofnix/ac3a23d5fefbde422f44685674f5feac), setting the `` within the markdown document doesn't work for GitHub markdown previews, which is the use case in which our issue practically lies. + + [base-tag]: https://developer.mozilla.org/en/docs/Web/HTML/Element/base -- cgit 1.3.0-6-gf8a5