# astro-refs

Sphinx-style named anchors that survive content moves.

> For the index of this section of the site, see [llms.txt](https://lambdalatitudinarians.org/llms.txt)

# 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](https://www.npmjs.com/package/astro-refs)

## Installation

```shell-session
$ npm install astro-refs
```

## Setup

### Register the integration

In `astro.config.ts`:

```typescript
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**
    
    ```yaml
    ---
    ref: my-page-name
    ---
    ```
    
*   **Section heading suffix**
    
    ```markdown
    ## Jumbo Potatoes {potato-section}
    ```
    
    The `{potato-section}` suffix is stripped from the rendered heading.
    
*   **`<Ref>` component**
    
    ```jsx
    import Ref from 'astro-refs/Ref.astro';
    <Ref id="my-anchor" />
    ```
    

### Link by name

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

```markdown
[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:

*   [ref:section-heading-suffix](https://lambdalatitudinarians.org/docs/build-tools/refs.md#section-heading-suffix)

## Integration options

| Option | Type | Description |
| --- | --- | --- |
| `collections` | `{src, base}[]` | Content directories to scan for ref declarations |

## `Ref` component props

| Prop | Type | Description |
| --- | --- | --- |
| `id` | `string` | The ref name to declare at this location |

Multiple aliases

A page can declare multiple ref names in frontmatter:

```yaml
---
refs:
  - my-page-name
  - legacy-name
---
```