<title>SSG framework for displaying music scores</title>
<link href="https://blog.skarhed.com/"/>
<updated>2023-04-10T00:00:00Z</updated>
<id>https://blog.skarhed.com/</id>
<content type="html"><p>Table of contents:
</p><div class="table-of-contents"><ul><li><a href="https://blog.skarhed.com/#background">Background</a></li><li><a href="https://blog.skarhed.com/#requirements">Requirements</a></li><li><a href="https://blog.skarhed.com/#alternatives">Alternatives</a><ul><li><a href="https://blog.skarhed.com/#defining-metadata">Defining metadata</a></li><li><a href="https://blog.skarhed.com/#scripting-with-templating-language">Scripting with templating language</a></li><li><a href="https://blog.skarhed.com/#eleventy-11ty">Eleventy (11ty)</a></li><li><a href="https://blog.skarhed.com/#astro">Astro</a></li></ul></li></ul></div><p></p>
<h2 id="background">Background<a class="tdbc-anchor" href="https://blog.skarhed.com/#background">#</a></h2>
<p>At university I used to be a part of a classical male choir, which is traditional for Swedish universities, dating back to the early 1800s. Our choir is anything but traditional, but that subject may be covered at a later date ;)</p>
<p>A lot of the repertoire in this genre is rather old, which makes it a prt of the public domain. A lot of famous composers have songs that still to this day are common to sing during Swedish traditional holidays. Prince Gustaf, Otto Lindblad and Hugo Alfvén are some of the most famous of these composers.</p>
<p>A big part of this genre, which is tightly connected to universities, is "snapsvisor"; drinking songs commonly sung before taking a schnapps.</p>
<p>Joakim Sandström, a previous conductor of my choir Snapsakademien, started a project where he wrote a lot of the classical songs in <a href="http://lilypond.org/">Lilypond</a>. This is a programming language that enables easy generation of music scores, usually in the form of PDFs. The initial purpose for this was to generate PDFs to combine them into a song book that could be used during a semester.</p>
<p>Lilypond provide possibilities for output aswell. MIDI-files, a music file format known for producing simple music, can be generated, so the melody can be listened to while practicing. This is perfect especially for people like me who have a hard time reading notes!</p>
<p>The library has grown enough to be useful beyond a single choir, so these scores can really be useful to publish alognside the MIDI-files.</p>
<h2 id="requirements">Requirements<a class="tdbc-anchor" href="https://blog.skarhed.com/#requirements">#</a></h2>
<p>Joakim Sandström is a happy volunteer that write these scores in his spare time. He has good knowledge of Lilypond, and even though he may understand the technical implementations of publishing the scores to the web, he shouldn't need to worry about it. Volunteer efforts are super important, and we should do anything in our power to not make any of these tasks more difficult or complex.</p>
<p>We can do this assumption that the knowledge should extend to the Lilypond output files. This means that we can assume the following:</p>
<ul>
<li>Song information is known, such as title, composer or artist.</li>
<li>Lilypond output file name is known</li>
<li>Output file location is known</li>
</ul>
<p>Furthermore, in order to make a clear connection to the structure of the website, it should preferably reflect the structure of the repository.</p>
<p>These are some other features we might want to consider:</p>
<ol>
<li>Easy way to list all the available songs</li>
<li>Simple way to implement a search feature</li>
<li>Categories or tags to group songs</li>
</ol>
<h2 id="alternatives">Alternatives<a class="tdbc-anchor" href="https://blog.skarhed.com/#alternatives">#</a></h2>
<ol>
<li>Scripting with templating language</li>
<li>eleventy (11ty)</li>
<li>Astro</li>
</ol>
<h3 id="defining-metadata">Defining metadata<a class="tdbc-anchor" href="https://blog.skarhed.com/#defining-metadata">#</a></h3>
<p>All of these need some kind of input data, as it is not trivial to extract data from Lilypond files. The choice of defining metadata highly depends on which SSG solution is chosen. Some alternatives for defining data could be:</p>
<h4>JSON files</h4>
<pre class="language-json"><code class="language-json"><span class="token punctuation">{</span><br /> <span class="token property">"composer"</span><span class="token operator">:</span> <span class="token string">"Otto Lindblad"</span><span class="token punctuation">,</span><br /> <span class="token property">"title"</span><span class="token operator">:</span> <span class="token string">"Längtan till landet"</span><span class="token punctuation">,</span><br /> <span class="token property">"categories"</span><span class="token operator">:</span> <span class="token punctuation">[</span><span class="token string">"spring"</span><span class="token punctuation">,</span> <span class="token string">"1800s"</span><span class="token punctuation">]</span><span class="token punctuation">,</span><br /> <span class="token property">"svgFiles"</span><span class="token operator">:</span> <span class="token punctuation">[</span><span class="token string">"./page-1.svg"</span><span class="token punctuation">,</span> <span class="token string">"./page-2.svg"</span><span class="token punctuation">]</span><span class="token punctuation">,</span><br /> <span class="token property">"midiFiles"</span><span class="token operator">:</span> <span class="token punctuation">[</span><span class="token string">"./all.midi"</span><span class="token punctuation">,</span> <span class="token string">"./t1.midi"</span><span class="token punctuation">,</span> <span class="token string">"./t2.midi"</span><span class="token punctuation">,</span> <span class="token string">"./b1.midi"</span><span class="token punctuation">,</span> <span class="token string">"./b2.midi"</span><span class="token punctuation">]</span><br /><span class="token punctuation">}</span></code></pre>
<h4>Frontmatter YAML in Markdown files</h4>
<pre class="language-yml"><code class="language-yml"><span class="token punctuation">---</span><br /><span class="token key atrule">composer</span><span class="token punctuation">:</span> <span class="token string">"Otto Lindblad"</span><br /><span class="token key atrule">title</span><span class="token punctuation">:</span> <span class="token string">"Längtan till landet"</span><br /><span class="token key atrule">categories</span><span class="token punctuation">:</span> <span class="token punctuation">[</span><span class="token string">"spring"</span><span class="token punctuation">,</span> <span class="token string">"1800s"</span><span class="token punctuation">]</span><br /><span class="token key atrule">svgFiles</span><span class="token punctuation">:</span> <span class="token punctuation">[</span><span class="token string">"./page-1.svg"</span><span class="token punctuation">,</span> <span class="token string">"./page-2.svg"</span><span class="token punctuation">]</span><br /><span class="token key atrule">midiFiles</span><span class="token punctuation">:</span><br /> <span class="token punctuation">-</span> <span class="token string">"./all.midi"</span><br /> <span class="token punctuation">-</span> <span class="token string">"./t1.midi"</span><br /> <span class="token punctuation">-</span> <span class="token string">"./t2.midi"</span><br /> <span class="token punctuation">-</span> <span class="token string">"./b1.midi"</span><br /> <span class="token punctuation">-</span> <span class="token string">"./b2.midi"</span><br /><span class="token punctuation">---</span></code></pre>
<h3 id="scripting-with-templating-language">Scripting with templating language<a class="tdbc-anchor" href="https://blog.skarhed.com/#scripting-with-templating-language">#</a></h3>
<p>The actual templating languiage does not matter much, as long a s it takes some kind of object and processes it. A personal preference would be Handlebars or Mustache.</p>
<p>For this, a script has to be written to traverse the folder structure and render the HTML files. This could be done with something like a bash script or a Node.js script.</p>
<p>The good thing with this approach is the flexibility. However, as soon as we look at thge requirements we listed previosuly, the complexity quickly increases. If we use this approach, then we basically need to write our own Static Site Generator.</p>
<p>Withoout proper though into the initial arcfhitecture, handling collections of songs kmight be difficult. Furthermore, search provides more complexity.</p>
<p>If we consider the fact that this project is on a volunteer basis, we want as little code as possible to maintain. With the features we require, the codebase may quickly increase uin size.</p>
<h3 id="eleventy-11ty">Eleventy (11ty)<a class="tdbc-anchor" href="https://blog.skarhed.com/#eleventy-11ty">#</a></h3>
<p>11ty offers a wide variety of templating languages. It also has something called a "data cascade" which defines the different levels from where it may get data.</p>
<p>The data may be defined in a YAML frontmatter, a use case which fits really well for writing blog posts. In the frontmatter things like <code>title</code>, <code>date</code> and <code>description</code> may be added, whereas in the actual body of the document, you can write Markdown. Neat!</p>
<p>In our case we do not have any need to write Markdown, so we can use JSON files instead, just containing the metadata. In a folder with songs in JSON format, an index template is applied to those and the JSONs in subfolders.</p>
<p>All scripting and shortcodes need to be written in the 11ty config. It is possible to extend it quite a lot, but the bare bones work really well without any scripting. The only issue here is that there needs to be consistent folder structure and naming conventions.</p>
<h3 id="astro">Astro<a class="tdbc-anchor" href="https://blog.skarhed.com/#astro">#</a></h3>
<p>Astro is one among many SSGs with supercharged templating, in this case powered by Javascript. In this case, YAML frontmatter is the only way to go. A downside is also that the layout for a spoecific post needs to be defined in each file, which breaks the promise that the Liliypond writer does nto need to know anything about the implementation.</p>
</content>