Time To Read

An 11ty plugin that approximates how long it would take a user to read a given text and outputs the result in your choice of language and format.

1 minute
3 minutes
3 minutes, 10 seconds
3 minutes and 10 seconds
3 min & 10 sec
3m, 10s
3m 10s
3 minuty i 10 sekund
३ मिनट और १० सेकंड
三分钟和一〇秒钟
🕒🕒🕒 3 minutes to read

• Installation
• Usage
• Configuration
  • Speed
  • Language
  • Style
  • Type
  • Hours
  • Minutes
  • Seconds
  • Digits
  • Output
• Example
• Licence

Installation

npm install eleventy-plugin-time-to-read

Usage

In your Eleventy config file (.eleventy.js by default):

const timeToRead = require('eleventy-plugin-time-to-read');

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(timeToRead);
}

Then, depending on your template engine (Liquid by default) insert the filter into your template:

// Liquid (.liquid) or Nunjucks (.njk):
It will take {{ 'text' | timeToRead }} to read this

// Handlebars (.hbs):
It will take {{ timeToRead 'text' }} to read this

// Javascript (.11ty.js):
It will take ${this.timeToRead('text')} to read this

// Output:
It will take 1 minute to read this

Configuration

const timeToRead = require('eleventy-plugin-time-to-read');

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(timeToRead, {
    speed: '1000 characters per minute',
    language: 'en',
    style: 'long',
    type: 'unit',
    hours: 'auto',
    minutes: true,
    seconds: false,
    digits: 1,
    output: function(data) {
      return data.timing;
    }
  });
}

Speed

• Default: '1000 characters per minute'
• Accepts: A String formatted as: Number 'characters'/'words' [optional preposition] 'hour'/'minute'/'second'

The speed to calculate the time to read with. E.g. '250 words a minute', '5 words per second'.

Can also be entered when using a filter:

{{ content | timeToRead: '220 words a minute' }} // Liquid

{{ content | timeToRead ('220 words a minute') }} // Nunjucks

{{ timeToRead content '220 words a minute' }} // Handlebars

${this.timeToRead(data.content, '220 words a minute')} // JavaScript

Language

• Default: 'en'
• Accepts: A String representing a language supported by the Internationalisation API.

The language to use when outputting reading times. For example:

• fr = French
• es = Spanish
• ru = Russian
• zh-hans = Simplified Chinese

Number scripts can be changed using '-u-nu-', for example:

• en = 3 minutes
• zh = 3分钟
• zh-u-nu-hanidec = 三分钟
• en-u-nu-hanidec = 三 minutes
• hi-u-nu-deva = ३ मिनट

Can also be entered when using a filter:

{{ content | timeToRead: 'zh-hans' }} // Liquid

{{ content | timeToRead ('zh-hans') }} // Nunjucks

{{ timeToRead content 'zh-hans' }} // Handlebars

${this.timeToRead(data.content, 'zh-hans')} // JavaScript

Style

• Default: 'long'
• Accepts: 'narrow', 'short' or 'long'

The style of the text and conjunction, for example:

• long = 3 minutes and 10 seconds
• short = 3 min & 10 sec
• narrow = 3m, 10s

The exact output depends on the language and type options.

Type

• Default: 'unit'
• Accepts: 'unit' or 'conjunction'

The type of connection between list items, for example:

• unit = 3 minutes, 10 seconds
• conjunction = 3 minutes and 10 seconds

The exact output depends on the language and style options.

Hours

• Default: 'auto'
• Accepts: Boolean or 'auto'

Whether to show (true) or hide (false) hours. 'auto' will only display hours when they are greater than zero.

Minutes

• Default: 'true'
• Accepts: Boolean or 'auto'

Whether to show (true) or hide (false) minutes. 'auto' will only display minutes when they are greater than zero.

Seconds

• Default: 'false'
• Accepts: Boolean or 'auto'

Whether to show (true) or hide (false) seconds. 'auto' will only display seconds when they are greater than zero.

Digits

• Default: 1
• Accepts: An integer between 1 and 21 inclusive

The minimum number of digits to display. Will pad with 0 if not met, for example:

• 1 = 3 minutes, 10 seconds
• 2 = 03 minutes, 10 seconds
• 3 = 003 minutes, 010 seconds

Output

• Default: function(data) { return data.timing; }
• Accepts: Function

Controls the output of Time To Read via a callback function's return value. Will be passed an object with the following keys:

• timing - [String] the computed reading time, for example: '3 minutes, 10 seconds'
• hours - [Number|Null] the number of hours required to read the given text (if applicable)
• minutes - [Number|Null] the number of minutes required to read the given text after hours have been deducted (if applicable)
• seconds - [Number|Null] the number of seconds required to read the given text after hours and minutes have been deducted (if applicable)
• totalCharacters - [Number] the amount of characters in the given text
• totalWords - [Number] the amount of words in the given text
• totalSeconds - [Number] the number of seconds required to read the given text
• speed - [Object] The parsed data from the speed option. Has the following keys:
  • measure - [String] 'character' or 'word'
  • interval - [String] 'hour', 'minute' or 'second'
  • amount - [Number] the amount of measures per interval
• language - [String] returns the string passed to the language option

Can be used to customise text, for example:

function (data) {
  const numberOfEmoji = Math.max(1, Math.round(data.totalSeconds / 60));
  const emojiString = '🕒'.repeat(numberOfEmoji);

  return `${emojiString} ${data.timing} to read`; // 🕒🕒🕒 3 minutes to read
}

Example

How to create a blog page listing all posts with their reading times as well as include the reading time within those posts.

File structure:

_includes
└─ post.liquid
blog
└─ post.md
blog.html
.eleventy.js

_includes/post.liquid

<header>
  <h1>{{ title }}</h1>
  <p>About {{ content | timeToRead }} to read</p>
</header>

<main>
{{ content }}
</main>

blog/post.md

---
layout: post.liquid
title: Lorem Ipsum
tags: blogPost
---
Lorem ipsum dolor sit…

blog.html

<h1>Blog</h1>

<ul>
  {%- for post in collections.blogPost %}
    <li>
      <h2><a href="{{ post.url }}">{{ post.data.title }}</a></h2>
      <p>{{ post.templateContent | timeToRead }}</p>
    </li>
  {%- endfor %}
</ul>

.eleventy.js

const timeToRead = require('eleventy-plugin-time-to-read');

module.exports = function(eleventyConfig) {
    eleventyConfig.addPlugin(timeToRead);
}

Licence

MPL-2.0