craftcms / anchors
Add anchor links to headings in your Craft CMS website content.
Installs: 30 413
Dependents: 0
Suggesters: 0
Security: 0
Stars: 48
Watchers: 8
Forks: 7
Open Issues: 2
Type:craft-plugin
Requires
- php: ^8.0.2
- craftcms/cms: ^4.0.0-RC2|^5.0.0-beta.1
Requires (Dev)
- craftcms/ecs: *
- craftcms/phpstan: dev-main
- craftcms/rector: dev-main
README
This plugin makes it possible to automatically add linkable anchors to HTML headings in Craft.
The anchors are named based on the heading text. The algorithm Anchors uses to convert the heading text to IDs is similar to Craft’s algorithm for automatically generating entry slugs.
Requirements
This plugin requires Craft CMS 4.0.0+ or 5.0.0+.
Installation
You can install this plugin from the Plugin Store or with Composer.
From the Plugin Store
Go to the Plugin Store in your project’s Control Panel and search for “Anchors”. Then click on the “Install” button in its modal window.
With Composer
Open your terminal and run the following commands:
# go to the project directory cd /path/to/my-project.test # tell Composer to load the plugin composer require craftcms/anchors # tell Craft to install the plugin ./craft install/plugin anchors
Templating
To use Anchors in your templates, just pass some HTML into the |anchors
filter.
{{ entry.body|anchors }}
By default, the anchors
filter will only search for <h1>
, <h2>
, and <h3>
tags. You can customize which tags it searches for by passing in a comma-separated list of tag names.
{{ entry.body|anchors('h2,h3') }}
The anchors
filter will convert any non-ASCII characters to ASCII, using the current site’s language’s ASCII character mappings by default.
If you are displaying content in a different language than the current site, use the language
argument to override which ASCII character mappings should be used:
{{ entry.body|anchors(language=entry.site.language) }}
By default, anchors
filter will lowercase words that are all uppercase and lowercase the first letter in any other case.
If you want the anchors to always be lowercase, you can use the lowercase
argument:
{{ entry.body|anchors(lowercase=true) }}
Configuration
To configure Anchors, create a new anchors.php
file within the config/
folder, which returns an array.
The following config settings are supported:
anchorClass
– The class name that should be given to named anchors. (Default isnull
, meaning no class will be given.)anchorLinkPosition
– The position that anchor links should have within headings, relative to the heading text ('before'
or'after'
). (Default is'after'
.)anchorLinkClass
– The class name that should be given to anchor links. (Default is'anchor'
.)anchorLinkText
– The visible text that anchor links should have. (Default is'#'
'.)anchorLinkTitleText
– The title/alt text that anchor links should have. If{heading}
is included, it will be replaced with the heading text the link is associated with. (Default is'Direct link to {heading}'
.)useAdditionalTagToAnchorTo
– Whether to render an additional tag above the heading and use it to scroll to when the anchor link is clicked. If set tofalse
, anchor id is added to the heading. (Default istrue
.)
Plugin API
Other plugins can take advantage of Anchors using the provided API.
$parsedHtml = \craft\anchors\Plugin::getInstance()->parser->parseHtml($html);
Like the |anchors
templating filter, parseHtml()
also allows you to specify which HTML tags should get anchors.
$parsedHtml = \craft\anchors\Plugin::getInstance()->parser->parseHtml($html, 'h2,h3');
You can also pass some heading text directly into Anchors to get its generated anchor name:
$anchorName = \craft\anchors\Plugin::getInstance()->parser->generateAnchorName($headingText);