https://github.com/apostrophecms/anchors
https://github.com/apostrophecms/anchors
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/apostrophecms/anchors
- Owner: apostrophecms
- License: mit
- Created: 2021-12-10T15:29:07.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-10-01T18:27:03.000Z (8 months ago)
- Last Synced: 2025-10-22T18:48:39.245Z (8 months ago)
- Language: JavaScript
- Size: 39.1 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
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:
```bash
npm install @apostrophecms/anchors
```
## Usage
Configure the anchor modules in the `app.js` file:
```javascript
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.
```javascript
// modules/my-banner-widget/index.js
export default {
options: {
anchorAttribute: 'data-anchor'
}
};
```
In this example the wrapping `div` element would look like this:
```html
```
### `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.
```javascript
// 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](https://docs.apostrophecms.org/reference/field-types/slug.html#optional).
```javascript
// 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.
### Getting Started with Astro + ApostropheCMS
New to using ApostropheCMS with Astro? Check out our starter kits:
- **[starter-kit-astro-essentials](https://github.com/apostrophecms/starter-kit-astro-essentials)** - Essential features for most projects
- **[starter-kit-astro-apollo](https://github.com/apostrophecms/starter-kit-astro-apollo)** - Advanced features with Apollo integration
---