Scratch – template

Posted
25 April 2025

I’ve made a start making a fresh NetNewsWire theme. My plan is to build it incrementally, blogging the process and releasing versions as I go.

Template variables

The first step was to poke around the NetNewsWire source code and default themes to discover what template variables NetNewsWire provides. To document these, and to make it easy to see how different feeds and posts populate them, I built the Template variables theme.

Minimum viable template.html

NetNewsWire bakes in some CSS and JavaScript applied to article content alongside what a theme provides. The first task was to establish what was required of template.html to support baked in features.

I’m pleased to say, aside from the template variables themselves, there’s not much:

  1. A div with a class of articleBody wrapping the article content:

    <div class="articleBody">[[body]]</div>

    This must be a div as there is a div.articleBody selector within the iOS JavaScript that applies some pre-processing of article content.

  2. The feed favicon must have an id of nnwImageIcon

    <img id="nnwImageIcon" src="[[avatar_src]]" height="48" width="48" alt>

    The id is used to update the image src and also to attach an onclick to open feed options from the article view on iOS.

    Note I have added an alt attribute too to suppress a superfluous “image” announcement in VoiceOver. We could add the name of the feed here using [[feed_link_title]], but since we already have the feed link alongside this image, doing so would not add anything useful.

The baked in stylesheet includes some base styling applied to several other classes included in the default theme HTML. I’ve chosen to avoid these to minimise specificity that might be needed to override them in my theme CSS.

Base HTML landmarks

It is a semantically appropriate norm for themes to wrap the feed title and icon in a header element. Extending on the expectations of an accessible web page, I’ve wrapped the remainder of the content in a <main>.

I remain curious as to whether these landmarks provide a practical accessibility benefit within the context of the NetNewsWire article view. Please let me know if you are a regular VoiceOver user, I’m very interested in your experience. My contact details are at the bottom of this page.

Missing post titles vs h1

It is also normal and expected to place the post title in a h1 heading. The issue with this, in the context of a feed reader, is some feeds don’t title all posts.

To avoid the inconsistency of an empty or missing h1, I’ve added the date in the h1 alongside the title. Using CSS in stylesheet.css this fallback is only displayed when the title is absent. The same trick is used to display only the time in the date stamp slot when the date is used as a title.

The template

Here’s the template in full. I’m not anticipating much further change will be necessary to theme it:

<header class="[[text_size_class]]">
	<img id="nnwImageIcon" src="[[avatar_src]]" height="48" width="48" alt >
	<h2><a href="[[feed_link]]">[[feed_link_title]]</a></h2>
	<p class="byline">[[byline]]</p>
</header>
<main class="[[text_size_class]]">
	<hgroup class="[[dateline_style]]">
		<h1><a href="[[preferred_link]]"><span>[[title]]</span><span>[[date_medium]]</span></a></h1>
		<p><span>[[datetime_medium]]</span><span>[[time_short]]</span></p>
	</hgroup>
	<div class="articleBody">[[body]]</div>
	<hr>
	<p class="external-link">[[external_link_label]] <a href="[[external_link]]">[[external_link_stripped]]</a></p>
</main>

The CSS to switch around which span is displayed:

hgroup span + span {
	display: none;
}

hgroup:has(span:empty) span {
	display: none;
}

hgroup:has(span:empty) span + span {
	display: inline;
}

Install

To enable a quick switch between different versions of this theme I’ve generated a zip of each version – incorporating the version number in the name:

Get the latest version on the Scratch project page.

Next up

The next task, and the next version of the theme, will be to make the font size configurable.