1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
|
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="icon" href="data:,">
<title>Yet Another Static Site Generator Switch</title>
<link href="/atom.xml" type="application/atom+xml" rel="alternate" title="Atom feed for blog posts" />
<link href="/rss.xml" type="application/rss+xml" rel="alternate" title="RSS feed for blog posts" />
<style>*{box-sizing:border-box;}body{font-family:sans-serif;line-height:1.33;margin:0 auto;max-width:650px;padding:1rem;}img{max-width:100%;}pre{border:1px solid;overflow:auto;padding:5px;}table{text-align:left;width:100%;}.footnotes{font-size:90%;}</style>
</head>
<nav>
<a href="#menu">Menu ↓</a>
</nav>
<main>
<h1 id="yet-another-static-site-generator-switch">Yet Another Static Site Generator Switch</h1>
<p>2022-07-06</p>
<p>If you’re an RSS subscriber, I’ve probably blown up your feed reader (again). This seems to be an on-going theme with this blog. I can’t help it.</p>
<p>This website now uses my <em>new</em> Pandoc-based static blog generator: <a href="https://pblog.bt.ht">pblog</a>. I won’t go into great detail about it’s features (or lack thereof) - if you’re interested in that, check out the <a href="https://pblog.bt.ht/blog/pblog-intro.html">“Introducing pblog” article</a>.</p>
<p>The bigger question is, “Why the change?”</p>
<h2 id="wheres-the-love-for-shinobi">Where’s the Love for “Shinobi”?</h2>
<p>Switching over to <code>pblog</code> wasn’t caused by a dislike of using <a href="https://shinobi.bt.ht">Shinobi</a>. In fact, I still really enjoy the work flow that that plain-text focused SSG provides. The main issues that popped up for my own blog was <em>accessibility</em> and <em>poor user experience</em>.</p>
<p>I had multiple readers reach out and mention poor rendering of content in their RSS reader of choice. That’s kind of a <strong>big deal</strong>. I test that project as best I can with my limited access to all available RSS readers - but I can only test so much. It became one of those “Well, it works on my machine!” meme. So instead of spending an untold amount of time debugging every RSS reader known to man, I figured my best bet was to render things as <code>HTML</code>.</p>
<p>The next big issue was <em>accessibility</em>. Screen readers can read <code>txt</code> formatted files perfectly fine but since elements aren’t categorized everything ends up with the same level hierarchy. This can cause confusion between headers, list items, URLs, footers etc. For my personal use-case (sharing tutorials and covering design topics) it didn’t make sense to sacrifice user accessibility for minimalism.</p>
<h2 id="the-search-for-simplicity">The Search for Simplicity</h2>
<p>My initial thought process was to include some form of “plus” add-on to the existing Shinobi build script. The idea was to render <code>HTML</code> versions of each post and dump those into the generated RSS file. Although maybe good in theory, it ended up impractical because:</p>
<ol>
<li>No utility or existing tool could render the style of text-based formatting I implemented as semantic HTML (at least not without heavy customization and tinkering)</li>
<li>I was actually adding extra bloat to the Shinobi project (true minimalism is the point, right?)</li>
</ol>
<p>So, that option was ruled out pretty quickly.</p>
<p>The next option didn’t take me long to land on: <em>Pandoc</em>. I’ve used Pandoc for years and have nothing but great experiences tweaking it for my own needs. I knew that I could piggyback off the original <code>shell</code> commands in the Shinobi project and alter them as needed to incorporate Pandoc.</p>
<p>I honestly didn’t run into many issues while rolling this out. Fairly seamless!</p>
<h2 id="new-workflow">New Workflow</h2>
<p>With this new blog switch I also decided to try out a new <em>deploy</em> workflow. I’ve used <code>rsync</code> for the longest time but wanted to have something more GUI-based on macOS. I know, <em>blasphemy</em>!</p>
<p>Since I already have a Transmit license, that seemed like the best fit since it is designed specifically for macOS. Now my workflow process is as follows:</p>
<ol>
<li>Write new posts in my root <code>posts</code> folder</li>
<li>Rebuild the <code>pblog</code> with <code>make</code></li>
<li>Use the built-in sync function of Transmit to mirror my local <code>_output</code> with my web server</li>
</ol>
<p><img src="/public/images/transmit-ftp.webp" alt="The Transmit UI in all of its wonderful glory (before I updated)" /></p>
<h3 id="wrapping-up">Wrapping Up</h3>
<p>Will there be bugs with this switch-over? Most likely. Will some URLs be left behind or broken? Possibly. These small issues will be ironed out over time. For now, I’m quite happy with keeping things minimal on the workflow side of things, while preserving accessibility and user experience with the output.</p>
<p>Thanks for reading!</p>
<footer role="contentinfo">
<h2>Menu Navigation</h2>
<ul id="menu">
<li><a href="/">Home</a></li>
<li><a href="/projects">Projects</a></li>
<li><a href="/uses">Uses</a></li>
<li><a href="/wiki">Wiki</a></li>
<li><a href="/resume">Resume</a></li>
<li><a href="/colophon">Colophon</a></li>
<li><a href="/now">Now</a></li>
<li><a href="/donate">Donate</a></li>
<li><a href="/atom.xml">RSS</a></li>
<li><a href="#top">↑ Top of the page</a></li>
</ul>
<small>
Built with <a href="https://git.sr.ht/~bt/barf">barf</a>. <br>
Maintained with ♥ for the web. <br>
Proud supporter of <a href="https://usefathom.com/ref/DKHJVX">Fathom</a> & <a href="https://nextdns.io/?from=74d3p3h8">NextDNS</a>. <br>
The content for this site is <a href="https://creativecommons.org/licenses/by-sa/2.0/">CC-BY-SA</a>.<br> The <a href="https://git.sr.ht/~bt/bt.ht">code for this site</a> is <a href="https://git.sr.ht/~bt/bt.ht/tree/master/item/LICENSE">MIT</a>.
</small>
</footer>
|
