ghost-progress-plugin preview

Scroll and watch the bar at the top fill from 0% to 100%. Change options in the left panel and the embed code updates with them.

Getting started

ghost-progress-plugin is a tiny, dependency-free reading progress bar for Ghost. It started as a Ghost widget, but it also works on Notion-based blogs, and anywhere you can add a script. As you read, a thin bar fills to show how far through the article you are. This page is a live example: the bar at the top is the real widget.

Installation

Add it once with this snippet, no build step, no theme files to edit:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/GreedyLabs/ghost-progress-plugin@1/progress.css">
<script src="https://cdn.jsdelivr.net/gh/GreedyLabs/ghost-progress-plugin@1/progress.min.js"
        data-content=".gh-content"
        data-position="top"></script>

Code injection

In Ghost, paste it into Settings → Code injection → Site Footer. On Notion-based hosting, add it in the custom-code field: oopy has a head/footer code box in its site settings, super.so has a Custom Code area, and there you set data-content to .notion-page-content. On any other site, put it just before the closing </body> tag.

Options

Everything is configured with data-* attributes on the script tag: the content selector, the position, the height, and the z-index:

data-content=".gh-content"
data-position="top"
data-height="4"
data-z-index="100"

Customize

The bar color and thickness are adjustable. Every class and CSS variable is namespaced under greedylabs-ghost-progress, so it never clashes with your theme.

Colors

The fill follows your Ghost theme accent (--ghost-accent-color) by default; set data-color or override the CSS variables to change it. The unread track is transparent by default, so give it a color to make the bar visible even at 0%:

.greedylabs-ghost-progress {
  --greedylabs-ghost-progress-color: #1a73e8;
  --greedylabs-ghost-progress-track: rgba(0,0,0,.08);
}

Position

Use data-position for top or bottom, and data-height for the thickness in pixels. The bar reaches 0% when the article top meets the top of the viewport, and 100% when its bottom meets the bottom. Give data-anchor a selector to pin the bar to that element (for example a top nav) instead of the viewport edge. When the selector is empty, matches nothing, or is hidden (as on mobile), the bar falls back to the viewport edge.

FAQ

Does it track the whole page or just the article?

Just the article you point data-content at. The header, feature image, and footer do not count toward the progress.

Why is the bar invisible at the top?

At 0% the fill has no width and the track is transparent by default. Give the track a color (see Colors) to show the bar even when empty.

Does it work outside Ghost?

Yes. Anywhere you can inject a script, point data-content at your article container. For Notion that is .notion-page-content.

Wrapping up

ghost-progress-plugin is open source under the MIT license; the code and issues live on GitHub. Try the options in the left panel and copy the embed snippet when you are happy. If it helped you, a coffee is always appreciated ☕.