bkry-code / footnotes Goto Github PK

This plugin extends Kirby CMS with some basic and extremely easy footnote functionalities. The syntax is simple to understand and if the plugin is removed the remaining text still makes sense.

Table of Contents

1. Requirements
2. Installation & Update
3. Usage
4. Options
5. Help & Improve
6. Version History

Requirements

Since version 1.0.0 the footnotes plugin requires Kirby CMS 2.3.0 or higher.
If you are running an older version of Kirby, please use version 0.9.0.

Installation & Update

1. Download Footnotes
2. Add to site/plugins/footnotes/
3. Add CSS for the footnotes (optional)
   .footnote: in-text reference mark, sup tag
   .footnotes: div wrapper for list of footnotes, ol list inside
   .footnotedivider: div element before the ol list

With the Kirby CLI

kirby plugin:install distantnative/footnotes

Usage

Use the footnotes method on the field: $page->text()->footnotes() or $page->text()->ft(). Adding footnotes to your Kirbytext field is simple. Just type them inline in your post in square brackets like this:

[^This is a footnote.]
[^ This is another.]

Each footnote must start with a caret (^) and will be numbered automatically. Footnotes can contain anything you want including links or images. Entries in the bibliography are automatically linking back to the spot in the text where the note was made.

“In a deterritorialized context, the conventional one-to-one 
relationship between state and territory is increasingly 
questioned and challenged” [^Wong, L. (2002): Home away from 
home? Abingdon: Routledge. Seite 171]

In-text reference mark:
Bibliography at the end of the text:

Notes:

• You should not include square brackets [] inside a footnote.

Footnotes without reference mark

To have a footnote/an information included in the bibliography, but without any reference mark inside the text, just prepend a ! to the footnote:

[^! **Photo credits:** (link:http://www.flickr.com/photos/cubagallery/ text:Cuba Gallery)]

Options

Remove footnotes

If you want show footnotes of a text field on specific pages (e.g. single blog article) but not on others (e.g. blog overview), you can add a parameter to the footnotes field method in e.g. templates/blog.php to remove all footnotes:

<?= $post->text()->footnotes(false) ?>
<?= $post->text()->footnotes(['convert' => false]) ?>

Separate bibliography output

If you do not want the bibliography to be appened right after the field text, you first have to deactivate thhe bibliography in the field method:

<?= $page->text()->footnotes(['bibliography' => false]) ?>

And then output the bibliography where wanted:

<?= KirbyFootnotes::bibliography($page->text()) ?>

Smooth scrolling

With the following options, you can enable a smooth scrolling effect to the bibliography as well as define a scroll speed and an offset to the scrolling position (e.g. if a fixed header menu is used). Add them to your site/config/config.php:

c::set('plugin.footnotes.scroll',        true);
c::set('plugin.footnotes.scroll.offset', 60);
c::set('plugin.footnotes.scroll.speed',  500);

Global footnotes

In addition to converting footnotes via the field method, you can set an option to activate it for all Kirbytext outputs globally. Add the following to your site/config/config.php:

c::set('plugin.footnotes.global', true);

Specific templates

Allowed
You can allow footnotes only on specific templates by adding the following to your site/config/config.php:

c::set('plugin.footnotes.templates.allow', array(
  'about',
  'blog',
  'project'
));

Ignored You can restrict footnotes from specific templates by adding the following to your site/config/config.php:

c::set('plugin.footnotes.templates.ignore', array(
  'about',
  'blog',
  'project'
));

Help & Improve

If you have any suggestions for further configuration options, please let me know.

Version history

You can find a more or less complete version history in the changelog.

License

MIT License

Author

Nico Hoffmann - https://nhoffmann.com