on-ramp

Getting started

520 words·4min read

What PlugDash is

PlugDash is a plugin catalog for EmDash. Every plugin ships as an npm package, a companion Astro component, and a short list of CSS tokens you can override. Install one, import one component, and your readers see the result.

This site runs on EmDash with every PlugDash plugin installed. The reading time on this page, the sidebar you're reading it from, the engagement bar on blog posts - all of them are plugins. If they work here, they work for you.

How EmDash plugins work

An EmDash plugin is a small module that runs inside your Astro site. It listens to lifecycle hooks (like "a post was just published") and writes data back to your content - usually onto post.data.metadata. That data is then read by a companion component that renders it in your theme.

You do not need to know how the hook fires. You just install the plugin, register it in astro.config.mjs, and drop the companion component into your layout.

Install readtime

readtime is the simplest plugin in the catalog. It calculates reading time on every publish and ships a component that shows it. Use it as your worked example.

Step 1: install

npm install @plugdash/readtime

Step 2: register

Open astro.config.mjs at the root of your Astro project. Import the plugin at the top, then add it to the plugins array of the emdash() integration - the one that sits inside Astro's top-level integrations array: 

// astro.config.mjs
import { defineConfig } from "astro/config"
import emdash from "emdash/astro"
import { readtimePlugin } from "@plugdash/readtime"

export default defineConfig({
  integrations: [
    emdash({
      plugins: [
        readtimePlugin({ collections: ["blog"] }),
      ],
    }),
  ],
})

Step 3: add the component

In your post layout:

---
import ReadingTime from "@plugdash/readtime/ReadingTime.astro"
---
<ReadingTime post={post} />

Publish a post in the EmDash admin. Reload the page. The reading time appears. No other configuration needed.

Change the look

Every PlugDash component reads from CSS custom properties under the --plugdash-* namespace. To restyle, override them in your global stylesheet: 

:root {
  --plugdash-accent: #6366f1;
  --plugdash-muted: #888;
  --plugdash-rt-radius: 4px;
}

If you need more than tokens can give you, copy the component's .astro file out of node_modules/@plugdash/*/src/ into your theme and modify it freely. Components are intentionally simple and have no upstream coupling.

Next steps

Each plugin has its own doc with install, props, CSS tokens, and a live demo of its companion component:

built with plugdash