For a while now, I have been working on my Jekyll theme, structRDFaL, which is meant to make generating structured data in accordance with schema.org easier. As stated, improving SEO for your site is a secondary concern for paying attention to schemas. It should be about best practices and being a good netizen with just a little bit more effort.

The "a little bit more effort" is key to my current dilemma. schema.org has lots of information and examples, but presented in a way that more or less expects that you know what is going on. I have yet to find a bridge between the list of types and examples on a random schema page and the hard core (?) mostly unreadable (to me) technical standards type of documents. I would very much like to find a popsci type explainer/implementation describer on this topic. I expect that part of the problem is that I chose to use RDFa Lite vs JSON which would not (?) have the "envelope" problems I have encountered. Thus, I continue to be a cut-and-paste keyboard monkey and not a properly informed technician.

The problem with being a keyboard monkey is the endless and repetitive testing by doing and checking the results, instead of knowing and doing (and then testing to see if it's been properly implemented 🥸). In the midst of the Sisyphean coding by validation testing, I had a crisis of faith. Why was I doing this? If SEO is not the goal, then could/should I make do with proper structured HTML usage and call it a day? What did the Semantic Web want in the first place???

W3's Semantic Web Best Practices document was not helpful. More than half the links on the tutorial page are currently dead. I'm not trying to make my own technical vocabulary ... or am I???.

In any case, I'm certainly not trying to help you (or anyone who might choose to use my structRDFaL Jekyll theme) write your own formal 'net recognized vocabulary. So, why am I doing this? schema.org schemas are not even proper standards type things! Part of it, perhaps, is suffering from sunk cost (fallacy?) problems. So much time already wasted trying to do this thing, so just finish it. Most schemas like Blog or Book were relatively easy to implement (just a little more effort). Trying to make a generic HowTo tool has been a bear, though. Are schemas actually useful to the semantic web or no? What am I even doing and why??

This is my existential crisis, however, and you should not care. 😅 So, let me share what I have discovered about RDFaL for my fellow keyboard monkeys and leave it at that, for now.

<div property="itemListElement" typeof="HowToDirection">
  <meta property="position" content="1"/>
  <a href="more.html">
    <p property="text">Turn on your hazard lights and set the
      flares.</p>
  </a>
</div>
      

Detected               1 ERROR   0 WARNINGS  2 ITEMS
Unspecified Type       1 ERROR   0 WARNINGS  1 ITEM
HowTo                  0 ERRORS  0 WARNINGS  1 ITEM
      

<div property="itemListElement" typeof="HowToDirection">
  <meta property="position" content="1"/>
  <img alt="image showing positioning of jack" property="duringMedia" 
    src="position-jack.jpg" />
  <div property="text">Position the jack underneath the car, 
    next to the flat tire.</div>
</div>	
      

<div property="itemListElement" typeof="HowToDirection">
  <meta property="position" content="1"/>
  <div property="beforeMedia" typeof="ImageObject">
    <img alt="image showing car while still on the ground" 
      property="contentUrl" src="car-on-ground.jpg" />
  </div>
</div>
      

<div property="itemListElement" typeof="HowToDirection">
  <meta property="position" content="1"/>
  <img alt="..." property="duringMedia" src="position-jack.jpg" />
</div>
      

<div property="itemListElement" typeof="HowToDirection">
  <meta property="position" content="2"/>
  <figure property="beforeMedia" typeof="MediaObject">
    <img alt="..." property="contentURL" src="car-on-ground.jpg" />
  </figure>
</div>
      

<div property="itemListElement" typeof="HowToDirection">
  <meta property="position" content="3"/>
  <figure property="beforeMedia" typeof="ImageObject">
    <img alt="..." property="image" src="car-on-ground.jpg" />
  </figure>
</div>
      

<div property="itemListElement" typeof="HowToDirection">
  <meta property="position" content="4"/>
  <figure property="duringMedia" typeof="textObject">
    <p property="text">...</p>
  </figure>
</div>
      

<div property="itemListElement" typeof="HowToDirection">
  <meta property="position" content="5"/>
  <figure property="AssociatedMedia" typeof="textObject">
    <p property="text">...</p>
  </figure>
</div>
      

<div property="itemListElement" typeof="HowToDirection">
  <meta property="position" content="6"/>
  <figure>
    <picture>
      <img property="image" src="..." />
    </picture>
  </figure>
</div>
    

<a property="beforeMedia" href="bigger-before.jpg">
  <img property="thumbnailURL" alt="..." src="before-thumb.jpg" />
</a>
      

<a property="duringMedia"  href="bigger-during.jpg">
  <picture property="thumbnail">
    <img property="thumbnailURL" alt="..." src="during-thumb.jpg" />
  </picture>	
</a>
      

itemListElement
   @type                      HowToDirection
   position                   2
   text                       some instructional text
   afterMedia                 after text
   beforeMedia                https://example-test.site/bigger-before.jpg
   thumbnailUrl               https://example-test.site/before-thumb.jpg
   duringMedia                https://example-test.site/bigger-during.jpg
   thumbnailUrl               https://example-test.site/during-thumb.jpg	
      

One problem was that the schema differences between webpage-of-a-thing vs webpage-that-is-a-blogposting-of-a-thing extended into the header stuff, so default being a complete page layout that would be used as the (duh) default layout for other pages caused issues similar to the ones that I was having with sitehome.

I could solve some of my problems if I could process some data and then pass a new page title or similar down to default. An answer from Jekyll Talk or Stack Overflow that I can no longer find said variables defined in one layout could be accessed by another depending on order of inheritance. That was a lie. Variables (eg. {% assign myvariable = "something" %}) are not shared between layouts or even the page itself. Order does not matter. Custom variables (eg. {{ page.title}}) cannot be assigned to outside of the front matter. Further, front matter cannot handle liquid variables

---
title: My Name - {{ site.tag }}
---
This will not work.

So, if you want to code in chunks in order to reuse bits and pieces and you want to use variables that change (and not just static variables you can insert into front matter) then the only answer is includes. Include files are just merged into the text of the layout don't need to "share" data. The main annoyance for me is that Liquid logic and flow control is so verbose. It feels like if you were allowed to have data cascade through your inherited layouts it would not feel so much like amateur hour kludging.

For a less emotional illustration of the issue, imagine that you have 4 types of pages that require processing of the <header> in general plus the title <h1> differently, say, sitehome, bloghome, blog page, and standard page. Footer, nav, and general page layout is the same which is put into a default layout. Obviously, you would need to code some switches into your default for the special cases but 4 is manageable. Then you start adding new types like, say, gallery home and gallery page, catalog home and catalog page, forum home and forum page. Databases or data files are involved so you can't just pass known text to the layout. The code explodes into a massive blob of if-then-else special cases. Wouldn't it be nice if, instead, you could designate pages with a gallery page layout, access the database, do some processing and pass the title plus custom breadcrumbs to default? Maybe gallery page and catalog page share some logic but access different databases so both gallery and catalog could share a framed layout which eventually slots into default. If only processed variables could be passed between layouts.

The problem here is most intractable if default is inviolable. If, say, you are using a theme that you don't want to re-clone or re-merge your customizations with each new release.

In any case, this is not to say that layout inheritance doesn't work or that it is useless. It was, however, a little counter-intuitive when I was trying to map it all out for my own mental model and using non-standard fragments. Let's say all your layouts are like this (except for default not having a further layout):

---
layout: default
---
1<br>
{{ content }}
1<br>

(default)
1
"page content"
1
(default)

Another confusing factor is that I was using fragments (as previously mentioned) to test out ideas of having header pieces in a layout that would then be completed in the basic/default layout but Jekyll was oh-so helpfully adding a basic html page's skeleton because my default layout didn't have anything of the sort. Frustrating and boggling when I wasn't expecting it. Further experimentation has shown, though, that if I at least put the <html><body></body></html> in myself, I can have layouts with wacky incomplete page fragments.

Now that I know exactly what my parameters are, I can decide for myself if I want to use the tools as intended or if shenanigans and tomfoolery will rule the day.

Once your local development is done, here's my reference for pushing it out to the world: How to Create and Publish a Jekyll Theme Gem - David Darnes.

I should really make a separation from the structRDFal demo site from the theme itself, even if that's just the background colours somewhere else...?

Based on occasional idle research, I decided that I was choosing between 11ty and Hugo. They are the fastest static site generators (SSGs) and Jekyll was getting slow for my bigger sites. Hugo uses the Go programming language (sometimes called Golang) which in my aged and judgmental opinion is a "real" language as it is based on C. I learned Ruby for Jekyll, I could learn Go for Hugo. 11ty uses JavaScript which is an abomination that I have selectively blocked from browsers for decades. My unreasoning hatred for JavaScript is why I have resisted 11ty for a number of years now (I don't think it was a thing when I first started work with Jekyll?), but so many developers who are my CSS reference sources are 11ty adherents so maybe I should???

Rooting for Hugo, I tried to take a logical and practical approach to deciding between the two. Hugo reportedly has the edge in speed. Both are FOSS. So much of 11ty's purported advantage is based on the idea that you already know JavaScript, which I do not. In any case, the deciding factor was plugin documentation. I found some vague stuff about plugins "could" be written for Hugo by writing modules in Go. 11ty's plugin authoring documentation is less vague and, while not as abundant as I remember Jekyll documentation being, at least exists. A couple of videos that claim to be how-tos can be found on YouTube. Instructions for what should be a text-heavy exercise does not belong in video format.

** Old bag yells at clouds (and prepares to learn JavaScript) **

Following 11ty's own getting started guide, I had to insert a brew install npm *sigh*... Finishing the page we end up with, basically, a "Hello, World" type of thing. The first thing I want to change is the output going to source-directory/_site, where do I do that? It takes a few minutes but there's no default configuration file. That's stupid. Sure, don't put anything in there that you don't need to keep things light, but in what universe would you not end up needing a configuration file? 8-P

Configuration should be the easiest part, but I'm already in trouble in as much as there wasn't a default configuration file and the configuration file is not even remotely plaintext. We are already programming in JavaScript and most of the getting started tutorials assume we know how to do that or don't cover configuration at all! Add to this that there are (at least) two major formats of JavaScript itself (CommonJS and ESM) so the tutorials that do cover configuration don't match which cripples my default in-context contrast and compare learning style. I just wanted to tweak an existing config file and get started with something basic. Instead I have to learn how much JavaScript first?

Trying to find some ESM configuration file examples, I came across this. Now, I can understand some graphic designer wanting "pretty links" if they are uninformed and afraid of the messiness, but a programmer enforcing that nonsense is just nausea-inducing and disqualifying.

Part of my eagerness to move away from Jekyll has to do with something I read about a redesign in which they intended to remove Pages as a content type. That was a while ago and since it does not appear to have happened, perhaps I can stop worrying? That or try harder to look for Hugo documentation about plugins? ¯\_(ツ)_/¯

Now, I was/(am?) deeply into Jekyll, industriously building it out with plugins, generators, and such to create the perfect standards based, sematic webified, site engine. Why would I want to restart that sort of thing from scratch with 11ty??? Other than the apparent momentum of people jumping ship from Jekyll to 11ty, many of whom I was using as guidance in my CSS adventures. Why would I want to learn this new thing, now?

Two things caught my eye:

• 11ty is much faster
• better templating options

11ty is Javascript based and that's an enormous red flag for me as I've spent most of my 'net life avoiding Javascript. As a result, everyone's "11ty is based on Javascript, which you already know!" is just not true for me (or Node or Grunt or Gulp or ...). Of course, I didn't know Ruby when I started with Jekyll either, so it's not like I can't learn... it's just that I don't want to. ( >д<)

Then there's the template thing. 11ty is very proud of all the templating languages it supports. Liquid is interesting if flawed and I've never used another templating language, so it is tempting to see what else is out there. For a long time, I could not find any useful comparison reviews to help me decide on a templating language to try. I didn't want to jump from Liquid to Nunjucks just because all those JS-lovers think it's great. Finally I found a useful comparison chart.

I read through the whole post and based on that plus the handy chart, the list cuts down to ERB, Liquid, Twig, or Nunjucks. Twig is PHP based and I'm already uninterested in PHP, so: No to Twig. ERB is actually a generic templating system written in Ruby that happens to do HTML. I don't hate Ruby, but signing up for ERB would be signing up for even more Ruby and even more Javascript ... is there a point to that?

Liquid, of course, I already know, except that Jekyll's Liquid is not quite the same as 11ty's Liquid. So, is it better to make a clean break? On the one hand, one of the strengths (?) of 11ty is that you can mix and match templating languages. On the other hand, once I start converting tags, filters, plugins, and whatnot to filters, shortcodes and plugins would I be just doubling the work for myself?

If there were a "native" template language for 11ty it'd be Nunjucks... but then there's the whole web component "issue". It's a standard, and so merits attention. It also does what we would be using filters/plug-ins/shortcodes for, to a certain extent. What would be best to use? For my simple needs, is WebC a bonfire where a match would do?

Now, I could fabricate more data, but since the inspiration for wanting book lists in the first place was sitting right there, no need to imagine a list. I'd take a few books from the page, create them as collection records, test out the whole collection stuff, decide how to template/style a list entry (I was already thinking about how to activate/deactivate fields for a nice listing format), and Bob's your uncle! Of course, life is not so simple.

The second book (which in retrospect, I should maybe have skipped?) was one of the more complicated types you're likely to encounter:

1. there are multiple editions
2. it is the translation of another book
3. many elements have multilingual versions

Add more fields. Define them inside the schema and just for the page. Book part, per se, done but then I have all this publication/publisher information that I wanted to retain. You can. You can define a publisher as an Organization and then their address can be a PostalAddress and, and, and... but do you need to? Examples on schema.org use WorldCat and VIAF as resources. If I could point to an official record somewhere with all the publisher information or even all the author information, then I wouldn't have to be storing or coding it myself: go there if you're curious or need to know for whatever.

VIAF is hideously confusing at first glance. It was quick to narrow down from "author with this name" to "author of this book with this name". The record had tonnes of other entries that I believe are librarians from various different instutions doing data entry ever so slightly differently, but no so much that the authority's software doesn't collate them together (without winnowing them down to a canonical one). But they only had one of her five books.

WorldCat on the other hand looked to have all of her books, but very few had the cover images, in particular the non-English editions making me less certain of my interpretation. Also, in WorldCat, I was unable to winnow out the other authors with the same name, so... what to do???

I had hoped that the "official" sources of the world would save me from formally formatting a bunch of data and let me just point to the references but I have more data than they do, and I am begrudgingly willing to encode it. If I go to the trouble, can I contribute it to the world's formatted data? VIAF and WorldCat are library based places. Of course, you don't want random mischievous users polluting your rigorously formatted formal data pool, but you still need help, no? I found a document that mentions that VIAF takes "contributions" from WikiData which does take user contributions... should I?

The lazy (correct??) voice in my soul says that I could retain this extraneous information, unstructured, in the description of my book data and call it a day (or even not bother retaining it, who cares?). Does the publisher even exist anymore? Would/will anyone ever need to make use of the information? These are some of the thoughts that plague an info-pack rat.

You can't. For some reason "they" don't want you to.

If you were trying to keep your data close to where you are using it in an _include, that's not possible because there's no front matter in _includes and you can't create/populate an associative array/hash table in regular code either. Hash tables or dictionaries can only be created/defined in YML files or front matter. So, define your hash array in the nearest _layout front matter, site _config.yml, or site _data/ if what you really want is to put it in the front matter of an _include.

1. Hash arrays cannot be created within Jekyll+Liquid
   • vector arrays can
   • hash arrays can be created in front matter or .yml files

Hash Arrays vs Dictionaries

For some guidance on YML, there's the source from yaml.org and a shorter YML guide. A caveat on the shorter guide, however, don't put a "-" in front of dictionary keys. I'm not sure if that's a quirk of Jekyll-Liquid/Shopify Liquid though.

To access

dictionary:
  zero:
    number: "0"
  one:
    number: "1"
    adj: 
      - "first"
      - "unary"
    ordinal: "primary"
  two:  
    number: "2"
    adj: 
      - "second"
      - "dual"
      - "binary"
    ordinal: "secondary"

Getting at the data within. Note that the first thing we try doesn't work.

dictionary[0]
dictionary.zero {"number"=>"0"}
dictionary["one"] {"number"=>"1", "adj"=>["first", "unary"], "ordinal"=>"primary"}
dictionary.two.adj[0] second
dictionary["two"]["adj"][1] dual
dictionary["two"].adj[2] binary

<section id="tag-cloud">
  <h2>Web Tech Blog Tag Cloud</h2>
  <nav>
{% assign sortedCats = site.categories | sort %}
{% for category in sortedCats %}
{% assign cat = category[0] %}
  {%- unless cat == "blog" -%}
    <a class="category-cloud" href="{{ site.blogPath }}categories/{{ cat | slugify: 'pretty' }}"
        style="color: hsl({{ "now" | date: "%N" | divided_by: 400 }}, 100%, 40%); font-size: {{ category | last | size | logn }}em">
            {{ cat }}</a>
  {% endunless -%}
{% endfor %}
{% assign taglist = site.tags | sort %}
{% for tagitem in taglist %}
   {% assign tag = tagitem[0] %}
    <a class="tag-cloud" href="{{ site.blogPath }}tags/{{ tag | slugify: 'pretty' }}"
        style="color: hsl({{ "now" | date: "%N" | divided_by: 400 }}, 100%, 40%); font-size: {{ tagitem | last | size | logn }}em">
            {{ tag }}</a>
{% endfor %}
    </nav>
</section>

The code is very close to the same except that site.blogPath is something I defined for my stuff that won't exist for you. Since everything is in the blog category, there didn't seem to be any point to including it in the cloud.

For fun, I set the colour with HSL with a random hue. Since the hue defaults to a number that represents a degree between 0-360 but larger numbers just act as more circuits around the circle, big numbers just add to the randomness. So, I made a pseudorandom number generator by taking the current time in seconds and dividing by 400 and rounding to an integer. It works well enough for me. ¯\_(ツ)_/¯.

For the font sizes, I wanted more size variation, but with a size cap. Obviously, I needed logarithmic math, so I had to make a filter like so:

module Jekyll
  module LogFilter
    def logn(input)
      sprintf("%.2f", 1 + Math.log(input, 3))
    end
  end
end

Liquid::Template.register_filter(Jekyll::LogFilter)

For style, I borrowed the basic layout from Alvaro Montoro on DEV Community like so:

#tag-cloud h2{
    text-align: center;
    margin-top: 2em;
    margin-bottom: 0;
} 
#tag-cloud nav {
    display: flex;
    flex-wrap: wrap;
    align-items: center;
    justify-content: center;
}
#tag-cloud a {
    display: block;
    padding: 0.125rem 0.25rem;
    text-decoration: none;
    position: relative;
}

In your searches, you may have come across Staticman which is open source and promises to be static... but the catch is that you need to be serving your site from GitHub. Even if you can put your domain name on it (haven't bothered checking), you are definitely not running on your own server and, at least for me, serving from GitHub misses the point.

Some of my sites have comments that were imported from Drupal. Obviously that mechanism is gone with the conversion to Jekyll, and even though I don't get many comments (that aren't spam) I still want the ability for my readers to comment. I just don't want spammers and hackers to have any weaknesses to attack.

To be honest, if no one had the ability to comment, I doubt anyone would care. I do have a contact form and my email address on all my pages if people want to connect. But, I developed a comment file system and wrote a generator to render my commented posts, so why not finish out a system that would work with a real, live interactive readership? My solution works for sites with small, calm readership because they need to email you, and wait for you read their email and then create a comment record by hand and add it to your site.

Having said that, I have no doubt that there are mechanisms that can be triggered by email to process a comment to add things to your site and cron jobs to process and push out your modified site, but that would be an exercise for the reader. ( ´ｖ｀)

I searched to see if there was a maximum Ruby version for Jekyll before blowing everything up, but only found "Ruby version 2.5.0 or higher". It wasn't until much later (Sorry, I can't find the page anymore) that I found a page where someone was asking about Ruby versions and someone fairly official mentioning that Ruby 2.7 (?) being the version that the Jekyll developers themselves use. This is not that page.

Still, this series of articles made it seem pretty easy. Don't listen to Michael until part 4, though... at least if you're using MacOS. If you're on a Mac, do this instead. Prior to finding that article, I had done a lot of gem/bundle/brew updating without actually affecting the Ruby that was being used. rbenv was also involved, so you can see that I was throwing all the spaghetti at the wall.

Of course, that's not the end of the story. You also need to track through your Jekyll files to see where versions are being specified. Check your Gemfile and delete your Gemfile.lock. Because I was also developing a theme as a gem, I had a name-of-my-theme.gemspec which had versions specified in there as well. After I whack-a-mole'd all of those (and regenerated the theme gem), I did a bundle install and bundle update to get all the things, like Bundler itself, into versions that wanted to work together and then Conversion error: Jekyll::Converters::Scss encountered an error while converting 'assets/css/style.scss':

I then read a bunch of stuff about people having issues with Sass and Jekyll front matter processing or Liquid issues, but my problem Error: "var(--nav-width)" is not a number for `max' on line 93:15 of _sass/my-theme.scss, in function `max` made me think maybe it's not a Jekyll-Sass problem, but a Sass-modern CSS problem. Yahtzee!