shellsharks Devlogs

RSScaping

mike@shellsharks.com (Mike) — Wed, 19 Mar 2025 16:01:00 -0400

Having an RSS feed for your site’s content is one of the most important things you can do as a citizen of the open web. If you want people to tune into your writing, it just makes sense to have one. Or better yet, you could have many RSS feeds, as I do—each from their own unique collection or topic(s). This site is built on top of Jekyll, a static-site generator. Each of the individual RSS feeds on my site are comprised of a .xml file which sets the feeds metadata and programattically generates the feed records, and a .xsl file which (very optionally) gives the feed a web view.

In the years I’ve had this site, I’ve had to tune and tweak the .xml file quite a few times to continue to improve the way it works, the content it exposes and the metadata that is associated with the feed. Here I’ll explain some of those tweaks and the thought process behind them.

RSS XML File

My site’s RSS feed .xml file. I have substituted many values in the block below with placeholders such as [FEED NAME].

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet href="[LINK TO .XSL FILE]" type="text/xsl"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:shark="https://shellsharks.com/feeds/shark-namespace">
  <channel>
    <title>{{ site.title | strip_html | xml_escape }} [FEED NAME]</title>
    <description>{{ site.description | xml_escape }}</description>
    <link>{{ site.url }}</link>
    <language>en-us</language>
    <managingEditor>[EMAIL] ([ALIAS])</managingEditor>
    <webMaster>[EMAIL] ([ALIAS])</webMaster>
    <atom:link href="{{ "[RELATIVE .XML FILE LOCATION]" | prepend: site.baseurl | prepend: site.url }}" rel="self" type="application/rss+xml"/>
    <pubDate>{{ site.time | date_to_rfc822 }}</pubDate>
    <lastBuildDate>{{ site.time | date_to_rfc822 }}</lastBuildDate>
    <image>
      <title>{{ site.title | strip_html | xml_escape }} [FEED NAME]</title>
      <url>{{ site.url }}{{ site.avatar_url }}</url>
      <link>{{ site.url }}</link>
    </image>
    <generator>Jekyll v{{ jekyll.version }}</generator>
    {% assign sorted_posts = site.posts | sort: 'date' | reverse %}
    {% for post in sorted_posts limit:100 %}
      <item>
        <title>{{ post.title | strip_html | xml_escape }}</title>
        <shark:summary>{{ post.excerpt }}</shark:summary>
        <description>{{ post.content | replace: 'href="https://shellsharks.com/', 'href="https://[DOMAIN]/' | xml_escape }}</description>
        <pubDate>{{ post.date | date_to_rfc822 }}</pubDate>
        <link>{{ post.url | prepend: site.baseurl | prepend: site.url }}</link>
        <guid isPermaLink="true">{{ post.url | prepend: site.baseurl | prepend: site.url }}</guid>
        {% for tag in post.tags %}
        <category>{{ tag | xml_escape }}</category>
        {% endfor %}
        {% for cat in post.categories %}
        <category>{{ cat | xml_escape }}</category>
        {% endfor %}
      </item>
    {% endfor %}
  </channel>
</rss>

Some important things to note from the .xml file…

You’ll notice the shark namespace established in the initial <rss> element. Within the RSS <generator> elemtn you will see a tag from this namespace, <shark:summary>. I explain what these are for here.
There’s a lot of html stripping (strip_html) and xml escaping (xml_escape) being done. This is because RSS clients, and general RSS spec gets very cranky about certain characters being included in feeds.
For any date-related tags, be sure to use RFC822-compatible (date_to_rfc822) date strings. Otherwise things break.
Remember to sort your RSS feed output using sort: 'date' | reverse.
You can limit the number of posts that are included in your generated RSS feed by using the limit:[COUNT] directive in your Liquid for loop (as I did here {% for post in sorted_posts limit:100 %}).
For a full-content feed, use the following syntax in your <generator><description> tag ⬇️. This uses the content variable to pull in the full content, fixes relative links with replace: 'href="https://shellsharks.com/', 'href="https://[DOMAIN]/' and then does the usual xml_escape operation.

{{ post.content \| replace: 'href="https://shellsharks.com/', 'href="https://[DOMAIN]/' \| xml_escape }}

You can limit the source collections an RSS feed is generated from using something like this: {% assign pagesandnotes = site.posts \| concat: site.notes \| concat: site.scrolls %}
You can filter the feed records by front matter tags using syntax such as this: {% if post.tags contains 'fediverse' or post.tags contains 'social' or post.tags contains 'indieweb' %}
Create an individual .xml and .xsl file for each RSS feed you’re interested in having! A lot of the code is reusable with minor tweaks to customize for each of your feed usecases.

RSS XSL File

My site’s RSS feed .xsl file. I have substituted many values in the block below with placeholders such as [RSS FEED TITLE]. XSL, or eXtensible Stylesheet Lanugage is a styling language for XML. The syntax is somewhat arcane, but easy enough to use to create something simple like I have to spruce up your raw .xml RSS feeds (or other .xml files like a Sitemap).

I won’t spend time explaining the xsl-related syntax, as I believe you can kinda reverse-engineer how they work by looking at what is below, but I will note that you can use Jekyll includes to further stylize and bring these xml files under the umbrella of your site’s larger thematic design.

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version="3.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd" xmlns:shark="https://shellsharks.com/feeds/shark-namespace">
  <xsl:output method="html" version="1.0" encoding="UTF-8" indent="yes"/>
  <xsl:template match="/">
    <html xmlns="http://www.w3.org/1999/xhtml">
      <head>
        <title><xsl:value-of select="/rss/channel/title"/> [RSS FEED TITLE]</title>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
        <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1"/>
        <meta charset="UTF-8"/>
        <link rel="stylesheet" href="[LINK TO CSS FILE]"/>
      </head>
      <body>
        <header>
          <div class="sitetitle">
              <a href="/"><img src="[HEADER IMAGE]" alt="[ALT TITLE]" height="30" /></a>
          </div>
          <div class="head">
            <div class="description">
              <p><xsl:value-of select="/rss/channel/description"/></p>
            </div>
          </div>
          <div class="aboutfeeds">
            <p>This is a web feed that can be viewed in the browser. <strong>Subscribe for free</strong> by copying the URL <code><mark>[.XML URL]</mark></code> into your RSS reader. Learn more <a href="https://aboutfeeds.com">about feeds here</a>. A full listing of this site's feeds can be found <a href="[LINK TO FEEDS INDEX PAGE]">here</a>.</p>
          </div>
        </header>
        <main>
          <h2><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 455.731 455.731" xml:space="preserve"><path style="fill:#f78422" d="M0 0h455.731v455.731H0z"/><path style="fill:#fff" d="M296.208 159.16C234.445 97.397 152.266 63.382 64.81 63.382v64.348c70.268 0 136.288 27.321 185.898 76.931 49.609 49.61 76.931 115.63 76.931 185.898h64.348c-.001-87.456-34.016-169.636-95.779-231.399z"/><path style="fill:#fff" d="M64.143 172.273v64.348c84.881 0 153.938 69.056 153.938 153.939h64.348c0-120.364-97.922-218.287-218.286-218.287z"/><circle style="fill:#fff" cx="109.833" cy="346.26" r="46.088"/></svg> Latest Posts</h2>
          <xsl:for-each select="/rss/channel/item">
            <article>
              <h3><a hreflang="en"><xsl:attribute name="href"><xsl:value-of select="link"/></xsl:attribute><xsl:value-of select="title"/></a></h3>
              <footer id="pubdate">Posted: <time><xsl:value-of select="pubDate" /></time></footer>
              <p id="postdescription"><xsl:value-of select="shark:summary"/></p>
            </article>
          </xsl:for-each>
        </main>
        <footer>
          {% include footer.html %}
        </footer>
      </body>
    </html>
  </xsl:template>
</xsl:stylesheet>

One thing to note is the use of the shark:summary identifier in the article postdescription element. This is to bring in a more human readable form of the post description rather than the full-content, w/ HTML that is set by default. I describe what this is and why I’m doin’ it here.

“Shark” Namespace

Upon popular request, I recently upgraded all of my RSS feeds to be “full content”. This means that full-length articles, including much of the styling and images would be available directly within folks RSS readers, for those who enjoy consuming directly in-client, rather than clicking out to read within the confines of my site. I personally think reading on-site is the better way to enjoy mine and other people’s content, but to each their own!

This modification however had a negative downstream effect on the human-readability of my RSS feeds on the web. Last year I gave my .xml RSS feeds a makeover by giving each a .xslt file, which styled them and made them viewable via the browser. When I modified the feeds to be “full-content”, this changed the view of each post record in the stylized feed to be a single-line glob of HTML—not very readable! I wanted to fix this, but needed a way to do it that would keep my RSS .xml files in-spec enough to be handled by RSS clients.

The RSS 2.0 Specification states that “A RSS feed may contain elements and attributes not described on this page, only if those elements and attributes are defined in a namespace.”. Alrightey then, I needed to figure out how to establish a namespace and put custom elements in it. Enter the “shark” namespace. After much trial-and-error, I finally figured out how to establish the namespace, initialize a variable element in the .xml file and then reference it in the associated .xslt file. This ultimately allowed me to keep what shows up in the actual RSS feed as the full-content, HTML-laden blob and what shows up in the web view as a clean, human-readable, excerpt of each post record. Cool!

There’s a lot I still don’t understand about .xml namespaces, and XSLT in general. For now, I think I’ve figured out the bare minimum I need to, to solve this single issue. One notable, unexplained quirk that I encountered was that I needed to put my new <shark:summary> element before the standard RSS <description> element or it just didn’t work. I’m sure there’s an explanation for that but I couldn’t tell you what it is (yet).

Ongoing RSS Validation Issues

Full-content RSS feeds are great, for those who want that level of detail directly in their RSS clients. But having that much stuff jammed into the rather finicky RSS protocol is a recipe for well, validation issues. So, I’m going to create a running list of current validation issues for my RSS feeds here, and (hopefully) document how I ultimately address them. It’s worth pointing out that my feeds appear to be working fine in the RSS clients I have tried out, despite these issues/errors. But, I’d still like to fix them where possible.

According to the W3C Feed Validation Service I have a number of validation issues…

Missing namespace for p (84 occurrences)

<shark:summary><p>Here’s another <em>Blog Questions Challenge</em>. ...

I have a bunch of individual linstances ofo the following “invalid characther in a URI” error… Invalid character in a URI: ]/whats-a-home-page

</description>

Missing namespace for div

<shark:summary><div class="poem">

In addition, interoperability with the widest range of feed readers could be improved by implementing the following recommendations.

Use of unknown namespace: https://shellsharks.com—(LOL! They don’t like my sketchy shark namespace 🦈.)

<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:shark="htt ...

description should not contain relative URL references: #silliest-souvenir (1330 occurrences)

</description>

Invalid HTML: Unexpected start tag (a) implies end tag (a). (3 occurrences)

<description><p>My site is over <a href="https://shell ...

style attribute contains potentially dangerous content: color:var(–shellsharks-color);text-decoration:underline!important; (22 occurrences)

</shark:summary>

Non-html tag: svg (4 occurrences)

</shark:summary>

description should not contain script tag (4 occurrences)

</shark:summary>

description should not contain style tag (3 occurrences)

</shark:summary>

description should not contain onkeyup attribute (3 occurrences)

</shark:summary>

description should not contain onclick attribute (2 occurrences)

</shark:summary>

All kinda interesting huh?… Well I’ll work through these as I have time. In the meantime, if you know how to address any of these, or you’re seeing actual impact on a feed in your client, please reach out so I can fix them ASAP!

The Changelog

mike@shellsharks.com (Mike) — Mon, 17 Mar 2025 23:54:00 -0400

How I’ve built the Changelog on my site. The Changelog is a day-by-day list of changes to the site. It is something I manually update and includes many, but not all, changes. I tend to call out content changes to individual blog posts, but typically avoid listing out each and every little modification to other bits of the site’s code. It serves as an easy way for me to capture updates to the site that wouldn’t otherwise be explicitly mentioned.

The changelog is built using two separate constructs, a collection of weekly changes files and the changelog file itself. An example of the changes file front matter and markdown is shown below.

---
layout: page
title: Weekly Changes 3/17/25-3/23/25
description: Changes made March 17, 2025 - March 23, 2025
date: 2025-03-17 00:00:00 -0500
updated: 2025-03-17 23:54:00 -0400
---

###### March 17, 2025
- List
- of
- changes
- here

To pull in each of the weekly changes files, the following Liquid code is employed. Pretty simple actually!

{% assign changes = site.changes | sort: "date" | reverse %}
{% assign latest = changes | first %}

<h1>Changelog</h1>
Last Update: <i>{{latest.updated | date: '%B %-d, %Y | %l:%M %p %:z'}}</i>

<hr/>

{% for change in paginator.posts %}
{{ change.content }}
{% endfor %}

That’s it!

In the future, It’d be nice if this log could be dynamically populated with things like net new content. Content changes to existing, posts would either still need to be manually updated here, or maybe even exist in per-post change logs.

Mastodon Auto-PESOS

mike@shellsharks.com (Mike) — Tue, 11 Mar 2025 11:32:00 -0400

As someone who has fully embraced the IndieWeb, owning my data and maintaining a canonical identity on the web is very important. Though I operate a lot of my online life directly out of my website, it doesn’t mean I don’t participate in other social networks. What I don’t want is for my ‘content’ to live solely within any external platform, silo or walled garden. Finding a way to archive or otherwise make this content available on my own site mitigates this. PESOS (i.e. “Publish Elsewhere Syndicate (to your) Own Site”) or what I like to call “reverse syndication” is the practice of archiving content that is originally posted elsewhere on the web, back to your site - the single source of origin. The problem is, if a lot of your content originates outside your site, you have to either deal with the overhead of manually archiving it, or, find a way to automatically do it. Here, I talk about how I (finally) found a way to semi-auto-PESOS select Mastodon posts to the site.

Traditionally, my syndication strategy has been very curated, and very manual. It’s time consuming to archive stuff I post elsewhere, and that overhead scales rapidly if I am generating a lot that originates not on my own site. It requires that I, A. remember to archive it at all, and B. that I make nuanced decisions about whether something is worth archiving to begin with. That threshold for whether something is worth it or not can vary depending on how lazy I am being, to be frank. If there was a way for me to automatically pull down posts, add the appropriate front-matter and use some logic to determine which posts I would actually want to bring back to my site, that would save me a lot of time! Not only that, but there would be things that could make it to my site that I traditionally wouldn’t have bothered to try and manually bring over. Awesome!

Setting PESOS and data ownership aside for a second though, a big motivator for me wanting to pull in content from around the Internet was Molly White’s Activity feed. I loved the idea of just having that composite feed of everything I was up to all in one mega timeline. Bringing in Mastodon posts as I explain in this devlog is one piece to that ultimate indieweb-puzzle.

Mastodon markdown archive

I’ve had this dream of automating the reverse-syndication of my Mastodon posts since April(ish) of 2024, and had searched for ways to pull in this content off and on since then. Recently though, I came across this post, “Archiving and syndicating Mastodon posts”, which seemed to exactly meet my needs. ¹ So, I cloned down the repo and tried it out! ²

It didn’t go well.

I was getting an incomprehensible traceback and wasn’t sure how to troubleshoot. I thought, maybe it could be the version? So I tried a downgraded version and still no dice. Finally, I went back and actually re-read the original post and tried to follow slowly, step-by-step, and sure enough, it was something pretty simple that was the issue (isn’t it always?). Gabriel makes it pretty clear that the dist and user flags are required, and sure enough, they super are. I won’t dock any points from Gabriel for not handling those errors gracefully, after all, this is freely available and otherwise the script works great!

Planning and Mechanics

OK, so I’ve proved that I can get the script to work, now I needed to figure a few things out…

What posts did I want to pull in? (e.g. boosts, replies, public-only, etc…)
Where do I want these posts to live on my site?
What front matter is important to populate for these posts? What data is available in the .json output for each post?
Do I need to tweak any of my existing code to accomodate the posts pulled in via this script?

What to Archive?

The first challenge was part technical and part philosophical. What do I really want to archive? To start, I knew I didn’t care to archive my boosts/reblogs, so I can easily tune those out with the --exclude-reblogs flag. What about replies? Well I write a lot of (in my mind) great, well-thought-out replies, with info I’d love to hold on to and refer back to later. In fact, I’ve manually reverse-syndicated a lot of this kind of post in the past. So I knew I needed replies, just not all of them. The overwhelming majority of my reply posts are short little comments that when I thought about it, weren’t really anything I cared to bring back to my site. Especially in a format that is site-searchable and would certainly junk up other parts of the site (e.g. tags page, search results, RSS feeds, etc…)

I knew I would need to clean up any mass-export of posts that included replies, so to start I just created the full archive to see how many posts there were in total. The result was over 1000 and it became clear that I wasn't going to manually review each of those to see what was worth keeping. I needed a new approach. So, I decided to instead bring down just posts that I had marked public. More recently, when I post on Mastodon I’ve given more thought to whether that post should be marked as ‘public’ or ‘quiet public’ (i.e. ‘unlisted’). This foresight would pay off now as I wanted to only bring over a select few things that I felt were worthy of being public/exposed on my site. The problem is, I haven’t always been this mindful about what visibilty setting I post under. But it would have to do for now. So, how many posts did I have that were in fact public? Creating the filtered archive yielded only a few hundred posts - much more manageable to manually review. The compromise now was that maybe I’d miss a good reply that I had marked as unlisted some time ago, but I’ve done a decent enough job manually syndicating things I thought were worth keeping for a good while now so I’m OK if maybe I missed something.

Below are the flags I used to create my complete post archive of public toots (included replies).

go run main.go \
--user=https://shellsharks.social/@shellsharks \
--dist=./[OUTPUT FOLDER] \
--exclude-reblogs \
--filename='{{.Post.CreatedAt | date "2006-01-02"}}-shellsharks.social-{{.Post.Id}}.md' \
--porcelain \
--persist-last=./last \
--max-id=$(test -f ./last && cat ./last || echo "") \
--visibility=public

After clicking through each of the exported posts, I whittled the list down from 200-ish to about 50 posts. Not bad! Though it makes you wonder how important/worth it all of this effort is if I’m only interested in saving 50 things from nearly a year’s worth of tootin’. But, this last year I have also done a lot of manual reverse-syndicating which softened how many I needed to import now. 🤷‍♂️

Moving forward, I’ll have to be thoughtful about what I mark as unlisted vs. what I mark as public. Anything public will come to my site.

This is what my command looks like to import just the latest public posts…

go run main.go \
--user=https://shellsharks.social/@shellsharks \
--dist=/[DESTINATION DIR] \
--exclude-reblogs \
--filename='{{.Post.CreatedAt | date "2006-01-02"}}-shellsharks.social-{{.Post.Id}}.md' \
--porcelain --persist-first=./first --since-id=$(test -f ./first && cat ./first || echo "") \
--visibility=public

Notes

The second question was, where should these auto-syndicated posts live? In the original plan for my site, the Notes section was meant to house microblogs / social media posts, but I wasn’t sure I really wanted these auto-syndicated toots to junk up that timeline. In practice, the way I’ve used the notes feed has been for content I thought was “lower quality” than what was in my posts feed (e.g. shorter-form, less-researched, etc…). In hindsight, this was the wrong way to think about the notes feed. Over time, this approach resulted in me publishing a lot of things as Notes that should have just been Posts all along. This meant that my Notes feed had become HIGHER quality than I had intended it to be. So, rather than create yet another feed for these toots, I decided to revert back to the original, correct mode of thinking and house these toots as Notes on my site. Moving forward I plan to be less stingy about what I publish as a ‘Post’ and much less precious about what gets ‘Note’ status. If there was anything ‘lower quality’ than that, it probably doesn’t need to exist on my site.

It’s also worth mentioning that my notes layout was built with a social media post design in mind from the beginning. So, it definitely made sense in the end to just bring these toots in as notes and have them live directly within my notebook feed.

shellsharks
@shellsharks

3/22/24 23:31

Alright fedi’, spit a ‘verse, drop some knowledge.

Ivory for iOS

Syndication:

This said, they were’nt given full rights and visibility across the blog (at least not for now), as I’ll explain later…

Front Matter

Notes on my site have their own unique layout and some specific front matter metadata. To make this whole effort worth it, I needed the script to auto-populate as much of that metadata as possible. Thankfully, Gabriel solutioned for this…

This script supports a templating construct (located here /mastodon-markdown-archive/files/templates) which allows you to customize front matter. It will convert hashtags to jekyll tags, populate created dates, author names, etc… This resource shows you some of the variables/data types you can work with from the .json export. Notably, I used the “Account” and “Post” types to further enrich my post front matter. Below I show some of the more relevant tweaks to the default post.tmpl file…

layout: note
title: shellsharks.social {{.Post.CreatedAt | date "1/2/06 15:04 MST"}}
author: {{ .Post.Account.DisplayName }}
syndication: auto
syndicate-to:
- name: Mastodon
  url: {{ .Post.URI }}
  icon: ph ph-mastodon-logo
{{- if .Post.Application}}
posted-from: {{ .Post.Application.Name }}
{{- end}}

Customizing the date structure is super easy thanks to gomplate, and it’s nice that I can import the ‘Application’ used to publish the post and have that represented in my notes front matter metadata.

Site Tweaks

To make this all work correctly I had to tweak a few things in my existing layouts and consider how this type of content would be fed into the various streams and feeds across the site.

First, I excluded anything auto-syndicated from going into my RSS feeds. If you want to follow me on social media, you can do that, you can even subscribe to those RSS feeds directly. But I figured folks who subscribed to my blogs RSS didn’t need to have my exact social media posts fed into their RSS readers as well.

Second, a lot of these PESOS’ed toots do not have any hashtags, and thus do not come over with any tag front-matter. So I had to add a bit of logic on my tags page to make sure tagless posts didn’t show up in the list.

Third, I added some additional logic to my activity streams on my home page to not show auto-syndicated toots. They will show up in my “Infosec-Only” stream and in the “Latest Note” card however.

For all of this logic to work however, I added a flag in the front matter for these notes - syndication: auto. If I want to have these notes show up in my feeds/streams later, I can easily remove that flag and regenerate the site.

Overall though, my site handled the addition of these notes pretty well - with minimal re-engineering 😄.

Issues and the Future

I’m happy with the v1 of this capability, I think it will save me a lot of time and bring in content I never had the time to import/archive in the past. But, it isn’t without some issues, and there’s a lot I’d like to improve on into the future.

Notes are brought in with no title, and reply posts are brought in without the OP context. I might take time to retroactively go back and add this information in. Since I’m being pretty selective about what gets brought over, this shouldn’t be that big of a task.
This script solves for my Mastodon posts, but there’s a lot of other places I’d like to PESOS in a similar way (e.g. GoToSocial, Pixelfed, Bluesky, Reddit, Lemmy, etc…). Notably, this script does not work for GoToSocial or Pixelfed, so I’ll either need to tweak it myself, find a new solution, or whip up some script of my own to do it. Until then, I will continue to manually reverse-syndicate things I think are worth it.
For now, I am running this script manually, rather than having it auto-run as a GitHub action or cronjob on my local machine. In the future, I may want to automate it fully. If I do that, I’d like to find a way to auto update my changelog as well to reflect new imported notes.
Finally, I’ve considered making a separate feed that truly mirrors my Fediverse feed, importing all posts. This feed would be entirely isolated from my home page streams, search, tags, RSS feeds, etc… It would literally just be a mirror of my Mastodon toots. A project for another day…

Resources

Site Search

mike@shellsharks.com (Mike) — Tue, 04 Mar 2025 14:02:00 -0500

I have a fair bit of content on my site. I’ve been writing for over 5 years and at the time of this log have ~326 individual posts. My site is, and has always been, first and foremost a reference for myself. To be useful, to actually find stuff across all these posts, I need some sort of search capability. Here’s a brief history of the search capability on shellsharks.com and what I’d like to see search on this site do in the future…

Classic Search

When I first started the site, I picked a Jekyll theme that had already implemented search (super-search to be specific). Super search worked well enough, but in time I ran into some issues with it (which I honestly don’t remember what they were) and needed to find a new search solution. I liked super search because it displayed results dynamically as I typed my search query and it was decently fast/performant. From here, I went to Lunr.

Modern Search

The modern search capability on my site uses Lunr.js. It was easy enough to get started with, static-site-generator-compatible, and was easily tunable to search across all my different collection types. In practice, it works ok. It’s not “dynamic” in the same way that super search was, and it’s a bit clunkier given that I have it on a dedicated search page and not in-line across the site, but it does a decent job surfacing what I am looking for using a BM25-based scoring system. Lunr supports wildcards, field-level search, search term boosting, fuzzy matches, and logical ANDs. It also has some customization and plugin capabilties, but I haven’t really toyed around with that (yet). All this said, it’s not perfect. There’s still a few things that my perfect vision of search would be able to do…

The only thing I’ve really tinkered with related to Lunr is how I am constructing my page index. Below is the (very ugly) code that I have on my search page for creating the index. Notably, it specifies which pages are excluded from the index and then what front matter and body content is included across each collection type.

Creating the Lunr Search Index

{% assign counter = 0 %}
var documents = [{% for page in site.pages %}{% if page.url contains '.xml' or page.url contains 'assets' or page.url contains '.json' or page.url contains '.xsl' or page.title contains '- page' or page.url contains '/page/' or page.tags contains 'nosearch' %}{% else %}{
    "id": {{ counter }},
    "url": "{{ site.url }}{{ page.url }}",
    "title": "{{ page.title }}",
    "body": "{{ page.content | markdownify | replace: '.', '. ' | replace: '</h2>', ': ' | replace: '</h3>', ': ' | replace: '</h4>', ': ' | replace: '</p>', ' ' | strip_html | strip_newlines | replace: '  ', ' ' | replace: '"', ' ' }}"{% assign counter = counter | plus: 1 %}
    }, {% endif %}{% endfor %}{% for page in site.without-plugin %}{
    "id": {{ counter }},
    "url": "{{ site.url }}{{ page.url }}",
    "title": "{{ page.title }}",
    "body": "{{ page.content | markdownify | replace: '.', '. ' | replace: '</h2>', ': ' | replace: '</h3>', ': ' | replace: '</h4>', ': ' | replace: '</p>', ' ' | strip_html | strip_newlines | replace: '  ', ' ' | replace: '"', ' ' }}"{% assign counter = counter | plus: 1 %}
    }, {% endfor %}{% for page in site.posts %}{
    "id": {{ counter }},
    "url": "{{ site.url }}{{ page.url }}",
    "title": "{{ page.title }}",
    "body": "{{ page.date | date: "%Y/%m/%d" }} - {{ page.content | markdownify | replace: '.', '. ' | replace: '</h2>', ': ' | replace: '</h3>', ': ' | replace: '</h4>', ': ' | replace: '</p>', ' ' | strip_html | strip_newlines | replace: '  ', ' ' | replace: '"', ' ' }}"{% assign counter = counter | plus: 1 %}
    }, {% endfor %}{% for page in site.notes %}{% if page.tags contains 'nosearch' %}{% else %}{
    "id": {{ counter }},
    "url": "{{ site.url }}{{ page.url }}",
    "title": "{{ page.title }}",
    "body": "{{ page.date | date: "%Y/%m/%d" }} - {{ page.content | markdownify | replace: '.', '. ' | replace: '</h2>', ': ' | replace: '</h3>', ': ' | replace: '</h4>', ': ' | replace: '</p>', ' ' | strip_html | strip_newlines | replace: '  ', ' ' | replace: '"', ' ' }}"{% assign counter = counter | plus: 1 %}
    }, {% endif %}{% endfor %}{% for page in site.captain_logs %}{
    "id": {{ counter }},
    "url": "{{ site.url }}{{ page.url }}",
    "title": "{{ page.title }}",
    "body": "{{ page.date | date: "%Y/%m/%d" }} - {{ page.content | markdownify | replace: '.', '. ' | replace: '</h2>', ': ' | replace: '</h3>', ': ' | replace: '</h4>', ': ' | replace: '</p>', ' ' | strip_html | strip_newlines | replace: '  ', ' ' | replace: '"', ' ' }}"{% assign counter = counter | plus: 1 %}
    }, {% endfor %}{% for page in site.scrolls %}{
    "id": {{ counter }},
    "url": "{{ site.url }}{{ page.url }}",
    "title": "{{ page.title }}",
    "body": "{{ page.date | date: "%Y/%m/%d" }} - {{ page.content | markdownify | replace: '.', '. ' | replace: '</h2>', ': ' | replace: '</h3>', ': ' | replace: '</h4>', ': ' | replace: '</p>', ' ' | strip_html | strip_newlines | replace: '  ', ' ' | replace: '"', ' ' }}"{% assign counter = counter | plus: 1 %}
}, {% endfor %}{% for page in site.links %}{% if page.tags contains 'nosearch' %}{% else %}{
    "id": {{ counter }},
    "url": "{{ page.link }}",
    "title": "{{ page.title }}",
    "body": "{{ page.date | date: "%Y/%m/%d" }} - {{ page.content | markdownify | replace: '.', '. ' | replace: '</h2>', ': ' | replace: '</h3>', ': ' | replace: '</h4>', ': ' | replace: '</p>', ' ' | strip_html | strip_newlines | replace: '  ', ' ' | replace: '"', ' ' }}"{% assign counter = counter | plus: 1 %}
    }, {% endif %}{% endfor %}{% for page in site.devlogs %}{
    "id": {{ counter }},
    "url": "{{ site.url }}{{ page.url }}",
    "title": "{{ page.title }}",
    "body": "{{ page.date | date: "%Y/%m/%d" }} - {{ page.content | markdownify | replace: '.', '. ' | replace: '</h2>', ': ' | replace: '</h3>', ': ' | replace: '</h4>', ': ' | replace: '</p>', ' ' | strip_html | strip_newlines | replace: '  ', ' ' | replace: '"', ' ' }}"{% assign counter = counter | plus: 1 %}
    }{% if forloop.last %}{% else %}, {% endif %}{% endfor %}];

Web Search

I think having a native search capability on your site is very important, but I can’t dismiss the potential value of a traditional web search. Look, Google and other web search providers aren’t what they used to be, that’s undeniable. But, you can go on Google right now and do a good ol’ fashioned “site:shellsharks.com” search and pull back actual results from my site. So yeah, in a pinch, if your site is indexed by Google, or other search engines, you can fall back on that for search.

Next-Generation Search

Alright, let me chat a bit about what I’d like to see in future versions of my sites search capability. I’ve got a wishlist below actually…

Search Wish List

Searches across all pages of my site, but customizable so I can limit based on front matter (e.g. tag), or collection type (e.g. link)
Performant
Regex-capable
Supports boolean logic (i.e. AND, OR, NOT, etc…)
Can be put in-line in the header, rather than having to load into the separate /search page
Dynamically loads results (you don’t have to “submit” the queries) as you enter search terms
Search results return not only the page which matches the search term, but also a snippet from that page with the terms highlighted
The ability to filter results based on a number of criteria (e.g. date, collection, tag, etc…)
No server-side requirement (preferably)

Yep, that’s it. Put search on your site!!

Build Then Smile

mike@shellsharks.com (Mike) — Sun, 23 Feb 2025 00:43:00 -0500

Having a personal website is incredibly rewarding. It’s not always easy, but that’s what makes it all the more satisfying - seeing what you’ve worked so hard on, what you yourself have built, come to life on the web. Here’s a list of the things I am most proud of on this site.

(Listed kinda chronologically, in the order it was added to the site.)

The Artwork
Designer Vulnerabilities
The Enchiridion of Impetus Exemplar
Hamburger Menu
Theme Toggle
Activity Feed
Note Card
Style Page
Scrolls
Home Page (circa 2025)
Shark Fin <hr>

The Artwork

I LOVE the artwork on this site. Some of it was made by yours truly, but there’s many things that were designed by others!

I can take credit for the main logo and related doodles, the blinking SHELLSHARKS >_ title logo, and The Shellsharks Podcast logo. Finally, I made the li’l shark shiver you see at the bottom of most pages.

Past that, everything else I’ve gotta shout out others for…

angryrolypoly is a long-time friend, a super gifted artist, and an awesome person! He’s also responsible for a lot of lovable characters hanging out around the site…

Finally, thanks to Iwona Skiba, who whipped up my PRO logo.

Designer Vulnerabilities

There are two ideas which form the genesis of this site. First, I wanted to thoroughly respond to everyone who was asking me (back in 2019) “how to get into infosec”, and second, I wanted to create a running list of all named / “Designer” vulnerabilities. These of course were posts one and two respectively on the site. Nearly 6 years later, I’m still keeping the designer vulns list up-to-date, and am closing in on ~600 named vulns. Wow!

The Enchiridion of Impetus Exemplar

I wish I remembered if there was a specific reason why I decided to build the monumental Enchiridion of Impetus Exemplar, but alas, if there was one, it is lost to time. What I can say is that I put an incredible amount of time into researching and writing that piece. It’s also one of, if not the post I personally reference the most. I get a lot of great feedback on it too, and is the post I think I am most proud of.

I have plans to continue expanding it too, but like other posts I’ve had grand-addition-plans for, it just hasn’t happpened yet.

Implementing the aptly named “hamburger menu” was (in my memory) a real pain. I’m also confident that I’ve committed a vast array of HTML, CSS and JavaScript crimes in order to get what you see today. But, if it works, it works right?

Here’s my menu.html code with all the hamburger-iness in it. (As you can see, I got the code from Erik, but it seems I’ve lost the link.)

<style>
    /*
 * Made by Erik Terwan
 * 24th of November 2015
 * MIT License
 *
 *
 * If you are thinking of using this in
 * production code, beware of the browser
 * prefixes.
 */

#menuToggle
{
  display: block;
  position: relative;
  
  z-index: 1;
  
  -webkit-user-select: none;
  user-select: none;
}

#menuToggle a
{
  text-decoration: none;  
  transition: color 0.3s ease;
  color: var(--contrast-font-color);
}

.menu_section {
  color: var(--light-font-color);
  font-weight: 900;
}

.menu_section:nth-of-type(n+2) {
    margin-top:20px;
  }

#menuToggle a:hover
{
  color: var(--link-hover-color);
}

#menuToggle input
{
  display: block;
  width: 40px;
  height: 32px;
  position: absolute;
  /*top: -7px;*/
  /*left: -5px;*/
  
  cursor: pointer;
  
  opacity: 0; /* hide this */
  z-index: 2; /* and place it over the hamburger */
  
  -webkit-touch-callout: none;
}

/*
 * Just a quick hamburger
 */
#menuToggle span
{
  display: block;
  width: 27px;
  height: 3px;
  margin-bottom: 4px;
  position: relative;
  margin-top:4px;
  
  background: var(--font-color);
  border-radius: 3px;
  
  z-index: 1;
  
  transform-origin: 4px 0px;
  
  transition: transform 0.5s cubic-bezier(0.77,0.2,0.05,1.0),
              background 0.5s cubic-bezier(0.77,0.2,0.05,1.0),
              opacity 0.55s ease;
}

#menuToggle span:first-child
{
  transform-origin: 0% 0%;
}

#menuToggle span:nth-last-child(2)
{
  transform-origin: 0% 100%;
}

/* 
 * Transform all the slices of hamburger
 * into a crossmark.
 */
#menuToggle input:checked ~ span
{
  opacity: 1;
  transform: rotate(45deg) translate(-2px, -1px);
  background: var(--link-hover-color);
}

/*
 * But let's hide the middle one.
 */
#menuToggle input:checked ~ span:nth-last-child(3)
{
  opacity: 0;
  transform: rotate(0deg) scale(0.2, 0.2);
}

/*
 * Ohyeah and the last one should go the other direction
 */
#menuToggle input:checked ~ span:nth-last-child(2)
{
  transform: rotate(-45deg) translate(0, -1px);
}

/*
 * Make this absolute positioned
 * at the top left of the screen
 */
#menu
{
  position: absolute;
  left:-10px;
  width: 200px; /*fit-content;*/
  padding: 10px;
  margin-top:10px;
  /*display:none;*/
  background: var(--light-background-color);
  color:var(--font-color);
  list-style-type: none;
  -webkit-font-smoothing: antialiased;
  max-height: calc(80vh);
  overflow:auto;
  overscroll-behavior: contain;
  border-radius: 5px;
  /* to stop flickering of text in safari */
}
/*
 * And let's slide it in from the left
 */
#menuToggle input:checked ~ ul
{
  display:block;
}
.hidden {
  display: none;
}
</style>

<div role="navigation" id="hamburger">
  <div id="menuToggle">
    <input type="checkbox" />
    <span></span>
    <span></span>
    <span></span>
    <ul id="menu" class="hidden">
      {% include nav-links.html %}
      <li><img src="/assets/img/avatar.png" height="50" style="position: relative; display: block; margin:auto; margin-top:20px; margin-bottom:20px;" /></li>
    </ul>
  </div>
</div>

Also in menu.html is the following JavaScript code which has the click & toggling-related event listeners.

const menuButton = document.getElementById('menuToggle');
const menu = document.getElementById('menu');
var links = menu.querySelectorAll('a');

menuButton.addEventListener('click', () => {
  if (!menu.contains(event.target)) {
    menu.classList.toggle('hidden');
  }
});

document.addEventListener('click', (event) => {
  if (!menu.contains(event.target) && !menuButton.contains(event.target)) {
    menu.classList.add('hidden');
    if (document.getElementById("menuToggle").children[0].checked) {
      document.getElementById("menuToggle").children[0].checked = !document.getElementById("menuToggle").children[0].checked;
    }
  }
});

links.forEach(function(link) {
  link.addEventListener('click', function(event) {
    document.querySelector("#hamburger").click();
  });
});

Next, nav-links.html (included in menu.html) loops through a data array in my _config.yml file converting said data into the list of items you see in the menu!

<li class="menu_section">Main</li>
{% for link in site.mainlinks %}
    <li><a href="{{ link.link }}" {{ link.target }}><i class="{{ link.icon }}"></i> {{link.name}}</a></li>
{% endfor %}
<li id="themetoggler"><i class="ph ph-swatches" id="themetoggle"></i> Toggle theme</li>
<li class="menu_section">Site Nav</li>
{% for link in site.sitelinks %}
    <li><a href="{{ link.link }}" {{ link.target }}><i class="{{ link.icon }}"></i> {{link.name}}</a></li>
{% endfor %}
<li class="menu_section">Other</li>
{% for link in site.otherlinks %}
    <li><a href="{{ link.link }}" {{ link.target }}><i class="{{ link.icon }}"></i> {{link.name}}</a></li>
{% endfor %}

But before that, nav.html (which calls nav-links.html) is called from my page layout.

<ul id="nav_menu" style="list-style-type:none;padding-left: 10px;">
    {% include nav-links.html %}
</ul>

E-z-p-z right?

Theme Toggle

I prefer a dark theme, but not necessarily the super-contrasty dark mode that you sometimes see. Others may prefer that, or maybe they’re a sicko light-mode type of person. Y’know I try not to judge. WIth this in mind, I wanted to create a theme toggle switcher that could iterate over three distinct themes. In my case, dark, light, and classic. The “classic” theme is basically the (dark-mode-ish) color scheme that my site has been rocking since ~2021. You can see the current color palettes for each theme on my Style page.

So, how did I achieve the 3-mode theme switcher? It took some googlin’ around, and sifting through a lot of results that were for 2-mode implementations, which seemed to always employ a hidden HTML check box, but I eventually found my solution.

A sanitized (I took the colors out, you can look at them on my Style page) version of my CSS code relevant to the theme switcher toggle is below.

:root {
  --accent-color: #CA3342;
  /* OTHER COLORS */
}

/* themes */
[data-theme="dark"] {
  --accent-color: #FA7575;
  /* OTHER COLORS */
}

[data-theme="light"] {
  --accent-color: #96000f;
  /* OTHER COLORS */
}

[data-theme="classic"] {
  --accent-color: #FA7575;
  /* OTHER COLORS */
}

Then, there’s some JavaScript code which does the switching when you press the Toggle theme button (located in the Hamburger menu).

function switchTheme(e) {
    if (document.documentElement.getAttribute('data-theme') == 'dark') {
      document.documentElement.setAttribute('data-theme', 'light');
      localStorage.setItem('theme', 'light');
      document.getElementById('themetoggle').setAttribute("class", "ph ph-moon");
    }
    else if (document.documentElement.getAttribute('data-theme') == 'light') {
      document.documentElement.setAttribute('data-theme', 'classic');
      localStorage.setItem('theme', 'classic');
      document.getElementById('themetoggle').setAttribute("class", "ph-fill ph-moon");
    }
    else if (document.documentElement.getAttribute('data-theme') == 'classic') {
      document.documentElement.setAttribute('data-theme', 'dark');
      localStorage.setItem('theme', 'dark');
      document.getElementById('themetoggle').setAttribute("class", "ph ph-sun");
    }
    else {
      document.documentElement.setAttribute('data-theme', 'dark');
      localStorage.setItem('theme', 'dark');
      document.getElementById('themetoggle').setAttribute("class", "ph ph-sun");
    } 
}

toggleSwitch.addEventListener('click', switchTheme, false);

The final piece of this theme-switching puzzle is the code below which resides on each page. I’ve added it to the default.html layout in the ‘_layouts’ directory of my Jekyll site. Basically, it gets and sets the theme in a browsers localStorage. It also uses the prefers-color-scheme directive to take advantage of users preferred dark vs light mode setting on their device(s). Cool!

  <script>
  const currentThemeX = localStorage.getItem('theme') ? localStorage.getItem('theme') : null;

  if (currentThemeX) {
    document.documentElement.setAttribute('data-theme', currentThemeX);
  }
  else if (matchMedia('(prefers-color-scheme: light)').matches) {
    localStorage.setItem('theme', "light");
  }
  else if (matchMedia('(prefers-color-scheme: dark)').matches) {
    localStorage.setItem('theme', "classic");
  }
  else {
    localStorage.setItem('theme', "classic");
  }
  </script>

Activity Feed

I’ve previously discussed how I built the Activity Feed, and where I got the inspiration. It’s just a really fun way to visualize everything I am writing and sharing, chronologically weaved together.

Note Card

The “Notebook” is where I file away short-form-style content (“notes”), including PESOS‘ed social media posts. After creating notes as a unique collection type, with a theme reminiscent of a social media post, I had the idea to create a capability to “embed” a note in another post, similar to how other social networks have embed code. The result is below…

Mike Sass
@shellsharks

11/17/22 08:11

“If you find yourself alone, riding in green fields with the sun on your face, do not be troubled. For you are on Mastodon, and not on Twitter!” - Mastodonius Decimus Meridius

#Gladiator is the best movie of all time. I can’t be convinced otherwise.

Metatext

Syndication:

#life #movies

Here’s the Liquid code I use to embed a note.

{% assign note = site.notes | where:"slug","Gladiator" | first %}
{% assign note_type = note.syndicate-to.last.name | downcase | remove: '.' %}
{% if note_type == '' %}{% assign note_type = "none" %}{% endif %}
{% include note-card.html %}

The “note card” (as I call it) is just a Jekyll include with markup that is effectively the same as the note layout markup. (You can see the HTML/CSS structure by viewing source on the div id = ‘ncard’.)

Style Page

The Style page is just a cool, relatively unique addition to this site’s abundance of neat pages. What’s more, it is actually pretty helpful when I’m tinkering with the CSS or other design aspects of the site. This post from Patrick Weaver was fundamental in the development of my Style page.

* All credit for this idea thought to fLaMEd 🔥 (check out their Style Guide).

Scrolls

A newsletter is an idea I had had for a while before launching the first edition of Scrolls. You see, week after week I spend a good bit of time scrolling a lot of different feeds. In doing so, I come across a lot of cool stuff. Things that I save, some stuff I may share, things that I end up writing about, etc… I realized that I was putting quite a bit of work into this, and what I was producing as a result of all that work, was so little. So, my idea was to convert, with really not that much more added effort, all the work I was doing by reading through and saving cool stuff across my feeds into something for everyone.

Arcane curation from the IndieWeb, Fediverse and Cybersecurity realms

This is a project I’m very excited about. I’ve always said that security is magic. I also believe in the magic of the IndieWeb and of the Fediverse. Scrolls is centered around these three distinct topics, which is why it’s been imbued with a kindred dollop of magic and whimsy.

Home Page (circa 2025)

I write about my home page revamp here. The home page has gone through (at least) 4 major revisions since 2019, when I first started the site.

I had major reservations about moving away from the classic, simple, clean, chronological list-of-posts aesthetic that I had been rocking since the beginning. But it only took a few minutes for me to realize not only how much more utility the new design had, but also how much better it did in telling folks what this site is about, what it has to offer, and what matters to me. I also think it looks awesome!

Shark Fin <hr>

I talk all about how I built the shark fin <hr> here.

But why did I do this? Sure yeah, I like sharks. But it ain’t really that. It’s more my love for little whimsical touches. I love the idea of having little easter eggs sprinkled throughout the site. Things that will surprise and delight not only my “readers”, but more importantly, me. I spend a lot of time just browsing around the pages of shellsharks, and these little touches make the experience all the better.

So build cool things, and remember to look upon those things and smile.

Shark Fin <hr>

mike@shellsharks.com (Mike) — Thu, 20 Feb 2025 09:51:00 -0500

You may have noticed that I have a bit of a shark theme goin’ on across the site. It’s not overwhelmingly shark-ey, but there’s certainly a shark or two sprinkled about - and I think that’s just fun. To this end, I had another fun li’l idea. What if I could change the usual boring ‘ol <hr> tag (horizontal rule) and have a shark dorsal fin coming out of it? Sounds cool right? Right.

I had this idea months or even years ago, I filed it away for another day, thinking it too hard for me to accomplish myself. It would have to be something that I’d need to learn a lot of arcane HTML/CSS to do or maybe I’d just need to hire someone to make it for me. Yesterday, for whatever reason, I decided to try and take it on. I’m going to walk through a bit of my trial and error, and then get into how I finally pulled it off.

Trial and Error

Let me tell you, getting this to work probably took me 4-5 hours of just sittin’ in my chair, hammering away. Though I can safely say I mostly figured out everything to get it to work, I also can say I figured out lots of ways it doesn’t work.

The way I thought this would work originally, and thus the way I approached it at first, was to use HTML’s Canvas Graphics to draw a shark fin and a line, and just use that instead of the normal <hr> tags. Of course I know nothing about drawing with <canvas>, and I absolutely wasn’t going to try and learn it well enough to do it myself, so naturally I googled for an answer. It wasn’t long into this search that I realized maybe drawing with straight CSS would be a better option. So, I searched for that instead. Google came up pretty dry once again, but there was one potential splash of luck.¹ Alvaro had managed to draw a (adorably cute) shark entirely with HTML and CSS. Cool! But could I use it somehow? I cmd+C & cmd+V’ed the code and tried ripping out stuff to get to just the fin. I figured if I could isolate the fin, I could tweak it a bit to be what I wanted. I was wrong. I gave up on that after like 10 min.

So now what? I got a bit desperate, from there I tried…

Searching for web tools that would convert drawings to CSS code
Searching for vector libraries
I even used ChatGPT to try and make it (here’s what it came up with - sorry I can’t get the viewBox to behave)

Fresh off of humiliating myself by thinking AI could be useful, I came across some actually useful info. Basically, I learned that I could customize <hr> tags with a character, or image using the ::after pseudo-element.² Neat!. This seemed like a more elegant solution. I could still use <hr> tags, just with a class specifier rather than importing some janky inline-svg + html + css abomination each time I wanted the effect. So, like any seasoned developer, I borrowed the code from the stack overflow page and started tweaking from there. But then I ran into my next issue, I needed an image to import! And not just any image, I needed something I could move along the <hr> continuum, something I could size up and down, and something I could change the color of. First place I went to was .svg.

I spent some time googling around for shark fin .svgs and came across a number of things that would work for me.

The xml syntax within an SVG file is kinda strange, and it took me a while to grok, but eventually I figured out how to change the fill color, resize it to my liking and generate a mirror image so that the shark fin can point both left and right.

So, let me give you the final result…

Shark Fin <hr>

Here’s how I finally put together my current v1.0 Shark Fin <hr>

Within the SVG, you can resize by changing the ‘width’ property in the <svg> tag. You can change the fill color with the ‘fill’ property in the <path> tag. Finally, for mirroring the image across the Y-axis, you can add transform="scale (-1, 1)" transform-origin="center" to the <path> tag as well (as shown below). I also had to toy around with the viewBox to take out unneccessary white-space/padding.

<svg ... width="35px" viewBox="0 0 1000 1000" ...>
  <path fill="#CA3342" transform="scale (-1, 1)" transform-origin="center" ... />
</svg>

My CSS for the ‘fin’ class…

:root {
  --hrfin-position: 40%;
  --hrfin-content: url( '/assets/img/shark-fin-notch.svg' );
}
hr.fin {
  margin-top: 40px; /* compensating for height of the fin */
  margin-bottom: 40px; /* making the bottom margin the same as the top */
  border-top: 1px solid var(--accent-color); /* the color that I want the hr tag to be */
  border-bottom: 1px solid var(--accent-color);
}
hr.fin:after {
  content: var(--hrfin-content); /* Loading the SVG url from :root */
  left: var(--hrfin-position); /* Setting the position of the fin along the rule */
  position: relative;
  bottom:29px; /* Moves the fin closer to the line - it's 6px less than the svg width */
}

So why am I setting the ‘left’ position and loading the svg from :root instead of directly? Well that’s because I wanted to randomize the fin’s position along the rule on page load. So I have some JavaScript that does this.

const root = document.querySelector(":root"); //grabbing the root element
var rand = Math.floor(Math.random() * 90) + 1;
const fins = ["url( '/assets/img/shark-fin-notch.svg' )","url( '/assets/img/shark-fin-notch-reverse.svg' )"]
var fins_rand = Math.round(Math.random());
console.log(fins[fins_rand]);
root.style.setProperty("--hrfin-position", rand + "%");
root.style.setProperty("--hrfin-content", fins[fins_rand]);

So what do I get in the end? This! *cue the music*

OK, this rules. Try reloading the page a few times and see it change positions and directionality. Niiiiice!

What’s cool too is that even if I shorten the width of the rule, the shark will stay along it.

You can now call me the Poseidon (or Aquaman) of HTML, as I summon forth a shiver of <hr> sharks!

Future Improvements

But things aren’t exactly how I’d like to see them. There are some improvements to be made in future iterations. A wish list of things I’d like to see it do in the future…

Given the way I am loading the SVG, I can’t dynamically change the color of the fin, it is statically set in the SVG itself. I’m fine with the compromise for now but would like to address this later.
The fin position (X-axis), set by the CSS ‘left’ directive is the same for all fin-class hrs on the page. Notice how all of them on this page are at the same point on the line. It’d be cool to randomize the position for each instance of the rule on a single page.
I’m pretty happy with the shark fin SVG I’ve landed on (Thanks Creative Fabrica!), but could see myself getting something a bit more customized in the future.
If I wanted to get crazy, maybe I’d have the fins animate in some way, like an actual shark swimmin’ around the rules.
Another compromise was having to use JavaScript to randomize the svg file and position. Modern/supported versions of CSS don’t have any way to produce a random value. There are some hacky ways to achieve this, but I couldn’t figure them out. It’d be cool to have this not be .js-dependent in the future.
Suggested to me was the idea to have the ‘left’ position determined by scroll position, so the shark would look like it was swimming as one scrolled. Interesting idea!

Pagination Nation

mike@shellsharks.com (Mike) — Wed, 29 Jan 2025 11:48:00 -0500

In the last Devlog, I talked about Jekyll collections and how I’m using them. As your site grows older, and you write more and more things, across a variety of collections, your pages which list-out content become more and more unwieldy, thus necessitating things like pagination. I encountered this issue some time ago - notably, with my Notebook, Changelog & Activity pages, each having 100’s of entries respectively. When not paginated, this results in not only very long pages that require quite a bit of scrolling to navigate, but also yielded pages that were very ill-performant, especially on mobile. My iPhone would nearly freeze trying to load, render or navigate away from these huge pages. So how can I mitigate this? Pagination of course!

Pagination is great, but unfortunately, if you are using GitHub Pages and building/deploying via the classic Deploy-from-a-branch method, you are limited to the legacy jekyll-paginate plugin, which can only paginate on a single page within your site, specifically on the root level index.html page. Ouch. Since I need the ability to paginate a variety of collections on multiple distinct pages, I needed something else - enter jekyll-paginate-v2.

Jekyll-paginate-v2 seemed to satisfy my requirements, but unfortunately, vanilla GitHub Pages does not support many plugins, this being one of them. Honestly, at this point I flirted with the idea of re-writing my entire blog using something like 11ty. I still might do this one day, but really I just want my current site to work the way I want, without having to scrap it. So… the other solution is changing the way I build & deploy the site. Fortunately, GitHub gives you the option to switch from the classic Pages Deploy-from-a-branch method to one based on GitHub Actions. I’m not going to explain what Actions is, but in the context of this writeup, just know it lets me use the full suite of Jekyll plugins, not just the limited selection that GitHub Pages supports. Woo!

Configuring GitHub Actions for GitHub Pages Build & Deploy

Alright. So how can I switch from the classic build+deploy method to the Actions-based one? Jekyll actually has a doc for exactly this. The steps as written are very simple and very straight-forward, or so I thought…

After creating the new action, Pages tried to build my site but quickly ran into an error with the Ruby setup. The traceback ended as follows…

In Gemfile:
  github-pages was resolved to 209, which depends on
    jekyll-mentions was resolved to 1.6.0, which depends on
      html-pipeline was resolved to 2.14.0, which depends on
        nokogiri
Error: The process '/opt/hostedtoolcache/Ruby/3.1.6/x64/bin/bundle' failed with exit code 5

I’ll admit, I was pretty stumped at first, and didn’t really know how to troubleshoot. You see, even though I’ve been running this Jekyll site for over 5 years, I really haven’t learned much about Ruby, hah! Looks like that needed to change, so I persist. After browsing around, I started to home in on the root problem - it seemed like I had some dependency issues stemming from my Gemfile.lock and/or Gemfile files. Ok, nice! Let’s add Gemfile.lock to my .gitignore and then swap out gem 'github-pages' to gem "jekyll", "~> 4.2" in my Gemfile. Commit the repo and then about a minute later, a green check in my workflow record! It worked!

Update: Another troubleshooting thing to consider is whether the ruby-version in the jekyll.yml file is up-to-date.

Configuring Jekyll-Paginate-V2

OK, now that my site can successfully be built & deployed via GitHub Actions, I need to get the jekyll-paginate-v2 plugin enabled and setup. Ultimately, it’s pretty simple to get set up and surprisingly backwards-compatible (with the classic jekyll-paginate plugin), but there’s a few bugs and other little tidbits to know so you don’t pull your hair out…

Caching Bug

The most insidious bug with getting the Jekyll-Paginate-V2 plugin to work is the “caching bug”. This is described here - Resolve the Jekyll Paginate V2 Caching Bug. To fix, go to your Gemfile and replace gem 'jekyll-paginate-v2' to either…

gem 'jekyll-paginate-v2', git: 'https://github.com/mohkale/jekyll-paginate-v2.git', branch: 'liquid-cache-bypass'

gem 'jekyll-paginate-v2', git: 'https://github.com/jameshi16/jekyll-paginate-v2.git', branch: 'cache-mismatch-error'

Fixed!

Set indexpage & extension to nil

The second (much more minor) issue I encountered was with how the plugin wants to tack on ‘index.html’ as the default name for generated pages. This causes weird, often just unsightly issues with how the page urls look for paginated pages. You’ll get pages that look like ‘https://domain/paginatedpage/page/3/index.html’, instead of the cleaner ‘https://domain/paginatedpage/page/3’. You can fix this by going into your config.yml file and making sure indexpage and extension are set to nil (as shown below).

  # Optional, the default file extension for generated pages (e.g html, json, xml).
  # Internally this is set to html by default
  extension: 

  # Optional, the default name of the index file for generated pages (e.g. 'index.html')
  # Without file extension
  indexpage: 

Understanding the V2 Pagination Generator

The last consideration is less of a bug and more of just a need-to-know. From v1 to v2 pagination links and paginator object variables/methods are largely the same, so much of any existing pagination code/syntax you may have from using the classic jekyll-paginate plugin should continue to work. To enable pagination on other pages, specify the collection you want to load in via the pages front matter, and continue to use the paginator.posts directive (even though you might be using a non-‘post’ collection).

Here’s more information on the v2 Pagination Generator.

So at the end of the day, I figured it out! As a result, I’ve been able to paginate my Notes, my Activity page and my Changelog, while keeping my main page pagination of my blog posts the same. From here, I still want to add pagination for a few other, less-pressing pages, i.e. the Captain’s Log, Podcasts, Tags, Devlog and more!

Appendix

Pagination Links Code

If you want to replicate my paginator trail, the code I use for the links is provided below.

<!-- Pagination links -->

  {% if paginator.page_trail %}
  <ul class="pagination pagination-sm" style="display: flex; justify-content:center;">
    {% if paginator.previous_page %}
      <li><a href="{{ paginator.previous_page_path | prepend: site.baseurl | replace: '//', '/' }}">&laquo;</a></li>
      <li>&nbsp;<a href="/YOURPAGEHERE">First</a></li>&nbsp;&nbsp;
    {% else %}
      <li class="disabled"><span aria-hidden="true">&laquo;</span></li>
      <li class="disabled"><span aria-hidden="true">&nbsp;First</span></li>&nbsp;&nbsp;
    {% endif %}
    {% for trail in paginator.page_trail %}
      <li>
        {% if paginator.page == trail.num %}
          {{ trail.num }}
        {% else %}
          {% if trail.num == 1 %}
            <a href="/YOURPAGEHERE">{{ trail.num }}</a>
          {% else %}
            <a href="/YOURPAGEHERE/page/{{trail.num}}" title="{{trail.title}}">{{ trail.num }}</a>
          {% endif %}
        {% endif %}
      </li>
      &nbsp;&nbsp;
    {% endfor %}
    {% if paginator.next_page %}
      <li><a href="/YOURPAGEHEREy/page/{{ paginator.total_pages }}/">Last</a> ({{paginator.last_page}})&nbsp;</li>
      <li><a href="{{ paginator.next_page_path | prepend: site.baseurl | replace: '//', '/' }}">&raquo;</a></li>
    {% else %}
      <li class="disabled"><span aria-hidden="true">Last&nbsp;</span></li>
      <li class="disabled"><span aria-hidden="true">&raquo;</span></li>
    {% endif %}
  </ul>
  {% endif %}

Collection all the things!

mike@shellsharks.com (Mike) — Tue, 16 Apr 2024 12:23:00 -0400

This site is built using Jekyll, and one of Jekyll’s (and other SSGs I’m sure) most powerful features is Collections - used to group related content together. When I was building the Activity log page recently, I was looking for ways to pull in content from around the site to feature in that timeline. I already had posts, notes and logs in their respective collections but changes and podcasts existed in singular page files, making it more difficult to pull individual records out without using some wacky JS/jQuery. It was then I had the idea to convert these monolithic pages, breaking them out into more atomic collection items. So that’s what I did!

For changes, I’ve decided to go with a “change collection item” being 1 week in length, with a file for each week. For podcasts, each podcast has its own record file and for now those files simply redirect to the Podbean permalink page where it is hosted. But! since I have the full-text shownotes in each file, I can programmatically loop through each podcast collection item and populate the main Podcast page with a bulleted list of show descriptions, much like I’ve always had, but now it is no longer statically typed. Woo! Similarly for changes, the Changelog still has some legacy changes listed in monolithic format (i.e. a gigantic list of bulleted sections), but for all changes in 2024+, they are programatically pulled in from the changes collection and populated much the same way they’ve always been right inside the main Changelog page. Nice!

My takeaway here is to consider in the future (and now looking back) what repeated/similar content would make sense to exist as a collection rather than a single, giant file. I haven’t pored through everything in my site to see if there’s any worthy candidates for additional conversion yet but eventually I will. Collections give you the ability to do multiple things with the same set of data. As I’ve seen with both changes & podcasts, I can now populate both their landing pages as well as the Activity feed with minimal additional effort.

Devlog 1: initialization

mike@shellsharks.com (Mike) — Wed, 10 Apr 2024 09:33:00 -0400

As I introduced here, this is a new content series for the site dedicated to discussing/sharing code, how-to’s, resources and more - specific to how I am building this site and related Shellsharks properties (i.e. podcast, Fediverse, etc…)

shellsharks Devlogs

RSScaping

RSS XML File

RSS XSL File

“Shark” Namespace

Ongoing RSS Validation Issues

The Changelog

Mastodon Auto-PESOS

Mastodon markdown archive

Planning and Mechanics

What to Archive?

Notes

Front Matter

Site Tweaks

Issues and the Future

Resources

Site Search

Classic Search

Modern Search

Creating the Lunr Search Index

Web Search

Next-Generation Search

Search Wish List

Build Then Smile

The Artwork

Designer Vulnerabilities

The Enchiridion of Impetus Exemplar

Hamburger Menu

Theme Toggle

Activity Feed

Note Card

Style Page

Scrolls

Home Page (circa 2025)

Shark Fin <hr>

Shark Fin <hr>

Trial and Error

Shark Fin <hr>

Future Improvements

Pagination Nation

Configuring GitHub Actions for GitHub Pages Build & Deploy

Configuring Jekyll-Paginate-V2

Caching Bug

Set indexpage & extension to nil

Understanding the V2 Pagination Generator

Appendix

Pagination Links Code

Collection all the things!

Devlog 1: initialization