Mathias Bynens

How to enable Safari Reader on your site?

Published · tagged with HTML, iOS, macOS

Yesterday, Mike Taylor raised a very interesting question on Twitter:

Anybody know what Safari 5 requires for a page to be Reader-ifiable?

I noticed Reader was already working on this site for most blog posts. For example, the article about the three levels of HTML5 usage triggers the Reader badge in Safari’s address bar. I concluded the use of the <article> element to wrap the actual content must be one of the things that trigger it.

Further investigation

However, there’s more to it than just using the right markup. For example, Reader doesn’t work on this page containing my notes on document.head, even though the markup is similar to that of any other article on this site. It seems as if the length of the content is important as well. But how does Safari measure content length? Does the number of children of the wrapper element matter? How about the number of characters inside?

Rob Flaherty decided to investigate this further and created some test documents. He made some interesting observations:

  • You need a wrapper element around the actual content, other than <body>. It doesn’t really matter which element you choose, as long as it’s not <p>.
  • Reader requires at least five child elements inside the wrapper. Using double line breaks (<br><br>) inside an element makes it count as two elements.
  • Reader doesn’t seem to work for local files.

All valid points, except “Reader requires at least five child elements inside the wrapper”, which doesn’t seem to be true. The number of child elements doesn’t matter, the content length seems to be measured another way. I’ll get to that later.

Clayton Ferris did some additional testing, and concluded the following:

It looks like that Safari Reader will detect a <div> or block level element that contains a header element (<h1> to <h6>), followed by a certain amount of text. The reader badge will appear when the content text (not including the header) is more than 2,000 characters.

Sadly, none of Clayton’s statements seem to be true. I created some quick test cases to demonstrate it’s just not that simple:

  • Test 1: 3 paragraphs, 1,863 characters (including heading and line breaks); Reader fails.
  • Test 2: same as test 1, but with <p>.</p> added — 4 paragraphs, 1,866 characters; Reader works.
  • Test 3: test without any heading elements — 6 paragraphs, 3,718 characters; Reader works.

This also proves that there is no fixed amount of paragraphs (or other elements) needed to enable Reader; it all depends on the contents.

Reader and the Readability bookmarklet

Apple attributes Arc90’s Readability experiment in the Safari Acknowledgements (Safari › Help › Acknowledgements or file:///Applications/Safari.app/Contents/Resources/Acknowledgments.html on Mac). This bookmarklet seems to be what Reader is based on, so it’s probably a good idea to dive in the source code.

For example, every paragraph containing double line breaks (<br>) counts as two paragraphs — this confirms what Rob concluded after his tests. Direct child text nodes and <div>s that don’t have block-level child elements count as paragraphs as well.

It turns out Readability then loops through all these ‘paragraphs’ and assigns a score to them based on how ‘content-y’ they look. This score is determined by things like the number of commas, class names used in the markup, etc. The content’s length appears to be measured by using .innerText; for every 100 characters inside a paragraph, that paragraph’s score goes up. Eventually, the number of elements is counted, adding their individual scores. I think it’s safe to assume Safari Reader is triggered based on this algorithm.

Conclusion

This definitely needs more investigating, but so far, these appear to be the most important factors for Safari’s Reader functionality to kick in:

  • Use the right markup, i.e. make sure the most important content is wrapped inside a container element. Whether you use <article>, <div> or even <span> doesn’t seem to matter — as long as it’s not <p>.
  • The content needs to be long enough. Use enough words, use enough paragraphs, use enough punctuation. Every paragraph should have at least 100 characters.
  • Reader doesn’t work for local documents.

About me

Hi there! I’m Mathias. I work on Chrome at Google. HTML, CSS, JavaScript, Unicode, performance, and security get me excited. Follow me on Twitter, Bluesky, and GitHub.

Comments

Niels Matthijs wrote on :

One thing you seem to have missed is that the reader fails when it has multiple possible reader sections on one page. The reader works on my blog, unless the article has a somewhat populated comment section. At that time there are two areas competing for the reader’s attention, and It appears to drop the functionality completely in such a case.

Still, interesting stuff, comes very close to what I’d figured out myself (minus the math and points system that is :)).

wrote on :

Niels: If there are multiple possible content sections on the page, the Reader will always target the one with the highest ‘score’.

Safari Reader indeed doesn’t seem to be working for the latest article on your blog. However, the fact that there are multiple possible content sections has nothing to do with this. I quickly made a test case based on your article without the comments section, and as you can see, Reader still doesn’t work.

Niels Matthijs wrote on :

It seems to dislike all my “work” posts btw. Which is strange, because there are plenty of them that feature more content, more paragraphs, more data.

One thing that’s different between the two is that I use extra wrappers for underlying sections (an extra wrapper div for each section starting with an h2 for example). My personal blog posts almost never feature subsections.

My guess: it does not count all paragraphs nested within a certain div, only the paragraphs on the same level? Would suck though.

Rob Flaherty wrote on :

Great post! Brilliant idea checking out the Acknowledgements and the Readability bookmarklet. It’s interesting that the Readability bookmarklet works on all of the test pages that fail. Actually it works on just about any page.

I’m a little surprised the test case based on Niels’ article fails. Too many nested divs trips up the algorithm?

George Terezakis wrote on :

Another interesting thing to look into would be the way Reader deduces multi-page articles such as this one.

I reckon that it’s looking for a series of 2 or more consecutive links to pages that use the same base URL as the current one, with a increasing numeral as an argument.

Marc wrote on :

Niels: I’d noticed the same thing; a design I'm working on has rather long articles (each wrapped in an <article>) broken down into sections, each of which is wrapped in a <section> and <div> tag, then headed within that with an <h2> (the <article> and <section> tags are purely future-looking semantic structure, for the heck of it; they serve no useful purpose).

With this layout, depending on the content of the largest of the <div> sections Reader may or may not even appear, and on those it does it only shows the content of the largest <div>. For example on a page where the largest chunk contains about 8,600 characters and 22 <p> elements, no Reader is offered at all. On a nearly identical one with a main section of 5,800 characters and 13 <p> elements, Reader is offered, but only displays that, ignoring the other 3,000 characters of main content on the page.

It would have been nice had the feature assumed <article> to be meaningful, and filtered down to, say, all the subheadings and paragraphs within it that look ‘content-y’. Maybe in a future version.

Scot Hacker wrote on :

Same question as George. I run a site with multi-page tutorials. Reader does kick in for the tutorial pages, but does not detect that they’re multi-page (it only renders one page at a time in Reader). What’s the secret to Reader detecting that a “next page” link really does go to the next page of the current article?

Thomas Viktil wrote on :

I just discovered that the Reader is enabled when I’m logged in to WordPress’ wp-admin. I just wrote a couple of notes on a future article, saved it as a draft and voila! The Reader button appears. I clicked it and the only thing it displayed was ‘Edit’ (since I was editing a post).

Ondrej wrote on :

I just tested Reader function in our CMS and found out that you just need one big text: one paragraph with length longer than 600 characters. Two paragraphs with length 300+300 don’t work.

bo wrote on :

I can’t make heads or tails… On one of my pages it selects a particular div, if I add content to the div or recreate it in another location, it still selects the original. How can I create a div that will absolutely be the one selected?

Also, it looks as if the content is being cached. If I make changes to the immediately ‘readable’ are, they do not get updated in the reader. Even if I add all the right elements to increase the ‘score’.

bob wrote on :

How much do I hate Reader? Plenty. The free web needs ads to pay for some of the work. This knocks out an important column supporting their work. Wow. One more reason almost everything good will end up behind a paywall.

burki wrote on :

Does anyone know a WordPress theme that does NOT allow Safari reader mode? Simply: I hate it.

Anonymous wrote on :

The Reader function is very unstable in iOS 5 on iPhone. It shows up or doesn’t show up on exactly the same site, so it is inconsistent.

Peter Blair wrote on :

We have produced a website containing my experience of having a serious stroke and the various ways I have learned to “get round” all the things I can no longer do easily. Some of the pages work with Safari Reader and some don’t and we found out about Safari long after we did the website. Can anyone explain how to activate the Reader facility because I have learning difficulties as a result of the stroke, and the Reader facility is a godsend and may help others with reading difficulties.

Dimitar Panov wrote on :

bob: I think if the site has a well optimized mobile version, that has good readability, the visitors won't feel a need to use the Safari Reader functionality. I use it almost only on sites without mobile version, or on mobile sites with very small font size.

Dan wrote on :

I struggled with this for some time, but I finally took the <ul> tags out of my story, and it worked. The first page it worked on is at http://www.danmanning.com/washington. I tried it again on another page, testing it first with the <ul> markings in (Reader didn’t work) and then took the <ul> tags out and reloaded the page. It worked.

sam wrote on :

Thank you so much for the info. I had issues making it work on my site and now, it is fixed. Thanks again.

robert wrote on :

Microsoft is demonized for adding freestyle “features” like this one. But I think this is even worse, because hundred people are not yet able to explain how it works. This is not a cool feature. HTML has invented <link rel="…" href="..."> to explicitly define alternate views, and it works in a predictable way, you don’t need to count your commas or pray to your saints.

vic wrote on :

A belated comment on this, but just recently upgraded my iPad to iOS 5, and discovereded Reader. My site’s (WP iFeature theme) pages and posts all seem to trigger it… And some paragraphs contain fewer than 100 characters, so that criterium doesn’t seem to apply.

eric wrote on :

The source code also must be stored in UTF-8 to be recognized. Not only <meta http-equiv="Content-Type" content="text/html; charset=utf-8">!

mike bayer wrote on :

I’m getting the impression based on my blog that reader also fails if your post has code sections using <pre> tags, or perhaps very wide code sections that employ in-place horizontal scrolling. But I haven’t looked into it deeply.

Lucas wrote on :

One note I would add. It does only work on http:// not on https:// secured connection.

Martijn wrote on :

None of the three tests trigger Reader on my Safari 7. The extra test case from comment 2 does trigger Reader this time around.

Does anyone know if more recent research has been done?

Shraftali wrote on :

I ran some tests using OS X Mavericks + Safari 7.0.1 and it looks like it can work on the localhost, and triggering the Reader button based on two things: 1. Content height if it is higher then the half of available browser height. 2. Content need to be in some wrapper tag, doesn’t matter what (tested to work with P, DIV, ARTICLE).

Phoenix wrote on :

Reader also doesn’t work on HTTPS. Secure sites. This is stupid because most websites such as banks and Bloomberg and NYT are going secure when logged in.

Robipad wrote on :

I tried to make my website showing the “Reader” at all available pages for iPad (2) and iPhone (4). During the design process I noticed that a minimum number of text characters of ca 350-400 is needed before the “Reader” is activated (4 lines left from URL). The number is independent from character size (even 3px is OK and even invisible characters will do) and independent from the elements you choose <p> or <div> or whatever.

But for the iPad (1) where the reader is still shown as “Reader” (right from the URL) and also in Safari at my PC at least 700–800 characters (12px) are needed. However this number of characters will very much depend on the size of characters. The smaller the size the more characters you need. So conditions change strongly with OS and/or browser versions.

Secondly if the homepage did come up without showing index.html in the URL (which is the default) the “Reader” was never activated. Using the navigation in the website always added index.html in which case the “Reader” is activated. So this was annoying. To solve this I now use a redirect which adds the index.html to the URL. Where can I find sensible “conditions” for a webpage to activate the “Reader”? Or is this a secret?

Anonymous wrote on :

I’m surprised that some of the feedback does not get into how Readability / Safari Reader essentially shuns the <p> element. I see many resources always trumpeting the viability of <p> elements for semantic web development constantly. I would have thought in 5+ years someone by now would have tossed some backlash at Readbility or Apple over this. But I’m also surprised that in 5+ years that Mozilla or Google have not added similar functionality into their own offerings — as I find Safari’s Reader a very nice addition constantly.

I for one do not use <p> tags unless something specific mandates it — a given CMS etc. — as the pre-formatting gets in the way constantly of most development. So instead of spending time rewriting CSS to adjust default <p> element styles, I simply start with elements such as <div> that come blank and build out from there.

But all in all you would think that instead of the community at large having to second-guess or hack at how Readability works and functions, there would be more readily available documentation to format for practical use cases.

Apple outs this mythical “Reader” thing and tells everyone they can use it to peruse content on any webpage on any website, but then don’t tell the developers how to set up for it and it becomes a hit-or-miss guessing game at best.

Andy Hurt wrote on :

I’ve been postponing the inevitable wrt: getting things right with “Reader View”, as my expertise is little, and the details are large (I work in an entirely-different field, and my compu-time is limited).

It’s 2016, now, and things have moved-on, but the basic gist still remains:

What are we to to—as Designers—when results fail expectations?

We try, and try; again, and again.

My little web-space-content-thingy is my passion, and joy: I hold the expectation that everything I create should follow my desire that Things Just Work.

Short Story Long:

I’ve finally got my Photo Gallery PHP working, and it traverses the image folder-tree so, so sweetly it would surely make my mother blush, but the fsck'r still would plop the first few <div>'s raw data as the Title-Header in Reader View in Safari, iOS, et al. (until I interactively (re)cursed the folder tree past top-level).

I’ve been working on fixing this for over thirteen months, and it has escaped me.

It was not until tonight that I read your thoughts (from 2010, nonetheless), and I actually began to truly think about the matter.

I had a series of <p>aragraphs that were successfully parsed in Reader View, but the Parser has always fsck’d the Header.

Reading your thoughts, I had an epiphany: why not wrap a <div> around these <p>s to see what happens?

So; it’s so: I did this.

Amazingly, Reader View in Safari 9.0.3 (11601.4.4) on El Capitan, and Safari on iOS 9.2.1 (13D15) now show “Photo Gallery” as the Title-Header on the base landing page, rather than “215artwork” (2 folders, 15 images and a folder-name of artwork).

Boring, I’m sure, but a coup, to say the least.

Thank you, Mathias, for your thoughts, and helping another stranger!

I, and I, and (you (you know who you are, as you who are possibly in the same boat)), will remember.

Peace, Brother.

Andy; USA; Atlanta

Billy Bob wrote on :

Scot Hacker: I was visiting some pages about Alcatraz Island and maybe the source code of the pages will help you find out why Safari Reader does this "multiple-game digging". www.alcatrazhistory.com/battle1.htm in reading mode, once you scroll to the bottom it loads the next page, but the button is visible breifly.

Vince de Vries wrote on :

It’s quite remarkable how some commenters write that they dislike the Reader feature or even hate it. I only invoke it when someone has made a bad design so those haters really should ask themselves why anyone hits the Reader button in the first place.

Common mistakes that urge me to use Reader are:

  • a too wide column or no width restriction at all (like Wikipedia)
  • a font so small that you need 20/20 vision (and defined in pixels instead of ems so it won’t adjust to accessibility settings)
  • a lack of contrast between foreground and background. Many designers seem to love gray-on-gray. But it is difficult to read
  • a bad layout that requires a lot of eye-movement to follow the content. Especially ads that are placed left within the text-flow

These issues make at least me feel happy with Reader. So designers who fear their websites will lose income because of Reader hiding advertising, should really do a better job designing the page (and the ads). If you make something annoying, people will be annoyed and do everything to fix it.

Vince de Vries wrote on :

I have a problem with Reader however. I made a test page, with two articles both with <h1> title (I also tried <h2>) and content (over 1000 chars), following all recommendations of Readability, doing all that’s advised on this page, but still Reader doesn’t show the headers of articles correctly.

I have validated the page to be sure there were no errors. The weird thing is that Safari Reader wraps the paragraphs of the first article in a <div> but leaves the paragraphs of the second article un-wrapped. It baffles me.

Awais khan wrote on :

Awesome! very helpfull article Thankx.. See our services Digits Global provide services like web design in usa, web development in usa, seo services in usa, social media and web hosting. call now +1-866-513-467

Jesse wrote on :

I agree it would be a kindness were Apple to offer specifics for what a website coder might expect. I'd like one of my blogs gracefully to transform in Reader. I finally got it down to one pickayuny thing. I'd like the whole byline (including author's name) to vanish in Reader. As it is, I link the author's name to an "About" page. I found this. If I set the link with "rel=author" the Author's name will NOT vanish in Reader; but if I change it to "rel=me" it vanishes as desired. All this is with no other changes to the HTML or CSS; the link is enclosed in a DIV below an H1 before the first P. Curious. Not documented anywhere I can find. Frustrating. Me: like it or lump it.

Leave a comment

Comment on “How to enable Safari Reader on your site?”

Your input will be parsed as Markdown.