β Kirby Anchor-Headings by @wottpal
(Disclaimer: This is a pre-release.)
A field-method for the Kirby CMS which automagically enumerates your headings, generates IDs for them and inserts matching anchor links. Customizable to it's core.
Note: Please dive into this advanced use case if you want to build something like the GIF above.
Demos
- wottpal.com (my personal site)
- Submit yours
Installation
Use Kirby's CLI and install the plugin via: kirby plugin:install wottpal/kirby-anchor-headings or place the repo manually under site/plugins.
Usage
This is a kirby field-method, so you can basically just do:
<?= $page->text()->kirbytext()->headingAnchors() ?>Options
The following options can be set globally in your config.php with c::set($key, $value = null). You can also set multiple keys with c::set([$key => $value, ..]).
Please prefix every key with anchorheadings.!
| key | default | description |
|---|---|---|
toplevel.only |
true |
Nested headings are ignored. |
heading.min |
2 |
The <h>-level to begin enumeration. |
heading.max |
3 |
The <h>-level to end enumeration. |
enum.start |
1 |
Integer to start enumeration on each level. |
enum.seperator |
'.' |
Seperator for enumeration-levels. |
id.prefix |
false |
A string all IDs get prefixed with (before the enumeration). |
id.prepend.enum |
true |
If the enumeration should be part of the generated ID. |
id.rules |
(see below) | A dictionary of reg. expressions and their respective replacements. (They will be applied in the given order.) |
markup |
(see below) | A template-string which defines the new inner-markup of each heading-element |
Set id.prefix
Even if id.prefix defaults to false I encourage you to set it to something like section- to prevent namespace-conflicts all over your site.
Default of id.rules
You can either pass a regular expression as the replacement or a callback-function. They will be used with preg_replace_callback or preg_replace, respectively.
[
// characters to replace with an hyphen
'/[_ ~\/,.]/' => '-',
// replace German umlauts (YES, even the large Γ)
'/Γ€/' => 'ae', '/ΓΆ/' => 'oe', '/ΓΌ/' => 'ue',
'/Γ/' => 'Ae', '/Γ/' => 'Oe', '/Γ/' => 'Ue',
'/Γ/' => 'ss', '/αΊ/' => 'SS',
// remove all remaining characters that are not letters/digits
'/[^A-Za-z0-9\-]/' => '',
// remove trailing hyphens and squash multiple occurences
'/-+$/' => '',
'/-{2,}/' => '-',
// convert everything to lowercase (using a callback-function)
'/([A-Z]+)/' => function($x) { return strtolower($x[1]); }
]Default of markup
<a href='#{id}'>{enum}.</a> {heading}You can use the following template-literals in your markup: {id}, {enum} and {heading}. I think they are self-explanatory, but feel free to reach out if you need further guidance.
Advanced Markup & Styling
Changelog
Have a look at the releases page.
Roadmap
- Add an example with advanced markup & styling to the
README.md - Improve ID generation by collapsing consecutive '-' to one
- Allow non integer values for
enum.startlikeAoriand conitnue enumeration with this style.
π°β Pricing
Just kidding. This plugin is totally free. Please consider following me on Twitter if it saved your day.
You can also check out one of my other Kirby-plugins:
- Lightbox-Gallery - Easily inline beautifully aligned galleries with lightbox-support powered by PhotoSwipe.
- HTML5-Video Kirbytag - Adds a kirbytag for embedding HTML5-videos with a variety of features.