YAML documents -> HTML?

I have a simple problem. I want to have a set of YAML files and create static HTML from them.

Files could look like this:

name: IBEW Local 123
county: orange
state: CA
description: Local 123 has close ties with developers.
tags: [active, developers]

And I want HTML that looks like this:

/CA.html

Active

  • IBEW Local 123
    • Orange County
    • Local 123 has close ties with developers.
  • IBEW Local 456

Developers

  • IBEW Local 123
    • Orange County
    • Local 123 has close ties with developers.

Is Jekyll a good fit for this use case? Using YAML as “data files”? I’ve Googled a bit and can’t seem to find a good static site generator for this need. Maybe the need is too simple.

Related:

Yes, Jekyll can handle this nicely. I created a video that shows you how to use various data files like CSV, TSV, YAML, and JSON. You can see the link at the bottom of this message.

That said, the code is super simple, so all you will need to do is create a Jekyll site with the theme you want and you can use the following code to get started.

:abc: Create the dataset

Here is a sample dataset I created based on your requirements (plus a little extra). Note that by default Jekyll uses a folder called _data in the root of your Jekyll folder. If it does not exist, just create it and then add the YML file. No further configuration is needed!

./_data/unions.yml

items:
  - name: IBEW Local 123
    county: Orange County
    state: CA
    description: Local 123 has close ties with developers.
    tags: [active, developers]
  - name: IBEW Local 456
    county: San Francisco County
    state: CA
    description: Local 456 has close ties with architects.
    tags: [active, architects]
  - name: IBEW Local 789
    county: San Francisco County
    state: CA
    description: Local 789 is now part of local 456.
    tags: [inactive, architects, developers]

:page_facing_up: Create the web page

Now that you have data in the ./_data folder, you can create a web page to display the content. To get the bullets, you use HTML unordered lists (the <ul> and <li> tags). You can also use Markdown if you like, but my example uses HTML.

Somewhere on your site, create a unions.html file. In my example, I will create it in the root Jekyll folder, like this:

./unions.html

---
layout: page
title: Unions
---
{% assign unions = site.data.unions.items | where_exp: "union", "union.tags contains 'active'" %}
{%- if unions -%}
    <h2>🟢 Active</h2>
    <ul>
    {% for union in unions %}
        <li>{{union.name}}</li>
            <ul>
                <li>{{union.county}}</li>
                <li>{{union.description}}</li>
            </ul>
    {% endfor %}
    </ul>    
{%- endif -%}

{% assign unions = site.data.unions.items | where_exp: "union", "union.tags contains 'active' and union.tags contains 'developers'" %}
{%- if unions -%}
    <h2>🟢👷 Active Developers</h2>
    <ul>
    {% for union in unions %}
        <li>{{union.name}}</li>
            <ul>
                <li>{{union.county}}</li>
                <li>{{union.description}}</li>
            </ul>
    {% endfor %}
    </ul>    
{%- endif -%}

{% assign unions = site.data.unions.items | where_exp: "union", "union.tags contains 'inactive'" %}
{%- if unions -%}
    <h2>❌ Inactive</h2>
    <ul>
    {% for union in unions %}
        <li>{{union.name}}</li>
            <ul>
                <li>{{union.county}}</li>
                <li>{{union.description}}</li>
            </ul>
    {% endfor %}
    </ul>    
{%- endif -%}

:checkered_flag: Final result

After you build your site, the browser will display your content, like this:

:warning: Caveat

Jekyll is a static site builder, which means it does not read data live from a database. You would use another technology for that.

If you use something like GitHub Pages (or any site that supports Jekyll), you can always upload and replace the old file or modify the file by hand. Jekyll will rebuild in a few minutes and the site will be up to date with your changes.

You could automate the creation of the file and even automate the upload of the file, but that will take some specialty coding (like a GitHub Action, for example).

:bookmark: Using data with Jekyll video

To learn more about how to use custom data with Jekyll, you can use this training video I created. This is on a playlist that contains many more helpful tutorials on how to use Jekyll, so feel free to peruse at your leisure.