Astro

Astro builds static HTML into dist by default. Run Headlark right after it and every page ships with its title, description, link previews, structured data and alt text.

Option A: the Astro integration

npx astro add astro-headlark

Or install it yourself with npm i -D astro-headlark and add it to your config:

// astro.config.mjs
import { defineConfig } from "astro/config";
import headlark from "astro-headlark";

export default defineConfig({
  site: "https://example.com",
  integrations: [headlark()],
});

It runs after astro build on the output folder, using site and base from your config, so you don't repeat the address. Without HEADLARK_KEY (local builds, previews) it skips and leaves pages as built. headlark({ strict: true }) fails the build when a page can't be optimized. Then add your key (step 3 below).

Option B: the build step

1. Install

npm i -D headlark

2. Add it to your build script

// package.json
"scripts": {
  "build": "astro build && headlark dist --site-url https://example.com"
}

Use the same address as site in astro.config.mjs, plus base if you set one (--site-url https://example.com/docs/). Page URLs and canonicals follow the files Astro writes: dist/blog/index.html becomes https://example.com/blog/. With trailingSlash: "never", also set build: { format: "file" } so Astro writes dist/blog.html and the canonical is https://example.com/blog, matching your links.

3. Add your key

Set HEADLARK_KEY to your site's secret key from the dashboard wherever the build runs: your host's environment variables, a CI secret, or your shell for a local build.

HEADLARK_KEY=sk_... npm run build

Good to know