For AI agents: The complete documentation index is available at /llms.txt. A markdown version of this page is available at /build-tools/refs.md.

Anchor References

On this page

Named cross-references for Astro. Declare an anchor anywhere in your content, link to it by name from anywhere else in the site. Links stay valid even when content moves, because the name travels with the content.

Current version: 0.2.1 --npm

Installation

$ npm install astro-better-refs

Setup

Register the integration

In astro.config.ts:

import astroRefs from 'astro-better-refs';

export default defineConfig({
  integrations: [
    astroRefs({
      collections: [
        { src: 'src/content/docs', base: '/docs' },
      ],
    }),
  ],
});

Declare refs in your content

You can declare a ref in any of the following ways:

  • Frontmatter

    ---
    ref: my-page-name
    ---
    
  • Section heading suffix

    ## Jumbo Potatoes {potato-section}
    

    The {potato-section} suffix is stripped from the rendered heading.

  • <Ref> component

    import Ref from 'astro-better-refs/Ref.astro';
    <Ref id="my-anchor" />
    

Use the ref: URL scheme anywhere you write a link:

[See the potato section](ref:potato-section)
[Jump to the heading suffix docs](ref:section-heading-suffix)

Refs work anywhere a Markdown link does. The target doesn’t have to be a heading; a <Ref> placed anywhere in the page works just as well.

Live example

The following example targets a <Ref> component placed just before the “Section heading suffix” option in the Setup section, showing how you can link anywhere in your content, not just to headers and pages:

Integration options

OptionTypeDescription
collections{src, base}[]Content directories to scan for ref declarations

Use with Sätteri

When markdown.processor is a Sätteri processor, the integration adds its Sätteri plugin to that processor instead of building a unified one. The same setup works unchanged.

To cover MDX as well, or to share one ref map across several processors, pass a state object to the integration and add the plugin yourself. The integration then only scans and reports:

astro.config.ts
import mdx from '@astrojs/mdx';
import { satteri } from '@astrojs/markdown-satteri';
import astroRefs from 'astro-better-refs';
import { refs } from 'astro-better-refs/satteri';

const state = { refMap: null, brokenRefs: [], duplicates: [] };
const processor = satteri({ mdastPlugins: [refs({ state })] });

export default defineConfig({
  markdown: { processor },
  integrations: [
    mdx({ processor }),
    astroRefs({ collections: [{ src: 'src/content/docs', base: '/docs' }], state }),
  ],
});

With unified, the same pattern uses remarkAstroRef from astro-better-refs.

Ref component props

PropTypeDescription
idstringThe ref name to declare at this location
Multiple aliases

A page can declare multiple ref names in frontmatter:

---
refs:
  - my-page-name
  - legacy-name
---