EditMD
Edit on GitHubLink to Markdown

astro-refs

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.1.0 --npm

Installation

$ npm install astro-refs

Setup

Register the integration

In astro.config.ts:

import astroRefs from 'astro-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-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 — inside prose, tables, admonitions, or step text. 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

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