s1syphos/kirby-pep

Supercharging Parsedown with ParsedownExtraPlugin for Kirby

Kirby P(arsedown)E(xtra)P(lugin)

, _(*1)

This plugin modifies Kirby's markdown component and enhances the built-in markdown parser ParsedownExtra by adding some PEP., _(*2)

Table of contents - 1. What's MarkdownExtra? - 2. Getting started - 3. Configuration - 4. Troubleshooting - 5. Credits / License, _(*3)

What's MarkdownExtra?

Markdown Extra is an extension to PHP Markdown implementing some features currently not available with the plain Markdown syntax [such as] - Inline HTML - Markdown Inside HTML Blocks - Special Attributes - Fenced Code Blocks - Tables - Definition Lists - Footnotes - Output - Abbreviations - Ordered Lists - Emphasis - Backslash Escapes, _(*4)

By Michel Fortin, _(*5)

While these are already nice to have, PEP takes global configurability just a bit further - because Markdown!, _(*6)

Getting started

Use one of the following methods to install & use kirby-pep:, _(*7)

Git submodule

If you know your way around Git, you can download this plugin as a submodule:, _(*8)

git submodule add https://github.com/S1SYPHOS/kirby-pep.git site/plugins/kirby-pep

Composer

composer require S1SYPHOS/kirby-pep

Clone or download

1. Clone or download this repository.
2. Unzip / Move the folder to site/plugins.

Activate the plugin

Activate the plugin with the following line in your config.php:, _(*9)

c::set('plugin.kirby-pep', true);

In order to enable features of ParsedownExtraPlugin, read on about configuring it. If you want to activate kirby-pep only on specific domains, read about multi-environment setups., _(*10)

Configuration

Change kirby-pep options to suit your needs:, _(*11)

• Element prefix (HTML / XHTML)
  • 'element_suffix' => '>' // HTML5
• Predefined abbreviations
  • 'abbreviations' => []
• Predefined links
  • 'links' => null
• Custom attributes for (external) links / images
  • 'links_attr' => []
  • 'links_external_attr' => ['rel' => 'nofollow', 'target' => '_blank']
  • 'images_attr' => null
  • 'images_external_attr' => null
• Custom code class / (block) text
  • 'code_class' => 'language-%s'
  • 'code_text' => null
  • 'code_block_text' => null
• Putting <code> attributes on <pre> element
  • 'code_block_attr_on_parent' => false
• Custom table (alignment) class
  • 'table_class' => null
  • 'table_align_class' => null
• Custom footnote class
  • 'footnote_class' => 'footnotes'
• Custom footnote link id / class / text
  • 'footnote_link_id' => 'fnref:%s'
  • 'footnote_link_class' => 'footnote-ref'
  • 'footnote_link_text' => '[%s]'
• Custom footnote back link id / class / text
  • 'footnote_back_link_id' => 'fnref:%s-%s'
  • 'footnote_back_link_class' => 'footnote-backref'
  • 'footnote_back_link_text' => '↩'

If you'd like to change them, just prefix each option with plugin.kirby-pep. in your config.php and you're set! With the following option in place, this plugin integrates seemlessly with kirby-highlight, generating themeable server-side syntax highlighting for Kirby:, _(*12)

c::set('plugin.kirby-pep.code_class', 'language-%s hljs');

These examples are a good starting point, too., _(*13)

Troubleshooting

Custom attributes for (external) links / images currently don't work - feel free to submit a PR with your solution!, _(*14)

Credits / License

kirby-pep is based on Taufik Nurrohman's parsedown-extra-plugin library (an extension to ParsedownExtra). It is licensed under the MIT License, but using Kirby in production requires you to buy a license. Are you ready for the next step?, _(*15)

Special Thanks

I'd like to thank everybody that's making great software - you people are awesome. Also I'm always thankful for feedback and bug reports :), _(*16)