reading_time
A Liquid filter that intelligently counts the number of words in a piece of HTML and estimates how long the text will take to read.
Installation
The easiest way to install this plugin is with RubyGems: gem install liquid_reading_time
.
If you’re using Jekyll, see the Jekyll documentation on installing plugins for more-detailed installation instructions. This plugin requires Nokogiri, so if you install this one manually you’ll need to make sure that that one is installed too.
Usage
Two functions are provided:
-
reading_time
This function gives an estimate of the amount of time it will take to read the input text. The return value is an integer number of minutes. The input should be HTML (i.e. the text should have already been run through your Markdown or Textile filter). For example, you could use it in a
_layout
file like this:{% capture time %}{{ content | reading_time }}{% endcapture %} <p>This article will take {{ time }} {% if time == '1' %}minute{% else %}minutes{% endif %} to read.</p>
Even better, using the pluralize filter,
<p>This article will take {{ content | reading_time | pluralize: "minute" }} to read.</p>
-
count_words
This function returns the number of words in the input. Like
reading_time
, this function takes HTML as its input.
Details
These functions try to be smart about counting words. Specifically, words are not counted if they are contained within any of the following HTML elements: area, audio, canvas, code, embed, footer, form, img, map, math, nav, object, pre, script, svg, table, track, and video. My intention here is to prevent words from contributing toward the count if they don’t seem to be part of the running text—contrast this with the simple but inaccurate approach of e.g. Jekyll’s built-in number_of_words
.
The plugin assumes a reading speed of 270 words per minute. Wikipedia cites 250–300 words per minute as a typical range, and I found that I could read articles on my website at about 270 words per minute.
Author
This plugin was created by Benjamin Esham.
This project is hosted on GitHub. Please feel free to submit pull requests.
Version history
The version numbers of this project conform to Semantic Versioning 2.0.
- 1.1.3 (2017-07-19)
- Updated the dependencies to reflect that the plugin works with Liquid 4 (without any code changes needed).
- 1.1.2 (2015-03-07)
- Apostrophes and curly single quotes shouldn’t break words into two.
- This plugin works with Liquid 3.x in addition to 2.x; updated the dependencies to reflect that.
- Added unit tests.
- 1.1.1 (2015-03-04)
- Don’t put the
ReadingTime
module in theJekyll
module. - Packaged the plugin as a Gem.
- Don’t put the
- 1.1.0 (2013-08-30)
- Switched from REXML to Nokogiri for HTML parsing.
- Input can now be HTML or XHTML. Previously, only valid XML was accepted (so things like non-closed
img
tags would makereading_time
crash). - Character entities like
蘗
are no longer included in the word count.
- 1.0.0 (2013-08-24): Changed reading speed from 220 to 270 words per minute.
- 0.9.0 (2013-08-19): Initial release.
License
Copyright © 2013, 2015, 2017 Benjamin D. Esham. This program is released under the ISC license, which you can find in the file LICENSE.md.