Elevate Your Eleventy Articles with the Reader Bar Plugin

Getting Started

The Reader Bar Plugin for Eleventy is a lightweight plugin to your Eleventy articles, designed to enhance the reading experience for your visitors. By displaying a simple and customizable bar that progresses as the user scrolls through your content this plugin provides a visual cue about their reading progress, encouraging longer engagement and content consumption.

Installation

The eleventy-plugin-reader-bar is available on npm, simply run the following command to add it to your project:

npm install eleventy-plugin-reader-bar

Configuration

Once installed, open your Eleventy config file (typically called .eleventy.js) and add the plugin:

const readerBar = require('eleventy-plugin-reader-bar')

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(readerBar)
}

Usage

Using the Reader Bar Plugin is straightforward and can be implemented in two simple steps:

1. Base Template Setup

In your base template:

• Create a div HTML element with the class reader-bar-start.
• Ensure this div wraps all the elements of the page, including the header (and optionally, the footer). If not wrapped properly, the Reader Bar may appear fully filled before scrolling through the entire page.
• To hide the Reader Bar on your base or index page, add the custom shortcode:

{% readerBar "0px" %}

2. Post/Content Template Setup

In your post or content template:

• Add the shortcode:

{% readerBar %}

• For template-specific shortcode examples, refer to the "Examples" section below.

Customization

The Reader Bar Plugin offers various customization options to tailor the appearance of the Reader Bar to your site's branding and preferences:

• height: Adjust the thickness of the bar (value in pixels, default: 4px).
• background color: Specify the color of the full-width bar (value can be a literal color name or a hexadecimal code, default: black).
• fill color: Customize the color that fills the bar as you scroll the page (value can be a literal color name or a hexadecimal code, default: orange).
• padding top: Control the space between the top of the screen and the bar (value in pixels, default: 2px).

Examples

Here are some examples of how to use the Reader Bar Plugin shortcode with different customization options:

• 
  {% readerBar %}
  

  displays the default Reader Bar (works in Liquid and Nunjucks templates).

• 
  {% readerBar "0px" %}
  

  hides the Reader Bar (use in your base template if necessary).

• 
  {% readerBar "8px" "red" %}
  

  displays the Reader Bar with a height of 8px and a red background color.

• 
  {% readerBar "8px" "#ff0000" "#0000ff" %}
  

  displays the Reader Bar with a height of 8px, a red background color, and a blue fill color.

• 
  {% readerBar "8px" "#ff0000" "#0000ff" "0px" %}
  

  displays the Reader Bar as in the previous example, but with no padding top.

Note for Nunjucks templates: Arguments need to be comma-separated, e.g.,

{% readerBar "8px", "#ff0000", "#0000ff" %}

Note for Handlebars templates: All parameters must be informed, e.g.,

{{{ readerBar "8px" "#ff0000" "#0000ff" "3px" }}}

See It in Action

You can see a live demo of the Reader Bar Plugin in action on the 11ty Plugin Reader Bar Demo website or check out the Github repository.

Alternatively, you can run a sample locally by cloning the repository (git clone https://www.github.com/thigoap/eleventy-plugin-reader-bar.git) and running npm test.

Elevate your Eleventy site's reading experience by incorporating the eleventy-plugin-reader-bar today! With its sleek design and customization options, you'll provide your visitors with a visually appealing and engaging way to track their reading progress, encouraging deeper content consumption and improving overall user satisfaction.