Designing HTML for Safari Reader Mode

For whatever reason, Apple doesn’t provide any guidance on how to design for Safari Reader Mode . Maybe they want the right to change it at any time or maybe it’s to prevent abuse and advertising sneaking in. Likewise, it’s near impossible to find any third-party guidance on how to structure your HTML. It’s mostly guessing, checking reader mode, editing HTML, reloading until it works. But after looking at the Reader javascript source code, and a lot of View Source on numerous publications, I’ve come up with some rules on how to structure HTML to optimize for Reader. There are no doubt many alternative rules and layouts, but this seems to work.

Structure the main content

The main content (include the headline and other content) should be in a single <main> tag. Other tags like <article> also work. The article should be text-heavy. If there are too many links, lists, or other non-text items, Reader might not trigger. Conversely, if the HTML node immediately prior to the article node is text-heavy it might bleed into the main article.

Structure the title

The title of the article should be a <h1> immediately after the <main> tag.

Structure the subtitle

Put the subtitle or a short description as a <div> under the <h1> tag.

Update 2018-05-01: It appears the subtitle has a maximum length of under 200 character. If it exceeds this value, it’s just treated as paragraph. 150 characters seems safe, but unclear what the extract threshold is.

Add a publication date byline

Underneath the subtitle, add a <div> that wraps a <time> tag, with a datetime attribute, for the publication date, will trigger Reader to make a byline with the author and the date. It’s unclear where the author part comes from. Possibly from Google search, Open Graph, or Twitter Card metadata.

In hugo, the static site blog generator, this can be done using:

<div>
<time datetime="{{ .Date.Format "2006-01-02T15:04:05Z" }}">
{{- .Date.Format (.Site.Params.dateform | default "January 2, 2006") -}}
</time>
</div>

Working with bylines

You can make limited custom bylines as well. If <div> above also uses a byline class, Reader uses the entire <div>as a byline. Within reason: the total text needs to be short or Reader will reject it. The class byline does not need to be defined or provide style, it just needs to be present. Likewise, other CSS classes can be used, but byline must be included.

Again, in hugo:

<div class="byline another-class etc">
By <a href="/">Your Name Here</a> --
<time datetime="{{ .Date.Format "2006-01-02T15:04:05Z" }}">
{{- .Date.Format (.Site.Params.dateform | default "January 2, 2006") -}}
</time>
</div>

All Together

In the end, the main HTML for the content should look like:

<main>
<h1>Your title<h1>
<div>Your subtitle</div>
<div class="byline">
By <a href="/">Your Name</a> -- 
<time datetime="2018-04-06T05:52:50Z">April 6, 2018</time>
</div>
<p> article content... </p>
<p> article content... </p>
</main>

There are other variations that might work, but this provides a good base to start with. Not investigated are how images work with Reader.. When in doubt, View Source on a major publication is your friend.

Update 2018-04-12: Changed wrapper tag from <article> to <main>. Using <main> is more accessible.