# Time To Read

An [11ty](https://www.11ty.dev/) 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](#installation)
- [Usage](#usage)
- [Configuration](#configuration)
  - [Speed](#speed)
  - [Language](#language)
  - [Style](#style)
  - [Type](#type)
  - [Hours](#hours)
  - [Minutes](#minutes)
  - [Seconds](#seconds)
  - [Digits](#digits)
  - [Output](#output)
- [Example](#example)
- [Licence](#licence)


## Installation

```shell
npm install eleventy-plugin-time-to-read
```


## Usage

In your [Eleventy config file](https://www.11ty.dev/docs/config/) (`.eleventy.js` by default):
```js
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

```js
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl).

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:
```js
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

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

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

#### blog/post.md

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

#### blog.html

```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

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

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


## Licence
[MPL-2.0](https://choosealicense.com/licenses/mpl-2.0/)