content/posts/devlog/blog/1.md

   1 ---
   2 title: "DEVLOG: Custom Theme for Hugo"
   3 date: 2020-06-10T12:00:00-04:00
   4 draft: false
   5 tags: ["devlog", "blog", "devlog-blog"]
   6 ---
   7
   8 I've started working on a custom theme for Hugo[^1] that I use on my blog. The goal here is to be as simple as possible and takes its inspiration from the IETF .txt file[^2] where possible.
   9
  10 The theme itself contains a light/dark mode as well as a small variation of the main theme for mobile. I actually had some help from a good friend[^3] who helped me adjust the colors for both dark and light modes to make them a bit more legible.
  11
  12 The two complicated components and 1 simple component are outlined below.
  13
  14 ## Features
  15
  16 ### Numbered Headers
  17
  18 I wanted to ensure that each heading would have a number associated with it that matched the number that it was automatically assigned by Hugo during the Table of Contents generation. I didn't want to have to update numbers as I added/remove header tags and I didn't want to utilize any JavaScript on the site, so I was left with CSS only.
  19
  20 I ended up utilizing counters[^4] to achieve this.
  21
  22
  23
  24 ```css
  25 body {counter-reset: h2;}
  26 h2 {counter-reset: h3;}
  27 h3 {counter-reset: h4;}
  28 h4 {counter-reset: h5;}
  29 h5 {counter-reset: h6;}
  30
  31 h2:before {counter-increment: h2; content: counter(h2) ". ";}
  32 h3:before {counter-increment: h3; content: counter(h2) "."counter(h3) ". ";}
  33 h4:before {counter-increment: h4; content: counter(h2) "."counter(h3) "."counter(h4) ". ";}
  34 h5:before {counter-increment: h5; content: counter(h2) "."counter(h3) "."counter(h4) "."counter(h5) ". ";}
  35 h6:before {counter-increment: h6; content: counter(h2) "."counter(h3) "."counter(h4) "."counter(h5) "."counter(h6) ". "; }
  36 h2.nocount:before,h3.nocount:before,h4.nocount:before,h5.nocount:before,h6.nocount:before {content: ""; counter-increment: none;}
  37 ```
  38
  39
  40
  41 I only have a single `<h1>` tag in my document which is for the title of the post, which I don't want numbered. The code above it ensures that every time we run across an `<h2>` tag it will reset the counter for `<h3>` tags to 0, increment the counter for `<h2>` tags, and then display the current value of the counter.
  42
  43 It repeats this for all header tags appending the counter for each subsequent tag level.
  44
  45 I've also included provisions for ensuring that you can skip incrementing the counters if you add a `.nocount` class to any header.
  46
  47
  48
  49 ### Flexible visual line-up
  50
  51 This was probably the hardest part.
  52
  53 ![flexible-line](/img/devlog/blog/flexible-line.png)
  54
  55 That dashed line that lets you link a post with the corresponding date. Both elements are positioned at the exterior of their boxes, and the titles have a varying width.
  56
  57 In order to accomplish this I ended up needing to introduce a 3rd element, the line itself. However, I can't actually use an `<hr />` tag because I want to work towards supporting screen readers.. and those tags get interpreted as dividers between content.
  58
  59 The article list is an unordered list, so the HTML code looks like this:
  60
  61 ```html
  62 <li>
  63         <a href="/link/to/post">Post Title</a>
  64         <span class="divider"></span>
  65         <span class="pubdate">YYYY-MM-DD</span>
  66 </li>
  67 ```
  68
  69 I set the `<li>` tag to utilize flex `display: flex` and tell it to align the items to the center
  70
  71 I then set the `.divider` to `flex-grow: 1` [^4] and don't set the property on the `<a>` or `.pubdate` elements. This causes the divider to grow to take up the entirety of space within the list element, subtracting the side of the title/date tags.
  72
  73 ```css
  74 .article-list li {
  75         list-style: none;
  76         display: flex;
  77         align-items: center;
  78 }
  79
  80 .article-list .divider {
  81         flex-grow: 1;
  82         border-bottom: 1px dashed black;
  83         margin: 0.3rem;
  84 }
  85 ```
  86
  87 ### Dark/Light mode
  88 One of the things that I ended up implementing, that I'm not 100% sold on is the auto dark/light mode. Utilizing CSS we can adjust things to account for if the user is utilizing a light or dark mode on their browser:
  89 ```css
  90 @media (prefers-color-scheme: dark) {
  91         /* your stuff goes here */
  92 }
  93 ```
  94 It's a very simple technique and given the minimalist nature of this site it works rather perfectly.
  95
  96 Where I'm not 100% happy is on color choices. Where possible I attmpted to tweak things so that they would look the same in light or dark mode. I tweaked the original colors of links (new/visited) and also settled on a particular code-highlighting style.
  97
  98 Where I'm not 100% happy, is with the default font color. In light mode it's browser defaults, but in dark mode it's a blue/grey and I think it might be a tad too dark. It's something that I'll continue tweaking in small batches until I find something that works well.
  99
 100 I also faded out images just a bit so that they're not so jaring. The idea is if you hover/touch the images they'll fade in to full color, but if you're just scrolling through you won't run into any weirdness.
 101
 102 ### Support for Utteranc.es
 103 This[^5] is something that I recently stumbled across - the ability to utilize GitHub issues to track comments on a site. I really love the idea - especially since I'm hosting my blog on GitHub Pages. By adding some params to your `config.toml` file you'll be able to turn on support for utterances.
 104
 105 ```toml
 106 [params.utterances]
 107 repo = "AngeloR/angelor.github.io"
 108 issue_term="pathname"
 109 label="comment"
 110 theme="preferred-color-scheme"
 111 ```
 112
 113 The settings match exactly the configuration options provided by utteranc.es, so you should be able to see the mapping quite easiy. The only thing I changed was making it `issue_term` instead of `issue-term`.
 114
 115 If you don't add this configuration, it'll just hide the comment block and you won't even load the utteranc.es client js.
 116
 117 ## Download/Install
 118 If you're interested in this theme, you can grab it here https://github.com/AngeloR/plain-hugo-theme
 119
 120 Up to date installation instructions can be found on the readme, but I've included a snapshot of what they were at this point:
 121
 122 ```bash
 123 git clone https://github.com/AngeloR/plain-hugo-theme /path/to/hugo/themes/plain/
 124
 125 Edit your config.toml to add the following line:
 126 theme = "plain"
 127 ```
 128
 129 If you do end up using it and come across any bugs, please let me know over on GitHub!
 130
 131 ## Footnotes
 132
 133 [^1]: https://github.com/AngeloR/plain-hugo-theme
 134 [^2]: https://tools.ietf.org/rfc/rfc7993.txt
 135 [^3]: http://westleysz.com/
 136 [^4]: https://developer.mozilla.org/en-US/docs/Web/CSS/flex-grow
 137 [^5]: https://utteranc.es/