blog post: june 2021 site updates (#44)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

.markdownlint.json

@@ -9,5 +9,6 @@
     "MD031": { "list_items": false },
     "MD032": false,
     "MD033": false,
-    "MD040": false
+    "MD040": false,
+    "MD045": false
 }

Makefile

@@ -18,7 +18,7 @@ checks: spellcheck mdlint
 
 spellcheck:
 	go run github.com/client9/misspell/cmd/misspell -locale UK -source text -i "center,color" ${SHELLCHECK_FLAGS} \
-		README.md index.html about.md blog open-source _posts
+		README.md index.html about.md blog open-source content
 
 mdlint:
 	markdownlint -c .markdownlint.json --ignore _site .

README.md

@@ -1,7 +1,7 @@
 # bobheadxi.dev ![Checks status](https://github.com/bobheadxi/bobheadxi.github.io/workflows/Checks/badge.svg) [![website status](https://img.shields.io/website/https/bobheadxi.dev.svg?down_color=lightgrey&down_message=offline&label=website&up_message=online)](https://bobheadxi.dev) <img align="left" width=128 src="/assets/images/profile.jpg"/>
 
 This is the [Jekyll](https://jekyllrb.com/) source for my website and blog, [**`bobheadxi.dev`**](https://bobheadxi.dev).
-It is a *heavily* modified version of the [indigo theme](https://github.com/sergiokopplin/indigo),
+It is a [*heavily*](https://bobheadxi.dev/march-2020-site-updates/) [modified](https://bobheadxi.dev/introducing-dark-mode) version of the [indigo theme](https://github.com/sergiokopplin/indigo),
 and is hosted using [GitHub Pages](https://pages.github.com/). All opinions in blog posts, writeups, etc. are my own.
 
 <br />

_layouts/default.html

@@ -27,21 +27,18 @@
         var isMobile = window.matchMedia("only screen and (max-width: 760px)").matches;
 
         /* dark mode */
+        var prefersDark = false;
         function setDarkMode(isDark) {
             const theme = `theme-${isDark ? 'dark' : 'light'}`;
             document.querySelector('html').dataset.theme = theme;
+            prefersDark = isDark;
             console.log(`Set ${theme}`);
         }
+        const prefersDarkMatch = window.matchMedia('(prefers-color-scheme: dark)');
+        setDarkMode(prefersDarkMatch.matches);
 
-        const matchMediaPrefDark = window.matchMedia('(prefers-color-scheme: dark)');
-        setDarkMode(matchMediaPrefDark.matches);
-        console.info(`Call 'setDarkMode(${!matchMediaPrefDark.matches})' to ${matchMediaPrefDark.matches ? 'disable' : 'enable'} dark mode`);
-
-        function onSystemThemeChange(e) {
-            setDarkMode(e.matches);
-            console.log(document.querySelector('html').dataset.theme);
-        };
-        matchMediaPrefDark.addEventListener('change', onSystemThemeChange);
+        prefersDarkMatch.addEventListener('change', (e) => setDarkMode(e.matches));
+        console.info(`Call 'setDarkMode(${!prefersDark})' to ${prefersDark ? 'disable' : 'enable'} dark mode`);
     </script>
     <style>
         {% capture scss_sheet %}{% include style.scss %}{% endcapture %}

_sass/base/syntax.sass

@@ -132,7 +132,7 @@
 		color: #555555
 
 	.nt
-		color: navy
+		color: var(--syntax-nt)
 
 	.nv
 		color: teal

_sass/base/variables.sass

@@ -10,15 +10,19 @@ $fontMonospace: "iA Writer Mono", "Consolas", Liberation Mono, Menlo, Courier, m
     --epsilon: #ededed
     --zeta: #666
 
+    --syntax-nt: navy
+
 [data-theme="theme-dark"]
     --background: #141414
     --alpha: #aaa
     --beta: #eeeeee
-    --gama: #474747
+    --gama: #5a5a5a
     --delta: #5A85F3
     --epsilon: #202020
     --zeta: #929292
 
+    --syntax-nt: lightblue
+
 $mobile: "only screen and (max-width: 450px)"
 $tablet: "only screen and (min-width: 450px) and (max-width: 750px)"
 

_sass/pages/categories.sass

@@ -55,12 +55,7 @@
                 .image
                     filter: saturate(20%)
                     transition: 0.3s
-
-                .emoji
-                    display: inline
-                    position: relative
-                    top: -4px
-                    margin-right: 10px
+                    margin-bottom: 0.5rem
 
         > .item:hover > .url
             .title, aside

content/_open-source/2018-1-29-inertia.md

@@ -1,5 +1,5 @@
 ---
-title: ":rocket: Self-Hosted Continuous Deployment Platform"
+title: ":airplane: Self-Hosted Continuous Deployment Platform"
 layout: post
 tag:
 - golang

content/_open-source/2020-10-01-rocket-2.md

@@ -1,5 +1,5 @@
 ---
-title: "✨ Team Management Slack Bot and Platform"
+title: ":rocket: Team Management Slack Bot and Platform"
 layout: post
 tag:
 - python

content/_posts/2021-06-20-introducing-dark-mode.md

@@ -0,0 +1,187 @@
+---
+title: "June 2021 Updates for bobheadxi.dev"
+layout: post
+image: false
+headerImage: false
+diagrams: false
+tag:
+- javscript
+- experiment
+- jekyll
+- my-website
+category: blog
+author: robert
+description: Dark mode! Updated typography! Refined design!
+---
+
+With dark mode on every website nowadays, my website seems to have fallen a bit behind the times. I decided it was about time to give my website a bit of a facelift - and over-hype it with a blog post!
+
+This round of improvements didn't strictly happen this month, but a lot of it was spurred on by my recent reading of the [iA Design Blog](https://ia.net/design/blog). I think their website is absolutely gorgeous, and it made the lacklustre of `bobheadxi.dev` all the more apparent.
+
+For the unfamiliar, my site started off over 2 years ago with the [`indigo` Jekyll theme](https://github.com/sergiokopplin/indigo). I have since made quite a number of changes to it, mostly in random spurts of effort, and started [writing about these periods of changes last year](/march-2020-site-updates).
+
+I quite like how things turned out for this set of changes - hope you do as well!
+
+## Refinements
+
+### Updated typography
+
+A big part of `bobheadxi.dev` is my blog posts, even though I'm unsure how many people read them (Google Analytics indicates a lot of traffic, particularly on my *really* old [Object Casting in Javascript](/object-casting-in-javascript/) post). Anyway, I've always been rather dissatisfied with the reading experience on my site, but could never quite put my finger on what exactly was wrong with it.
+
+All I knew was that I didn't like the previous fonts - *‌Helvetica Neue* - but until I started using [iA Writer](https://ia.net/writer) recently, I didn't have much of an inkling of what font I would like.
+
+iA Writer uses these gorgeous fonts - aptly named *Mono*, *Duo*, and *Quattro* - that I think looks *so nice* when typing and reading. They have a [neat blog post introducing these fonts](https://ia.net/writer/blog/a-typographic-christmas), and while I'm not really sure what this stuff means, I decided to  make the switch.
+
+This site now uses *Quattro* as its serif font, and *Mono* as its monospaced font. I think the results are quite nice.
+
+### Outdented heading anchors
+
+While editing in iA Writer, headings get nicely outdented '#'s like so:
+
+![](../../assets/images/dark-mode/header-outdent-ia.png)
+
+When I started thinking about it, I'm pretty sure this is a very common style in many websites already. Either way, I quite like how it looks, so I tried to replicate it on my site. I currently generate somewhat similar-looking (but not outdented) anchor links using [`allejo/jekyll-anchor-headings`](https://github.com/allejo/jekyll-anchor-headings), which allows a little bit of customization - I can give the anchor link elements a class, for example, and style it through that.
+
+{% raw %}
+
+```html
+<div class="post-content">
+    {% include anchor_headings.html html=content anchorBody='#' anchorClass='heading-anchor' beforeHeading=true %}
+</div>
+```
+
+{% endraw %}
+
+Turns out the outdenting can be achieved using the handy [`translateX` transformation](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/translateX), and a bit of [`@media`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media) helps me scale this effect for smaller screens (where outdenting could position the anchors very close to the edge of your screen).
+
+```sass
+h1, h2, h3, h4
+	// ... some CSS
+	> .heading-anchor
+		position: absolute
+		transform: translateX(-2rem)
+		@media #{$tablet}, #{$mobile}
+			position: inherit
+			transform: none
+```
+
+Sadly, I wasn't able to figure out a nontrivial way to have the number of '#'s correspond to the depth of the heading, but I figured this was close enough, and is definitely an improves the look of headings (in my opinion).
+
+![](../../assets/images/dark-mode/header-outdent-bob.png)
+
+### Bold introductions
+
+Some books and blogs get big first letters for the first paragraph of a chapter or article. The effect looks nice on books, but I was never really sold on its usage in blog posts - though the look of an emphasised introduction is certainly striking. As I browsed through [iA Design Blog](https://ia.net/design/blog), I noticed that their first paragraphs were *big*, and it made each essay feel much more compelling.
+
+![](../../assets/images/dark-mode/wide-intro-ia.png)
+
+However, as I went about considering different options for making *my* intros real big as well, I realised a lot of my introductory paragraphs were complete garbage. While sometimes that was the intent - leading with a tangent before diving into the article's main topic - they definitely did not age well.
+
+So perhaps a fortunate side effect is that this prompted me to go back through my posts and make the bare minimum effort to make them a bit more interesting. At least I look like I know what I'm talking about now!
+
+![](../../assets/images/dark-mode/wide-intro.png)
+
+### Exciting listings
+
+I just learned about Jekyll's `post.excerpt` feature that gives you the first paragraph of a blog post. Again inspired by the iA Design Blog, which uses excerpts instead of custom descriptions to great effect, I decided to use them here as well.
+
+![](../../assets/images/dark-mode/light-blog-listing.gif)
+
+I think this gives a far better preview into the content of each post, and kind of makes them look more important. Thankfully my updating of each post's first paragraphs to accommodate [bigger introductions](#bold-introductions) meant that the excerpts are at least somewhat meaningful.
+
+I also made minor improvements such as adding an on-hover effect to the clickable tags, which previously had no indication they were clickable.
+
+### The big picture
+
+I like to include all sorts of media in my blog posts - images, code snippets, diagrams, quotes, and more. Unfortunately, I also like somewhat narrow widths for my content, which makes for a poor viewing experience for various forms of media.
+
+On [articles in the Sourcegraph Blog](https://about.sourcegraph.com/blog/optimizing-a-code-intel-commit-graph/#Performance-improvements) (and I recall that you can do this on Medium as well), I noticed that images were "blown up" - wider than the content - and I thought the effect looked quite nice, giving an expansive canvas for media to be enjoyed while still maintaining a nice reading experience for all the other stuff.
+
+To do this myself, I turned images I wanted to be blown up into `<figure>` elements, and gave them expanded widths, along with `<figcaption>`. This also served nicely to standardise the raw HTML I'd been previously using to give images captions.
+
+<figure>
+	<img src="../../assets/images/dark-mode/wide-image.png" />
+	<figcaption>Big!!!!</figcaption>
+</figure>
+
+Code blocks ran into similar problems, where snippets I didn't careful adjust to adhere to an 80-character line limit would have to be scrolled to viewed, even on very wide screens. So I made them massive.
+
+![](../../assets/images/dark-mode/wide-code.png)
+
+I've also always liked the big quotes used in magazine and newspaper sites to give quotes an even more authoritative and dramatic feel - so quotes joined the big club.
+
+![](../../assets/images/dark-mode/wide-quote.png)
+
+[Mermaid diagrams](https://mermaid-js.github.io/mermaid) and some other things I might have forgotten also got this treatment. Hopefully these changes make the reading experience more exciting!
+
+## Dark mode
+
+And last but not least, the star of today's show... dark mode! Because no site is complete without one.
+
+<figure>
+	<img src="../../assets/images/dark-mode/light-to-dark.gif" />
+	<figcaption>The site now switches do dark mode if you have dark mode enabled on your device!</figcaption>
+</figure>
+
+Luckily for me, the theme my site was based on made decent use of SASS variables for colours (though the naming of the colours left quite a bit to be desired, as you'll see in a moment).
+
+I found to my dismay that because these variables are compiled away at build time, they cannot be used to respond to [`prefers-color-scheme: dark`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme), which seems to be the standard way to detect for what theme you should show to the user.
+
+Instead, I found some blog posts talking about [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties), which turns out to be the only way to have properly variable variables in stylesheets. To be honest this is the first time I've had to do something like this myself, and this was news to me!
+
+My implementation ended up pretty straight forward, using [universal selectors](https://www.w3.org/TR/CSS2/selector.html#universal-selector) and setting the theme in JavaScript, though I'm sure there are other ways to do this too (maybe even JavaScript-free?).
+
+```sass
+[data-theme="theme-light"]
+    --background: #ffffff
+    --alpha: #333
+    --beta: #222
+    --gama: #aaa
+    --delta: #5A85F3
+    --epsilon: #ededed
+    --zeta: #666
+
+[data-theme="theme-dark"]
+    --background: #141414
+    --alpha: #aaa
+    --beta: #eeeeee
+    --gama: #474747
+    --delta: #5A85F3
+    --epsilon: #202020
+    --zeta: #929292
+```
+
+```js
+var prefersDark = false;
+function setDarkMode(isDark) {
+    const theme = `theme-${isDark ? 'dark' : 'light'}`;
+    document.querySelector('html').dataset.theme = theme;
+    prefersDark = isDark;
+    console.log(`Set ${theme}`);
+}
+
+// set the initial theme
+const prefersDarkMatch = window.matchMedia('(prefers-color-scheme: dark)');
+setDarkMode(prefersDarkMatch.matches);
+
+// watch for changes to the user's dark mode configuration
+prefersDarkMatch.addEventListener('change', (e) => setDarkMode(e.matches));
+```
+
+Having the `setDarkMode` function available is useful for development, allowing me to switch between the modes via console, and I added the `prefersDark` variable... just because, I guess. Maybe handy if I want to add a button to toggle dark mode?
+
+In the end, despite picking the colours semi-randomly and not making an awful lot of adjustments, I'm pretty happy with how this (in my opinion) quick effort turn out! I'm particularly pleased with how the blog listings look:
+
+![](../../assets/images/dark-mode/dark-blog-listing.gif)
+
+## Up next
+
+There are still a lot of issues with dark mode - most noticeably the company logos I'm using that don't have transparent backgrounds, but also a few contrast issues in code highlighting.
+
+There also seems to be an issue with the tags page where posts from different collections do not get included that I definitely want to fix now that interaction with tags is more prominent.
+
+I recently wrote a newsletter featuring a ludicrous number of footnotes, and at some point I want to get [Tufte "sidenotes"](https://edwardtufte.github.io/tufte-css/#sidenotes) here so that I can abuse footnotes in my blog posts as well. Sadly, I haven't found a particularly elegant solution to this, so I'm putting it off for the time being.
+
+And, of course, I'm hoping to do more blog-writing as well.
+
+That's all for now - feel free to highlight anything on this post if you have comments for questions!

index.html

@@ -36,9 +36,9 @@ <h2 class="section-title" id="featured-posts">
   <div class="item" align="center" style="margin-bottom: 24px">
     <a class="url" href="{% if post.externalLink %}{{ post.externalLink }}{% else %}{{ site.url }}{{ post.url }}{% endif %}">
       {% if post.hero_image %}
-        <img class="image" src="{{ post.hero_image }}" width="50%" style="margin-bottom: 8px"/>
+        <img class="image" src="{{ post.hero_image }}" width="50%" />
       {% else %}
-        <img class="image" src="{{ post.image }}" style="margin-bottom: 8px; max-height:48px"/>
+        <img class="image" src="{{ post.image }}" style="max-height:48px"/>
       {% endif %}
       <h3 class="title">{{ post.title }}</h3>
       <p style="margin-bottom: 0px;margin-top:4px"> {{ post.description }} </p>
@@ -69,7 +69,7 @@ <h2 class="section-title" id="open-source-highlights">
   {% for post in site.open-source reversed %} {% if post.star %}
   <div class="item" align="center">
     <a class="url" href="{% if post.externalLink %}{{ post.externalLink }}{% else %}{{ site.url }}{{ post.url }}{% endif %}">
-      <img class="image" src="{{ post.image }}" width="50%" style="margin-bottom: 8px"/>
+      <img class="image" src="{{ post.image }}" width="50%" />
       <h3 class="title">{{ post.title }}</h3>
       <p> {{ post.description }} </p>
       {% include post-tags.html %}

open-source/index.html

@@ -100,10 +100,8 @@ <h1 style="font-weight:500;margin-top:-0.5rem;margin-bottom:-0.2rem;text-align:c
 <section class="post-list">
     {% for post in site.open-source reversed %}
         <div class="item">
-            {% if post.star %}<br />{% endif %}
             <a class="url" href="{% if post.externalLink %}{{ post.externalLink }}{% else %}{{ site.url }}{{ post.url }}{% endif %}">
                 {% if post.star %}
-                <br />
                 <img class="image" src="{{ post.image }}" width="100%" style="margin-top:16px"/>
                 {% endif %}
                 <h3 class="title">{{ post.title }}</h3>