85 lines
3.1 KiB
Markdown
85 lines
3.1 KiB
Markdown
# Grav Anchors Plugin
|
|
|
|
|
|
`anchors` is a [Grav](http://github.com/getgrav/grav) plugin that provides automatic header anchors via the [anchorjs](http://bryanbraun.github.io/anchorjs) jQuery plugin.
|
|
|
|
# Installation
|
|
|
|
## GPM Installation (Preferred)
|
|
|
|
The simplest way to install this plugin is via the [Grav Package Manager (GPM)](http://learn.getgrav.org/advanced/grav-gpm). From the root of your Grav install type:
|
|
|
|
bin/gpm install anchors
|
|
|
|
## Manual Installation
|
|
|
|
If for some reason you can't use GPM you can manually install this plugin. Download the zip version of this repository and unzip it under `/your/site/grav/user/plugins`. Then, rename the folder to `anchors`.
|
|
|
|
You should now have all the plugin files under
|
|
|
|
/your/site/grav/user/plugins/anchors
|
|
|
|
# Usage
|
|
|
|
To best understand how Anchors works, you should read through the original [project documentation](https://github.com/bryanbraun/anchorjs).
|
|
|
|
## Configuration:
|
|
|
|
Simply copy the `user/plugins/breadcrumbs/anchors.yaml` into `user/config/plugins/anchors.yaml` and make your modifications.
|
|
|
|
enabled: true # enable or disable the plugin
|
|
active: true # active by default, if false then you must activate per-page
|
|
selectors: 'h1,h2,h3,h4' # css elements to activate on. Uses jQuery style selectors
|
|
placement: right # either "left" or "right"
|
|
visible: hover # Active on "hover" or "always" visible
|
|
icon: # default link or a specific character like: #, ¶, ❡, and §.
|
|
class: # adds the provided class to the anchor html
|
|
truncate: 64 # truncates the generated ID to the specified character length
|
|
|
|
You can override any default settings from the page headers:
|
|
|
|
eg:
|
|
|
|
---
|
|
title: Sample Code With Custom Theme
|
|
anchors:
|
|
active: true
|
|
selectors: .blog h1, .blog h2
|
|
---
|
|
|
|
# Header
|
|
|
|
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas accumsan porta diam,
|
|
nec sagittis odio euismod nec. Etiam eu rutrum eros.
|
|
|
|
## Sub Header
|
|
|
|
Proin commodo lobortis elementum.
|
|
Integer vel ultrices massa, nec ornare urna. Phasellus tincidunt rutrum dolor, vestibulum
|
|
faucibus ligula laoreet id. Donec hendrerit arcu vitae lacus mattis facilisis. Praesent
|
|
tortor nibh, pulvinar nec orci ac, rhoncus pharetra nunc.
|
|
|
|
|
|
You can also disable anchors for a particular page if causes issues:
|
|
|
|
---
|
|
title: Sample Code with Highlight disabled
|
|
anchors:
|
|
active: false
|
|
---
|
|
|
|
# Header
|
|
|
|
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas accumsan porta diam,
|
|
nec sagittis odio euismod nec. Etiam eu rutrum eros.
|
|
|
|
## Sub Header
|
|
|
|
Proin commodo lobortis elementum.
|
|
Integer vel ultrices massa, nec ornare urna. Phasellus tincidunt rutrum dolor, vestibulum
|
|
faucibus ligula laoreet id. Donec hendrerit arcu vitae lacus mattis facilisis. Praesent
|
|
tortor nibh, pulvinar nec orci ac, rhoncus pharetra nunc.
|
|
|
|
|
|
> Note: If you want to see this plugin in action, have a look at [Grav Learn Site](http://learn.getgrav.org)
|