~hristoast/hristoast

hristoast/site/blog/soupault-one-year-in-and-beyond.html -rw-r--r-- 14.3 KiB
40e15203Hristos N. Triantafillou De-dupe 10 days ago
                                                                                
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
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
<h1 id="title">Soupault: One Year In And Beyond</h1>

<div id="dates">
  <span>Posted: <time id="post-date">2021-06-04</time></span>
</div>

<p id="post-excerpt">
  Some time ago, I decided to convert my Django-based blog to a static website. At the time, I wrote a little bit about my motivations but that piece was light on the technical details of "why Soupault". In this piece, I'll go over those details in the hope that more folks will give Soupault a look!
</p>

<div id="toc"></div>

<h3>Full Disclosure</h3>

<p>
  I want to first mention that I am a Soupault code contributor, plugin author, and I consider the creator to be a personal friend of mine. <span class="footnote"> Hey, <a href="https://baturin.org/">Daniil</a>!</span> I've created more than a handful of websites with Soupault, and I plan to use it for future projects when possible. <span class="footnote"> Some other sites I've built with Soupault: <a href="https://mousikofidi.info/">mousikofidi.info</a>, <a href="https://wem.hristos.co/">wem.hristos.co</a>, <a href="https://gr4h.co/">gr4h.co</a> (WIP), and <a href="https://dimension-warrior.blackholegate.com/">dimension-warrior.blackholegate.com</a> (also WIP)</span> These things make me somewhat biased, so keep that in mind as you read!
</p>

<h3>What Is Soupault?</h3>

<p>
  Soupault is a static site generator (hereby referred to as an SSG), which means it is a piece of software that produces static HTML files intended to be served as a website.
</p>

<p>
  As SSGs go, Soupault is a bit more powerful than that, though. Unlike most SSGs which try to hide layers such as HTML or CSS from you (more on that in a bit), Soupault embraces and gives you full access to them; use selectors in the same way as you would in your HTML, CSS, or Javascript. It feels idiomatic, as if it's just part of the HTML-processing experience. Best of all, nothing really feels magical this way, and I'm not worried about problems with abstractions.
</p>

<h3>Why Soupault? Part One: Themes</h3>

<p>
  When you look at SSGs, a common trait among them are "themes" or some way of attempting to abstract away HTML, CSS, and possibly even Javascript. On the surface it might seem nice, especially if you don't fancy coding in those languages. It could very well work out for those folks.
</p>

<p>
  But you may run into problems, usually, when you start to try and customize things - or if your SSG updates and breaks compatibility with your theme. <span class="footnote"> <a href="https://themes.gohugo.io/hugo-icarus/">Hugo-Icarus: "The original Hugo Icarus theme has been unmaintained for years, and as Hugo upgraded, some features broke (such as front-page post listing, recent posts, and post counts). This version fixes such issues."</a>; this indicates a history of breakage with Hugo.</span> <span class="footnote"> <a href="https://github.com/gohugoio/hugoThemes/issues/867">Another broken Hugo theme</a></span> <span class="footnote"> <a href="https://github.com/gohugoio/hugoThemes/issues/810">.. Another broken Hugo theme</a></span> <span class="footnote"> <a href="https://github.com/gohugoio/hugoThemes/issues/669">.... And another broken Hugo theme</a></span> <span class="footnote"> <a href="https://masalmon.eu/2020/02/29/hugo-maintenance/">A cautionary tale about using Hugo, mainly looking at themes breaking but other things are covered as well</a></span> This, in my opinion, is a shining point of Soupault: that it has no notion of "themes". That's right, a lack of a feature is itself a feature! You want to hear more? Okay!
</p>

<p>
  Instead of opaque themes, Soupault enables you to easily leverage HTML templates so that you can produce DRY <span class="footnote"> <a href="https://en.wikipedia.org/wiki/Don%27t_repeat_yourself">https://en.wikipedia.org/wiki/Don%27t_repeat_yourself</a></span> layouts and styles. You can even selectively do things with widgets (more on that in a bit)!
</p>

<p>
  If you're not looking to avoid HTML/CSS/JS at all costs this ends up paying off in the long run and offers much greater flexibility than a theme could by design.
</p>

<h3>Why Soupault? Part Two: Plugins And Scripts</h3>

<p>
  Soupault also sports a Lua scripting API, as well as a mechanism for piping in and processing output from scripts. This is probably the most complex part of Soupault, but also the most powerful. It's these features that allow me to have a fully static website that has a dynamic look and feel.
</p>

<h4>Lua Plugins</h4>

<p>
  Soupault has a public Lua plugin directory with several very useful plugins, including many that are used on this very website! <span class="footnote"> <a href="https://soupault.app/plugins/">https://soupault.app/plugins/</a></span> <span class="footnote"> <a href="https://git.sr.ht/~hristoast/hristoast/tree/9936b5aaf28818b2ace6642ef81100d5873210db/item/plugins">My plugins, as of this writing</a></span>
</p>

<p>
  If you want to extend a plugin or write your own, consult <a href="https://soupault.app/reference-manual/#plugin-api">the Plugin API docs</a> for a rundown of what all you can do with it. I found the public plugin directory to be a great resource for working plugin code to reference while building my own plugins.
</p>

<p>
  Here's some examples of nifty things I'm doing with plugins:
</p>

<ul>
  <li>My atom feed is generated with a Lua plugin, as is my sitemap. <span class="footnote"> <a href="https://git.sr.ht/~hristoast/hristoast/tree/9936b5aaf28818b2ace6642ef81100d5873210db/item/soupault.conf#L90-104">soupault.conf#L90-104</a></span> <span class="footnote"> <a href="https://git.sr.ht/~hristoast/hristoast/tree/9936b5aaf28818b2ace6642ef81100d5873210db/item/soupault.conf#L106-112">soupault.conf#L106-112</a></span></li>
  <li>You might notice the word "Blog" at the top of this page is boldened and underlined; that's the Highlight Active Link plugin in action. <span class="footnote"> <a href="https://git.sr.ht/~hristoast/hristoast/tree/9936b5aaf28818b2ace6642ef81100d5873210db/item/soupault.conf#L122-128">soupault.conf#L122-128</a></span></li>
  <li>The footnotes you may have noticed peppered throughout this and other posts are also from a Lua plugin. <span class="footnote"> <a href="https://git.sr.ht/~hristoast/hristoast/tree/9936b5aaf28818b2ace6642ef81100d5873210db/item/soupault.conf#L139-151">soupault.conf#L139-151</a></span></li>
  <li>The table of contents at the top of this and other posts - you guessed it: Lua plugin. <span class="footnote"> <a href="https://git.sr.ht/~hristoast/hristoast/tree/9936b5aaf28818b2ace6642ef81100d5873210db/item/soupault.conf#L170-184">soupault.conf#L170-184</a></span></li>
  <li>I selectively insert elements based on page content for several purposes, including: Asciinema assets, extra CSS for syntax highlighting code snippets, only loading Javascript on pages that need it, and more. <span class="footnote"> <a href="https://git.sr.ht/~hristoast/hristoast/tree/9936b5aaf28818b2ace6642ef81100d5873210db/item/soupault.conf#L194-225">soupault.conf#L194-225</a></span></li>
  <li>You can check the source of this page to see how it all works - there's a link at the bottom of the page. Yes, that too is a Lua plugin! <span class="footnote"> <a href="https://git.sr.ht/~hristoast/hristoast/tree/9936b5aaf28818b2ace6642ef81100d5873210db/item/soupault.conf#L130-137">soupault.conf#L130-137</a></span></li>
</ul>

<h4>Scripts</h4>

<p>
  When you need something a little more powerful, you can use external scripts written in any language to produce HTML that is consumed and processed by Soupault.
</p>

<p>
  On this website (at least, as of the time of this writing) <a href="/">the main index page</a> has a partial blog post list. This is achieved through an external python script and Soupault's own indexing capabilities. <span class="footnote"> <a href="https://git.sr.ht/~hristoast/hristoast/tree/9936b5aaf28818b2ace6642ef81100d5873210db/item/scripts/index.py">This</a> is the python script, which uses <a href="https://pypi.org/project/pystache/">pystache</a> to do templating.</span> <span class="footnote"> <a href="https://git.sr.ht/~hristoast/hristoast/tree/9936b5aaf28818b2ace6642ef81100d5873210db/item/soupault.conf#L56-63">This</a> is the relevant part of my <code>soupault.conf</code>.</span> <span class="footnote"> Soupault's documentation on "<a href="https://soupault.app/reference-manual/#metadata-extraction-and-rendering">Metadata extraction and rendering</a>" covers the topic of indexes quite well.</span>
</p>

<h3>Why Soupault? Part Three: I Can't Believe It's Not Dynamic!</h3>

<p>
  It's very possible to achieve a "dynamic" look and feel that's common with traditional non-static websites.
</p>

<h4>Blog Style</h4>

<p>
  The indexing capabilities mentioned above are powerful enough on their own to produce a full "blog post" index, without any scripts or plugins. As of this writing, such a page can be found on <a href="/blog/">this website's "Blog" page</a>.
</p>

<p>
  This website's <code>soupault.conf</code> has all the details, but in a nutshell: I first define <a href="https://git.sr.ht/~hristoast/hristoast/tree/9936b5aaf28818b2ace6642ef81100d5873210db/item/soupault.conf#L47-54">index fields</a> that will provide context to my index, then I define <a href="https://git.sr.ht/~hristoast/hristoast/tree/9936b5aaf28818b2ace6642ef81100d5873210db/item/soupault.conf#L65-88">the index itself</a> as well as a simple HTML snippet to use. I'm using a regular expression to select which "blog posts" to include in the index.
</p>

<p>
  The "Tips and tricks" section of the Soupault website has several nice resources on how to do various things with Soupault, including some helpful usage pattern examples, and <a href="https://soupault.app/tips-and-tricks/comparison/">a comparison table</a> that lists differences between Soupault and other popular SSGs. <span class="footnote"> <a href="https://soupault.app/tips-and-tricks/">https://soupault.app/tips-and-tricks/</a></span>
</p>

<h4>Searching</h4>

<p>
  You might think that searching is out of the question with a static website, but that isn't the case! Take for example the <a href="https://gitlab.com/portmod/portmod">Portmod</a> project's <a href="https://portmod.gitlab.io/openmw-mods/">OpenMW Mod Repository</a>, which is built using Soupault and leverages <a href="https://stork-search.net/">Stork</a> for searching.
</p>

<p>
  Of course this isn't specific to Soupault, but if you're coming from a system with a database that makes stuff like search easy, you may be wondering "can I still have that?". The answer is yes!
</p>

<h3>Why Soupault? Part Four: Any Format You Like</h3>

<p>
  This is an aspect of Soupault that I myself don't utilize much since I prefer to work directly with HTML and friends, however: any format that can be converted to HTML is usable with Soupault.
</p>

<p>
  Page preprocessors can be configured using any arbitrary command, so it is theoretically possible to use a huge variety of formats if desired. <span class="footnote"> <a href="https://soupault.app/reference-manual/#page-preprocessors">The official reference on page preprocessors</a>.</span>
</p>

<p>
  Additionally the converted output can and will be usable to Soupault, so you can apply widgets and scripts to them as desired.
</p>

<p>
  If you prefer Markdown, Wiki Markup, Rich Text Format, Org-mode, or any other one of many many different formats, Soupault has you covered. Anything you can convert to HTML outside of Soupault can be done within it.
</p>

<p>
  This is probably nice for folks who would be coming from other SSGs that use Markdown or some other format; it's possible that a lot of that would carry over into a Soupault project.
</p>

<h3>Why Not Soupault?</h3>

<p>
  Soupault is so excellent, so powerful, that I strongly recommend it for any project that can exist as a static website. That being said, I can think of a few reasons that Soupault might not be right for you:
</p>

<ul>
  <li>You really don't want to write <span style="font-style: italic;">any</span> HTML, CSS, or Javascript. Other SSGs that use "themes" can in theory allow you to get away with this. <span class="footnote"> Though even in this case you are likely still writing YAML or some other kind of markup.</span></li>
  <li>You want something with a graphical user interface. Soupault is a command-line program, so if you're someone who is used to Frontpage, Dreamweaver, or similar softwares, this may be a barrier to entry for you. <span class="footnote"> Snicker if you want, but as I understand it there are indeed folks who still use these and other older "publishing" softwares. These users are absolutely folks who could adopt Soupault, in theory.</span></li>
  <li>You're already using some other SSG/CMS/etc, and migrating is hard.
    <ul>
      <li>When I migrated this blog from being Django-based with an SQL database to Soupault, I had to handle converting blog posts from SQL to raw HTML and saving them in a way that Soupault could use them. It wasn't extremely difficult, but it wasn't trivial either, and did require some careful planning.</li>
      <li>Migrating from another SSG shouldn't be hard in theory. You could build the site into HTML, turn "generator mode" off.. Your site is now a Soupault project. <span class="footnote"> <a href="https://soupault.app/reference-manual/#overview">Soupault reference and overview</a>, mentioning what "generator mode" actually is. The <a href="https://soupault.app/tips-and-tricks/getting-started-html-processor/">Getting started: HTML processor</a> page is another good resource for this.</span></li>
    </ul>
  </li>
</ul>

<h3>Conclusion</h3>

<p>
  The "Soupault Way" is somewhat different from most other SSGs' usage patterns, but it ends up (for me, at least) being not only less work overall, but it also has (again, for me at least) less friction for actually interacting with my website. Really, the only barrier right now is simply me sitting down and writing something that's decent.
</p>

<p>
  The widget/plugin/scripts systems afford me the flexibility to do a lot of things, and in the future I'd like to do even more. For example, it'd be nice to bring categories back to the blog.
</p>

<p>
  In the end, there are a lot of SSGs out there, and more being made all the time. Soupault is still somewhat rare with its focus on HTML processing and manipulation, but I think it's a great approach that enables powerful new patterns that feel idiomatic in my HTML editing stack.
</p>

<h3>Footnotes And References</h3>

<div id="footnotes"></div>