DEV Community: Headlark

Duplicate titles and meta descriptions on a docs site

Headlark — Wed, 21 Oct 2026 22:57:48 +0000

Originally published on headlark.com.

Docs sites grow by copying pages. A new section starts as a copy of an old one, every product area gets an "Overview" and a "Configuration" page, and the framework fills in whatever the front matter leaves out. The result is dozens of pages that tell search engines the same thing in their <title> and <meta name="description">.

Google asks for a distinct description per page and descriptive, concise titles (Google Search Central: snippets, title links). When fifty pages share one description, Google writes its own snippet from the page text, and search results for your docs look alike, so people have a harder time picking the right page.

Where the duplicates come from

Docusaurus

Each doc's description comes from its description front matter. Without it, Docusaurus uses the first line of Markdown content as the description (docs front matter). It skips imports, code blocks and the # title, but not everything else, so these patterns produce repeats:

Pages that open with the same ## Overview or ## Prerequisites heading get "Overview" or "Prerequisites" as their description.
Pages that open with the same admonition (:::note followed by "This feature is in beta.") all get that sentence.
Versioned docs repeat every page once per version, with identical titles and descriptions.

Titles come from title front matter, then the Markdown # heading, then the doc id, followed by the site title. Two pages called "Configuration" in different sections become two identical "Configuration | My Project" titles.

Starlight

Every page has a required title; description is optional. The site-wide description in your Starlight config is used for every page that doesn't set its own (Starlight configuration). So the more pages you have without front matter descriptions, the more pages share the site description.

VitePress

The description in .vitepress/config renders on every page, and a page's front matter description overrides it (VitePress site config). A page's title is its front matter title or the text of its first <h1>, plus the titleTemplate suffix. The same failure modes as Starlight: one description everywhere, and repeated headings become repeated titles.

Find them in your build

Check the HTML your framework produced, not the source files: that's what crawlers read, and it includes the fallbacks. Build first, then point these at the output folder (build for Docusaurus, dist for Starlight, .vitepress/dist for VitePress).

Descriptions used on more than one page, with a count:

grep -rhoE --include='*.html' '<meta name="description" content="[^"]*"' build | sort | uniq -cd | sort -rn

Titles used on more than one page:

grep -rhoE --include='*.html' '<title[^>]*>[^<]*' build | sed 's/<title[^>]*>//' | sort | uniq -cd | sort -rn

To see which files share a given description:

grep -rlF --include='*.html' 'content="Overview"' build

Attribute order and quoting vary between frameworks; if a command prints nothing, open one built page and adjust the pattern to match its tag. For the live site, the free site checker reads your sitemap and lists every duplicated title and description with the pages that share it, across up to 50 pages. For a single live page, the free SEO checker shows the title and description exactly as crawlers get them.

Fix them per framework

Docusaurus

Set both fields in the front matter of each doc. description also becomes og:description.

---
title: Configure the CLI
description: Every option in headlark.config.json, with defaults and an example for monorepos.
sidebar_label: Configuration
---

title is for the browser tab and search results; sidebar_label keeps the short name in the sidebar. For old versions you don't want in search results, set noIndex on the version in the docs plugin options:

// docusaurus.config.js, inside the docs plugin or preset options
docs: {
  versions: {
    '1.x': { noIndex: true },
  },
},

Starlight

---
title: Configure the CLI
description: Every option in headlark.config.json, with defaults and an example for monorepos.
---

Keep the site-wide description in astro.config.mjs for the home page, and treat any other page that still shows it as unfinished. Starlight joins the page and site titles with titleDelimiter (default |); the page title is the part that has to be unique.

VitePress

---
title: Configure the CLI
description: Every option in headlark.config.json, with defaults and an example for monorepos.
---

To catch pages that still inherit the site description, a transformPageData hook in .vitepress/config.mts can list them during the build:

export default defineConfig({
  description: 'Docs for the example CLI',
  transformPageData(pageData) {
    if (!pageData.frontmatter.description) {
      console.warn(`no description: ${pageData.relativePath}`)
    }
  },
})

Writing ones that stay unique

Lead with what the page is about, not the section. "Configure the CLI" beats "Configuration"; "Deploy to Netlify" beats "Netlify".
Put the distinguishing detail in the description: the option names, the platform, the error message the reader searched for. Aim for one or two sentences, roughly 70 to 155 characters, so it isn't cut off.
Don't fill descriptions with keywords. Google is explicit that keyword lists don't help.
Reused partials and generated pages (API references, changelogs per version) need a description built from the data that differs, such as the class name or version number.
Re-run the duplicate check in CI so a copied page doesn't reintroduce the problem.

Automating it with Headlark

Writing and maintaining a description for every page is the part that slips on a large docs site. Headlark's build step runs after your framework's build, on the HTML in build, dist or .vitepress/dist:

"build": "docusaurus build && headlark build --site-url https://docs.example.com"

Each page gets a title and description written from that page's own content, so two pages only end up alike if they say the same thing.
Your canonical, robots directives and JSON-LD types are kept; an empty result never replaces one of your tags.
Unchanged pages come from cache on every rebuild.
Docusaurus and VitePress switch pages in the browser after the first load and can apply their own title from their route data, so the browser tab may show your original title after a click. Crawlers and link previewers load each page's HTML and see the rewritten tags.

Review the results on your most visited pages; it takes minutes when the rest is done.

Try it

The free plan covers one site and 25 pages. Add your site, copy its secret key, and your next build ships with SEO.

SEO for Docusaurus: titles, descriptions, link previews and structured data

Headlark — Wed, 21 Oct 2026 17:47:28 +0000

Originally published on headlark.com.

Docusaurus renders a static HTML file for every route, so crawlers and link previewers get real content without running JavaScript. Out of the box each page also gets a <title>, a canonical link, og:url, twitter:card set to summary_large_image, and hreflang links when you have more than one locale. What it can't do on its own is write a good description for every page, pick a preview image per page, or decide which pages belong in search. This guide goes through each setting in order, for Docusaurus 3 (Docusaurus: SEO).

1. Site URL and trailing slashes

Every absolute URL Docusaurus writes (canonical, og:url, og:image, sitemap entries) is built from url and baseUrl in docusaurus.config.js. Set them to the production address:

export default {
  url: 'https://docs.example.com',
  baseUrl: '/',
  trailingSlash: true,
};

Set trailingSlash explicitly. With the default (undefined) Docusaurus leaves links as written and emits /docs/intro/index.html for docs/intro.md, but the canonical and sitemap URL is /docs/intro without a slash. Many static hosts, GitHub Pages among them, answer that URL with a redirect to /docs/intro/. The result is a canonical that points at a redirect, and Search Console reports such as "Page with redirect" or "Alternate page with proper canonical tag".

Setting	File written for `docs/intro.md`	URL in canonical and sitemap
`true`	`build/docs/intro/index.html`	`/docs/intro/`
`false`	`build/docs/intro.html`	`/docs/intro`
`undefined`	`build/docs/intro/index.html`	`/docs/intro` (as linked)

Pick the value that matches how your host serves those files without redirecting; the Docusaurus deployment docs point to the trailing slash guide, which lists the behavior of each host. Then check one page:

curl -sI https://docs.example.com/docs/intro | grep -iE '^(HTTP|location)'

A 200 means the canonical URL is served directly. A 301 or 308 means trailingSlash and your host disagree.

2. Site-wide metadata and the default preview image

Two settings in themeConfig apply to every page (theme configuration):

export default {
  themeConfig: {
    image: 'img/social-card.png',
    metadata: [
      {name: 'twitter:site', content: '@example'},
    ],
  },
};

image is the default og:image and twitter:image, a path relative to the static folder (or a full URL). Docusaurus makes it absolute from url. It can't be an SVG; Facebook, LinkedIn and X won't render one. Use a PNG or JPG around 1200×630.
metadata is a list of <meta> tags; every field is passed straight to the tag, and an entry overrides a default with the same name, such as twitter:card.

Without image, pages have no preview image at all unless the doc sets one. If a card still comes out without a picture, og:image not showing covers the other causes.

3. Per-page front matter

The docs, blog and pages plugins all accept the same four SEO fields (docs front matter):

---
title: Configure the CLI
description: Every option in the config file, with defaults and an example for monorepos.
image: /img/social/configure.png
keywords: [cli, configuration]
sidebar_label: Configuration
---

title becomes <title> (followed by the site title) and og:title. Without it Docusaurus uses the Markdown # heading, then the doc id. sidebar_label keeps a short name in the sidebar while the title says what the page is.
description becomes both <meta name="description"> and og:description. Front matter is the better place for it than a hand-written tag, which would need both.
image becomes this page's og:image, replacing themeConfig.image.
keywords becomes a <meta name="keywords"> tag. Google doesn't use that tag for ranking, so leave it out unless your own site search reads it.

The first-line description

If a doc has no description, Docusaurus uses the first line of Markdown content. Imports, code blocks and the # title are skipped, but other headings, admonitions and short intro sentences aren't. A page that opens with ## Prerequisites gets "Prerequisites" as its description, and so does every other page that opens the same way. To see what your build produced:

grep -rhoE --include='*.html' '<meta name="description" content="[^"]*"' build | sort | uniq -c | sort -rn | head

Any description with a count above 1 is shared. Duplicate titles and descriptions on a docs site goes through finding and fixing them, including versioned docs.

4. Other head tags

For tags the front matter doesn't cover, there are three places, from widest to narrowest.

Every page: headTags in docusaurus.config.js, a list of objects with tagName, attributes and optionally innerHTML:

export default {
  headTags: [
    {
      tagName: 'link',
      attributes: {rel: 'preconnect', href: 'https://fonts.example.com'},
    },
  ],
};

One Markdown or MDX page: a <head> block in the file itself:

# Migrating from v2

<head>
  <meta property="og:type" content="article" />
</head>

A React page in src/pages: the @docusaurus/Head component. The default Layout also takes title and description props, which fill the same tags as front matter:

import Layout from '@theme/Layout';
import Head from '@docusaurus/Head';

export default function Pricing() {
  return (
    <Layout title="Pricing" description="Plans and limits for the hosted version.">
      <Head>
        <meta property="og:image" content="https://docs.example.com/img/social/pricing.png" />
      </Head>
      {/* page content */}
    </Layout>
  );
}

Tags set this way go into the static HTML at build time, so crawlers see them.

5. Keeping pages out of search

One page: <head><meta name="robots" content="noindex" /></head> in the file. The sitemap plugin leaves out pages with a noindex robots tag.
A page you link to privately: unlisted: true in front matter. It's built, but hidden from the sidebar, marked not to be indexed and left out of the sitemap.
An old docs version: noIndex: true on that version in the docs plugin's versions option.
The whole site (a staging deployment): noIndex: true at the top level of the config adds noindex, nofollow to every page and skips the sitemap. Make sure it's off in production.

Don't use robots.txt for this: it stops crawling, not indexing, and a blocked page can't show Google its noindex.

6. The sitemap

@docusaurus/plugin-sitemap is part of preset-classic and writes sitemap.xml during docusaurus build (plugin-sitemap). Configure it through the preset:

presets: [
  [
    'classic',
    {
      sitemap: {
        lastmod: 'date',
        changefreq: null,
        priority: null,
        ignorePatterns: ['/tags/**', '/blog/page/**'],
      },
    },
  ],
],

ignorePatterns takes globs matched against route paths. With a baseUrl other than /, include it in the pattern (/repo/tags/**). Tag and paginated list pages are the usual candidates: thin pages that compete with your docs.
lastmod ('date' or 'datetime') adds <lastmod> from each file's last update. Google uses lastmod when it's consistently accurate and ignores changefreq and priority, so setting those two to null just makes the file smaller.
createSitemapItems is a function for filtering or changing items when globs aren't enough.

Point crawlers at it with a line in static/robots.txt, Sitemap: https://docs.example.com/sitemap.xml, and submit it in Search Console.

7. Structured data

Recent Docusaurus 3 releases already emit BreadcrumbList JSON-LD on docs pages and BlogPosting on blog posts, so check a built page before adding your own. Site-wide data such as an Organization goes in headTags as a script with type: 'application/ld+json'; one-off data goes in the page's <head> block. JSON-LD for Astro and Docusaurus has working code, the types worth using and how to validate them.

8. Check the build

Everything above ends up in the HTML in build, so check that rather than the config. After npm run build, list pages without a description and pages without a preview image:

grep -rL --include='*.html' 'name="description"' build
grep -rL --include='*.html' 'property="og:image"' build

Then check a few deployed pages with the free SEO checker, which shows the Google result and the LinkedIn, Slack and X cards each page produces, or the site checker for up to 50 pages from your sitemap at once.

Automating it with Headlark

The settings above are one-time work. Writing a distinct title, description and image alt text for each of hundreds of docs is the part that doesn't get done. Headlark's build step runs after docusaurus build on the HTML in build:

"build": "docusaurus build && headlark build --site-url https://docs.example.com"

The first build after headlark is the output folder. If you set a baseUrl such as /repo/, include it: --site-url https://example.github.io/repo/. Set HEADLARK_KEY in the build environment.

Each page gets a title, a description and Open Graph and X tags written from its own content, and alt text for images that have none.
Your canonical, robots directives and JSON-LD types are kept, so the Docusaurus defaults and your noindex pages stay as they are.
An existing og:image, from front matter or themeConfig.image, is kept. Headlark doesn't create images: with only themeConfig.image set, every page keeps that one image, so set image on the docs that deserve their own card.
Docusaurus switches pages in the browser after the first load and applies its own title from route data, so the tab may show your original title after a click. Crawlers and link previewers load each page's HTML and get the rewritten tags.

Try it

The free plan covers one site and 25 pages. Add your site, copy its secret key, and your next build ships with SEO.

og:image not showing in Slack, LinkedIn or X

Headlark — Wed, 21 Oct 2026 17:36:18 +0000

Originally published on headlark.com.

You share a link and the card has a title and a description but no picture, or a tiny thumbnail instead of a large image. The image in a link preview comes from the page's og:image tag (and twitter:image for X). When it's missing, unreachable or in a format the previewer rejects, the card drops it without telling you why. This guide covers the image specifically; for the full set of tags, see Open Graph tags for every page.

The usual causes

A relative URL. <meta property="og:image" content="/og.png"> doesn't work reliably. The Open Graph protocol expects a full URL, starting with https:// and your domain.
The wrong domain. The URL points to localhost, a preview deployment or a staging host, because the site URL wasn't set for the production build.
An SVG. Facebook, LinkedIn and X don't render SVG preview images. Use JPG, PNG, WebP or GIF.
Too small or too heavy. LinkedIn shows images under 401 pixels wide as a thumbnail and recommends 1200×627 at most 5 MB (LinkedIn: make your website shareable). An image around 1200×630 works on every network.
The image is blocked. The page loads in your browser, but the previewer's request for the image gets a 403, a login page or a bot challenge: password-protected previews, firewall bot rules, or hotlink protection on the image host.
Added by JavaScript. Previewers read the HTML the server sends and don't run scripts. A tag set at runtime in a single-page app never reaches them.
A cached card. LinkedIn and Facebook keep a preview for days. You fixed the tag, but the card still shows the old one until you ask them to fetch the page again.
name instead of property. The Open Graph spec uses property="og:image"; X's tags use name="twitter:image". Some previewers accept either, but not all, so follow the spec.

Check what the previewer gets

First the tag, from the raw HTML:

curl -s https://example.com/blog/post | grep -oE '<meta[^>]+(og|twitter):image[^>]*>'

Then the image itself: it should return 200 and an image content type, with no redirect to a login page.

curl -sI https://example.com/og/post.png | grep -iE '^(HTTP|content-type|content-length)'

The free SEO checker does both from a server, the way previewers do, and shows the LinkedIn, Facebook, Slack and X cards it would produce. After a fix, refresh the cached card in LinkedIn Post Inspector and the Facebook Sharing Debugger (Scrape Again).

Astro

Set site in astro.config.mjs to your production URL, then build the absolute URL in your layout with Astro.site:

---
// src/layouts/Base.astro
const { title, description, image = '/og/default.png' } = Astro.props;
const imageURL = new URL(image, Astro.site).href;
---
<head>
  <meta property="og:title" content={title} />
  <meta property="og:description" content={description} />
  <meta property="og:image" content={imageURL} />
  <meta name="twitter:card" content="summary_large_image" />
  <meta name="twitter:image" content={imageURL} />
</head>

Without site, Astro.site is undefined and new URL throws on a relative path, which is better than shipping a broken tag. Put shared images in public/ so their URL doesn't change between builds; an image imported through astro:assets gets a hashed file name, so pass its .src to new URL rather than writing the path by hand.

Starlight sets og:title, og:description and twitter:card but no image by default. Add one for every page with the head option:

starlight({
  title: 'My Docs',
  head: [
    { tag: 'meta', attrs: { property: 'og:image', content: 'https://docs.example.com/og.png' } },
  ],
})

Next.js (App Router)

Set metadataBase once in the root layout. Relative image paths in metadata are then resolved against it; without it, a relative path fails the build (Next.js: metadataBase).

// app/layout.tsx
export const metadata = {
  metadataBase: new URL('https://example.com'),
  openGraph: { images: '/og/default.png' },
}

The pitfall: metadata from layouts and pages is merged shallowly. A page that sets any openGraph field replaces the whole openGraph object from the layout, image included:

// app/blog/[slug]/page.tsx: this page loses the layout's og:image
export const metadata = {
  openGraph: { title: 'My post' },
}

Repeat the image in the page's openGraph, spread a shared object into it, or use the file convention: an opengraph-image.png (or .jpg) in a route folder applies to that route and the routes below it.

Hugo

Use Hugo's embedded templates in your <head>:

{{ partial "opengraph.html" . }}
{{ partial "twitter_cards.html" . }}

They take the image from the page's images front matter, then from a page resource whose name contains feature, cover or thumbnail, then from params.images in your site configuration (Hugo: embedded templates). Give the site a default:

# hugo.toml
baseURL = 'https://example.com/'
[params]
  images = ['og/default.png']

---
title: My post
images: ['og/my-post.png']
---

Absolute URLs are built from baseURL, so check it's the production address in the environment that deploys. Older themes call the templates as {{ template "_internal/opengraph.html" . }}; recent Hugo versions use the partial form shown above.

If the tag is right and the card still has no image

Open the image URL in a private window. If you see a login page, so does the previewer.
Check your host's bot protection and any password protection on the domain you shared.
Look for two og:image tags with different values, for example one from your theme and one from a plugin. Previewers usually take the first.
Ask LinkedIn and Facebook to fetch the page again. Slack and X also cache cards, so a link shared before the fix may keep its old preview.

Automating it with Headlark

Headlark's build step writes the link preview tags into each page's HTML after your build. For the image it's deliberately conservative:

It keeps your page's existing og:image if there is one, otherwise it picks the page's most representative image.
It makes the URL absolute from your --site-url and never uses an SVG or a data: URL, so a page whose only image is an SVG logo gets a small card.
It doesn't create images. If you want branded cards, generate them yourself and set og:image; Headlark then fills in the title, description and the rest around it.

Try it

The free plan covers one site and 25 pages. Add your site, copy its secret key, and your next build ships with SEO.