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-track: rgba(0,0,0,.08);
}
@media (prefers-color-scheme: dark) {
  .greedylabs-ghost-progress {
    --greedylabs-ghost-progress-track: rgba(255,255,255,.14);
  }
}

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.

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 ☕.