@apostrophecms/anchors

Apostrophe Anchors

Enable deep linking and smooth navigation with automatic anchor generation for all ApostropheCMS widgets. Perfect for landing pages, documentation sites, and content-heavy applications where users need to link directly to specific sections.

Why Apostrophe Anchors?

• 🎯 Improve User Experience: Let visitors bookmark and share links to specific content sections
• 📈 Boost SEO: Search engines can index and link directly to your content sections
• ⚡ Zero Configuration: Works automatically with all widget types out of the box
• 🛠️ Developer Friendly: Customize anchor attributes and disable for specific widgets as needed
• 🔗 Marketing Ready: Perfect for campaign landing pages where you need to link to specific sections

Installation

To install the module, use the command line to run this command in an Apostrophe project's root directory:

npm install @apostrophecms/anchors

Usage

Configure the anchor modules in the app.js file:

import apostrophe from 'apostrophe';

apostrophe ({
  root: import.meta,
  shortName: 'my-project',
  modules: {
    '@apostrophecms/anchors': {},
  }
});

When the modules are active, all widget types will have a new "HTML Anchor Value" field. When an editor populates that field with a slug-style string, the widget HTML markup will be wrapped with a new div with an attribute (an id by default) set to the anchor value. This attribute can be targeted by anchor links, e.g., href="#anchor-id-value".

The only Apostrophe core widget type with this feature disabled is the rich text widget, @apostrophecms/rich-text-widget.

The "HTML Anchor Value" field is a "slug" type field, which means it is limited to lowercase characters and dashes for consistent usage.

Configuration Options

anchorAttribute

By default, the anchor attribute is an id. This makes it easy to link to the widget with a hash href matching the anchor value as described above. Developers have the option to use another anchor attribute if they prefer to target the HTML element with custom JavaScript instead.

To do this, include an anchorAttribute option on the individual widget type. You can also add this option on the root @apostrophecms/widget-type module or the @apostrophecms/anchors-widget-type module to set this for all widget types.

// modules/my-banner-widget/index.js
export default {
  options: {
    anchorAttribute: 'data-anchor'
  }
};

In this example the wrapping div element would look like this:

<div data-anchor="anchor-id-value">
  <!-- Normal widget markup here -->
</div>

anchors: false

Developers can choose to disable this module's features for any widget type by setting an anchors: false option on the widget type.

// modules/my-banner-widget/index.js
export default {
  options: {
    anchors: false
  }
};

This is automatically set for the rich text widget. That can be reversed by setting anchors: true on @apostrophecms/rich-text-widget.

anchorDefault

To help content editors populate anchor values automatically, set the anchorDefault option to the name of an existing field on a widget type. The "HTML Anchor Value" field will populate automatically based on the value of the named field using the following field option mechanism.

// modules/my-banner-widget/index.js
export default {
  options: {
    anchorDefault: 'heading'
  },
  fields: {
    add: {
      heading: {
        type: 'string',
        label: 'Heading'
      }
    }
  }
};

Use Cases

Landing Pages: Create marketing pages where different sections can be linked to directly from emails, ads, or social media.

Documentation: Allow readers to bookmark and share links to specific sections of your documentation.

Long-form Content: Help readers navigate lengthy articles or reports by providing direct links to sections.

Campaign Pages: Enable marketing campaigns to link directly to specific product features or testimonials.

Usage with Astro (Headless)

⚠️ Current Limitation: The configuration options described above (like anchorAttribute, anchors: false, and anchorDefault) are not currently passed through to headless frontends like Astro. These options only work in traditional ApostropheCMS projects. We're working on improving this integration.

When using ApostropheCMS as a headless CMS with an Astro frontend, you can still implement anchor functionality by manually handling the anchor data in your Astro components. You can also pass options to individual widgets on a per-area basis, but you will have to alter the code examples below to handle these options.

Step 1: Create the WidgetWrapper Component

In your Astro frontend, create components/WidgetWrapper.astro with the following content:

---
const { widget } = Astro.props;

const hasAnchor = widget?.anchorId;
---

{
  hasAnchor ? (
    <div id={widget.anchorId}>
      <slot />
    </div>
  ) : (
    <slot />
  )
}

Step 2: Wrap Your Widget Components

Then go to your widget components (e.g., widgets/ImageWidget.astro) and wrap their existing content with the WidgetWrapper:

// Before
---
<Figure {image} {link} caption={widget.caption} {style} />

// After
---
import WidgetWrapper from '../components/WidgetWrapper.astro';
---
<WidgetWrapper {widget}>
  <Figure {image} {link} caption={widget.caption} {style} />
</WidgetWrapper>

Benefits of this approach:

• No overhead when widgets don't contain anchor data (no artificial wrappers)
• You can add additional project-specific functionality and options to WidgetWrapper.astro
• Minimizes boilerplate code and provides a single source of truth for common widget logic

Getting Started with Astro + ApostropheCMS

New to using ApostropheCMS with Astro? Check out our starter kits:

• starter-kit-astro-essentials - Essential features for most projects
• starter-kit-astro-apollo - Advanced features with Apollo integration

Made with ❤️ by the ApostropheCMS team. Found this useful? Give us a star on GitHub! ⭐

Changelog

1.0.2 (2025-08-06)

• README updates.
• Test with supported Node.js and MongoDB versions.