430 lines
12 KiB
Markdown
430 lines
12 KiB
Markdown
|
# Grav Prism Highlighter Plugin
|
||
|
|
|
||
|
|
`Prism Highlighter` is a [Grav](http://github.com/getgrav/grav) plugin that adds simple and powerful code highlighting functionality utilizing the [Prism.js](http://prismjs.com/) syntax highlighter.
|
||
|
|
|
||
|
|
# Installation
|
||
|
|
|
||
|
|
Installing the Highlight plugin can be done in one of two ways. Our GPM (Grav Package Manager) installation method enables you to quickly and easily install the plugin with a simple terminal command, while the manual method enables you to do so via a zip file.
|
||
|
|
|
||
|
|
## GPM Installation (Preferred)
|
||
|
|
|
||
|
|
The simplest way to install this plugin is via the [Grav Package Manager (GPM)](http://learn.getgrav.org/advanced/grav-gpm) through your system's Terminal (also called the command line). From the root of your Grav install type:
|
||
|
|
|
||
|
|
bin/gpm install prism-highlight
|
||
|
|
|
||
|
|
This will install the Highlight plugin into your `/user/plugins` directory within Grav. Its files can be found under `/your/site/grav/user/plugins/prism-highlight`.
|
||
|
|
|
||
|
|
## Manual Installation
|
||
|
|
|
||
|
|
To install this plugin, just download the zip version of this repository and unzip it under `/your/site/grav/user/plugins`. Then, rename the folder to `prism-highlight`. You can find these files either on [GitHub](https://github.com/getgrav/grav-plugin-prism-highlight) or via [GetGrav.org](http://getgrav.org/downloads/plugins#extras).
|
||
|
|
|
||
|
|
You should now have all the plugin files under
|
||
|
|
|
||
|
|
/your/site/grav/user/plugins/prism-highlight
|
||
|
|
|
||
|
|
|
||
|
|
# Languages included
|
||
|
|
|
||
|
|
Prism.js supports currently [176 languages](http://prismjs.com/#languages-list), at the time of this edit, but the ones included in this specific version are:
|
||
|
|
|
||
|
|
* markup
|
||
|
|
* html
|
||
|
|
* xml
|
||
|
|
* bbcode / shortcode
|
||
|
|
* svg
|
||
|
|
* mathml
|
||
|
|
* css
|
||
|
|
* css-extras
|
||
|
|
* clike
|
||
|
|
* javascript, js
|
||
|
|
* apacheconf
|
||
|
|
* bash, shell
|
||
|
|
* coffeescript, coffee
|
||
|
|
* diff
|
||
|
|
* docker, dockerfile
|
||
|
|
* git
|
||
|
|
* go
|
||
|
|
* java
|
||
|
|
* json
|
||
|
|
* json5
|
||
|
|
* less
|
||
|
|
* lua
|
||
|
|
* markdown, md
|
||
|
|
* php
|
||
|
|
* php-extras
|
||
|
|
* python, py
|
||
|
|
* regex
|
||
|
|
* ruby, rb
|
||
|
|
* sass
|
||
|
|
* scss
|
||
|
|
* sql
|
||
|
|
* twig
|
||
|
|
* yaml, yml
|
||
|
|
|
||
|
|
# Plugins Included
|
||
|
|
|
||
|
|
This build of Prism also includes the following plugins:
|
||
|
|
|
||
|
|
* Line Highlight
|
||
|
|
* Line Numbers
|
||
|
|
* Command Line
|
||
|
|
* Toolbar
|
||
|
|
* Copy to Clipboard
|
||
|
|
|
||
|
|
# Basic Usage
|
||
|
|
|
||
|
|
In your markdown, you can create a block of code, and assign the language to it. You can choose between the list above.
|
||
|
|
|
||
|
|
Example using regular markdown fenced code syntax:
|
||
|
|
|
||
|
|
```php
|
||
|
|
```php
|
||
|
|
<?php
|
||
|
|
|
||
|
|
namespace Grav\Plugin;
|
||
|
|
|
||
|
|
use \Grav\Common\Plugin;
|
||
|
|
use \Grav\Common\Grav;
|
||
|
|
use \Grav\Common\Page\Page;
|
||
|
|
|
||
|
|
class PrismHighlightPlugin extends Plugin
|
||
|
|
{
|
||
|
|
/**
|
||
|
|
* @return array
|
||
|
|
*/
|
||
|
|
public static function getSubscribedEvents()
|
||
|
|
{
|
||
|
|
return [
|
||
|
|
'onPageInitialized' => ['onPageInitialized', 0],
|
||
|
|
'onShortcodeHandlers' => ['onShortcodeHandlers', 0],
|
||
|
|
'onTwigTemplatePaths' => ['onTwigTemplatePaths', 0],
|
||
|
|
];
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
# Advanced Usage
|
||
|
|
|
||
|
|
To get access to advanced options that can be set individually, you can use the included `[prism][/prism]` shortcode:
|
||
|
|
|
||
|
|
For line numbers:
|
||
|
|
|
||
|
|
```
|
||
|
|
[prism classes="language-twig line-numbers"]
|
||
|
|
{% set payload = {frontmatter: page.header, content: page.content} %}
|
||
|
|
{{ payload|json_encode|raw }}
|
||
|
|
[/prism]
|
||
|
|
```
|
||
|
|
|
||
|
|
You can also now add the `linkable-line-numbers` class to make the line numbers directly linkable. You need to provide an `id` on the Prism element so that there is something to link against.
|
||
|
|
|
||
|
|
For example:
|
||
|
|
|
||
|
|
```
|
||
|
|
[prism classes="language-twig line-numbers linkable-line-numbers" id="twig-example"]
|
||
|
|
{% set payload = {frontmatter: page.header, content: page.content} %}
|
||
|
|
{{ payload|json_encode|raw }}
|
||
|
|
[/prism]
|
||
|
|
```
|
||
|
|
|
||
|
|
For a command Prompt:
|
||
|
|
|
||
|
|
If you don't provide a custom prompt, it will default to `$` for the command prompt. Provide a custom prompt with the `cl-prompt` attribute.
|
||
|
|
|
||
|
|
```
|
||
|
|
[prism classes="language-bash command-line" cl-prompt="\[foo@localhost\] $"]
|
||
|
|
cd ~/webroot
|
||
|
|
git clone -b master https://github.com/getgrav/grav.git
|
||
|
|
[/prism]
|
||
|
|
```
|
||
|
|
|
||
|
|
You can also specify certain lines as output (won't be prefixed by prompt) using the `cl-output` attribute:
|
||
|
|
|
||
|
|
```
|
||
|
|
[prism classes="language-bash command-line" cl-prompt="[root@localhost]" cl-output="2-6"]
|
||
|
|
ls -la
|
||
|
|
total 2
|
||
|
|
drwxr-xr-x 2 chris chris 11 Jan 10 16:48 .
|
||
|
|
drwxr--r-x 45 chris chris 92 Feb 14 11:10 ..
|
||
|
|
-rwxr-xr-x 1 chris chris 444 Aug 25 2013 backup
|
||
|
|
-rwxr-xr-x 1 chris chris 642 Jan 17 14:42 deploy
|
||
|
|
[/prism]
|
||
|
|
```
|
||
|
|
|
||
|
|
Alternatively you can use the `cl-filter-putput` to provide a lines with a specific prefix to filter out. For example:
|
||
|
|
|
||
|
|
```
|
||
|
|
[prism classes="language-bash command-line" cl-prompt="[root@localhost]" cl-filter-output=">>"]
|
||
|
|
ls -la
|
||
|
|
>>total 2
|
||
|
|
>>drwxr-xr-x 2 chris chris 11 Jan 10 16:48 .
|
||
|
|
>>drwxr--r-x 45 chris chris 92 Feb 14 11:10 ..
|
||
|
|
>>-rwxr-xr-x 1 chris chris 444 Aug 25 2013 backup
|
||
|
|
>>-rwxr-xr-x 1 chris chris 642 Jan 17 14:42 deploy
|
||
|
|
[/prism]
|
||
|
|
```
|
||
|
|
|
||
|
|
For highlighting specific lines 2 and 4:
|
||
|
|
|
||
|
|
```
|
||
|
|
[prism classes="language-yaml" highlight="2,4"]
|
||
|
|
enabled: true
|
||
|
|
theme: prism-base16-ocean.dark.css
|
||
|
|
all-pre-blocks: true
|
||
|
|
plugins:
|
||
|
|
line-numbers: false
|
||
|
|
command-line: false
|
||
|
|
command-line-prompt: '$'
|
||
|
|
[/prism]
|
||
|
|
```
|
||
|
|
|
||
|
|
Find out more about these options by checking out the [Prism.js plugins page](https://prismjs.com/#plugins).
|
||
|
|
|
||
|
|
|
||
|
|
# Git File Support
|
||
|
|
|
||
|
|
If you provide a `git="<url>"` parameter in the shortcode, the plugin will try to retrieve the 'raw' version of this file. For example:
|
||
|
|
|
||
|
|
```
|
||
|
|
[prism git="https://github.com/getgrav/grav/blob/develop/system/router.php" classes="language-php line-numbers linkable-line-numbers" id="grav-router"]
|
||
|
|
[/prism]
|
||
|
|
```
|
||
|
|
|
||
|
|
You can also provide the **raw** version directly:
|
||
|
|
|
||
|
|
```
|
||
|
|
[prism git="https://raw.githubusercontent.com/getgrav/grav/develop/system/router.php" classes="language-php line-numbers linkable-line-numbers" id="grav-router"]
|
||
|
|
[/prism]
|
||
|
|
```
|
||
|
|
|
||
|
|
You can also slice the file to only show specific lines by passing a query parameter to the URL:
|
||
|
|
|
||
|
|
* `slice=0:-2` Show the first line up to and including the second to last line
|
||
|
|
* `slice=24:100` Show lines 24 through 100
|
||
|
|
* `slice=0` Show only the first line of the file
|
||
|
|
|
||
|
|
```
|
||
|
|
[prism git="https://github.com/getgrav/grav/blob/develop/system/router.php?slice=10:18" classes="language-php line-numbers linkable-line-numbers" id="grav-router"]
|
||
|
|
[/prism]
|
||
|
|
```
|
||
|
|
|
||
|
|
# Configuration
|
||
|
|
|
||
|
|
Configuration shall be set in `config/plugins/prism-highlight.yaml`.
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
enabled: true
|
||
|
|
theme: prism-base16-ocean.dark.css
|
||
|
|
all-pre-blocks: true
|
||
|
|
plugins:
|
||
|
|
line-numbers: false
|
||
|
|
command-line: false
|
||
|
|
command-line-prompt: '$'
|
||
|
|
```
|
||
|
|
|
||
|
|
You can also override configuration settings at the page level by prefixing options with `prism-highlight:`. For example you could set a different theme, and turning on line numbers on a particular page with:
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
title: My Page
|
||
|
|
prism-highlight:
|
||
|
|
theme: base16-duotone-dark.light.css
|
||
|
|
plugins:
|
||
|
|
line-numbers: true
|
||
|
|
```
|
||
|
|
|
||
|
|
|
||
|
|
### Themes
|
||
|
|
|
||
|
|
The themes available are:
|
||
|
|
|
||
|
|
```
|
||
|
|
base16-duotone-dark.dark.css
|
||
|
|
base16-duotone-dark.light.css
|
||
|
|
base16-duotone-darkdesert.dark.css
|
||
|
|
base16-duotone-darkearth.dark.css
|
||
|
|
base16-duotone-darkearth.light.css
|
||
|
|
base16-duotone-darkforest.dark.css
|
||
|
|
base16-duotone-darkforest.light.css
|
||
|
|
base16-duotone-darkpark.dark.css
|
||
|
|
base16-duotone-darkpool.dark.css
|
||
|
|
base16-duotone-darkpool.light.css
|
||
|
|
base16-duotone-darksea.dark.css
|
||
|
|
base16-duotone-darksea.light.css
|
||
|
|
base16-duotone-darkspace.dark.css
|
||
|
|
base16-duotone-darkspace.light.css
|
||
|
|
prism-a11y-dark.css
|
||
|
|
prism-atelier-cave-dark.css
|
||
|
|
prism-atelier-cave-light.css
|
||
|
|
prism-atelier-dune-dark.css
|
||
|
|
prism-atelier-dune-light.css
|
||
|
|
prism-atelier-estuary-dark.css
|
||
|
|
prism-atelier-estuary-light.css
|
||
|
|
prism-atelier-forest-dark.css
|
||
|
|
prism-atelier-forest-light.css
|
||
|
|
prism-atelier-heath-dark.css
|
||
|
|
prism-atelier-heath-light.css
|
||
|
|
prism-atelier-lakeside-dark.css
|
||
|
|
prism-atelier-lakeside-light.css
|
||
|
|
prism-atelier-plateau-dark.css
|
||
|
|
prism-atelier-plateau-light.css
|
||
|
|
prism-atelier-savanna-dark.css
|
||
|
|
prism-atelier-savanna-light.css
|
||
|
|
prism-atelier-seaside-dark.css
|
||
|
|
prism-atelier-seaside-light.css
|
||
|
|
prism-atelier-sulphurpool-dark.css
|
||
|
|
prism-atelier-sulphurpool-light.css
|
||
|
|
prism-atom-dark.css
|
||
|
|
prism-base16-3024.dark.css
|
||
|
|
prism-base16-3024.light.css
|
||
|
|
prism-base16-apathy.dark.css
|
||
|
|
prism-base16-apathy.light.css
|
||
|
|
prism-base16-ashes.dark.css
|
||
|
|
prism-base16-ashes.light.css
|
||
|
|
prism-base16-ateliercave.dark.css
|
||
|
|
prism-base16-ateliercave.light.css
|
||
|
|
prism-base16-atelierdune.dark.css
|
||
|
|
prism-base16-atelierdune.light.css
|
||
|
|
prism-base16-atelierestuary.dark.css
|
||
|
|
prism-base16-atelierestuary.light.css
|
||
|
|
prism-base16-atelierforest.dark.css
|
||
|
|
prism-base16-atelierforest.light.css
|
||
|
|
prism-base16-atelierheath.dark.css
|
||
|
|
prism-base16-atelierheath.light.css
|
||
|
|
prism-base16-atelierlakeside.dark.css
|
||
|
|
prism-base16-atelierlakeside.light.css
|
||
|
|
prism-base16-atelierplateau.dark.css
|
||
|
|
prism-base16-atelierplateau.light.css
|
||
|
|
prism-base16-ateliersavanna.dark.css
|
||
|
|
prism-base16-ateliersavanna.light.css
|
||
|
|
prism-base16-atelierseaside.dark.css
|
||
|
|
prism-base16-atelierseaside.light.css
|
||
|
|
prism-base16-ateliersulpherpool.dark.css
|
||
|
|
prism-base16-ateliersulpherpool.light.css
|
||
|
|
prism-base16-ateliersulphurpool.dark.css
|
||
|
|
prism-base16-ateliersulphurpool.light.css
|
||
|
|
prism-base16-bespin.dark.css
|
||
|
|
prism-base16-bespin.light.css
|
||
|
|
prism-base16-brewer.dark.css
|
||
|
|
prism-base16-brewer.light.css
|
||
|
|
prism-base16-bright.dark.css
|
||
|
|
prism-base16-bright.light.css
|
||
|
|
prism-base16-chalk.dark.css
|
||
|
|
prism-base16-chalk.light.css
|
||
|
|
prism-base16-codeschool.dark.css
|
||
|
|
prism-base16-codeschool.light.css
|
||
|
|
prism-base16-colors.dark.css
|
||
|
|
prism-base16-colors.light.css
|
||
|
|
prism-base16-default.dark.css
|
||
|
|
prism-base16-default.light.css
|
||
|
|
prism-base16-eighties.dark.css
|
||
|
|
prism-base16-eighties.light.css
|
||
|
|
prism-base16-embers.dark.css
|
||
|
|
prism-base16-embers.light.css
|
||
|
|
prism-base16-flat.dark.css
|
||
|
|
prism-base16-flat.light.css
|
||
|
|
prism-base16-google.dark.css
|
||
|
|
prism-base16-google.light.css
|
||
|
|
prism-base16-grayscale.dark.css
|
||
|
|
prism-base16-grayscale.light.css
|
||
|
|
prism-base16-greenscreen.dark.css
|
||
|
|
prism-base16-greenscreen.light.css
|
||
|
|
prism-base16-harmonic16.dark.css
|
||
|
|
prism-base16-harmonic16.light.css
|
||
|
|
prism-base16-hopscotch.dark.css
|
||
|
|
prism-base16-hopscotch.light.css
|
||
|
|
prism-base16-isotope.dark.css
|
||
|
|
prism-base16-isotope.light.css
|
||
|
|
prism-base16-londontube.dark.css
|
||
|
|
prism-base16-londontube.light.css
|
||
|
|
prism-base16-marrakesh.dark.css
|
||
|
|
prism-base16-marrakesh.light.css
|
||
|
|
prism-base16-mocha.dark.css
|
||
|
|
prism-base16-mocha.light.css
|
||
|
|
prism-base16-monokai.dark.css
|
||
|
|
prism-base16-monokai.light.css
|
||
|
|
prism-base16-ocean.dark.css
|
||
|
|
prism-base16-ocean.light.css
|
||
|
|
prism-base16-paraiso.dark.css
|
||
|
|
prism-base16-paraiso.light.css
|
||
|
|
prism-base16-pop.dark.css
|
||
|
|
prism-base16-pop.light.css
|
||
|
|
prism-base16-railscasts.dark.css
|
||
|
|
prism-base16-railscasts.light.css
|
||
|
|
prism-base16-shapeshifter.dark.css
|
||
|
|
prism-base16-shapeshifter.light.css
|
||
|
|
prism-base16-solarized.dark.css
|
||
|
|
prism-base16-solarized.light.css
|
||
|
|
prism-base16-summerfruit.dark.css
|
||
|
|
prism-base16-summerfruit.light.css
|
||
|
|
prism-base16-tomorrow.dark.css
|
||
|
|
prism-base16-tomorrow.light.css
|
||
|
|
prism-base16-twilight.dark.css
|
||
|
|
prism-base16-twilight.light.css
|
||
|
|
prism-base2tone-cave-dark.css
|
||
|
|
prism-base2tone-cave-light.css
|
||
|
|
prism-base2tone-desert-dark.css
|
||
|
|
prism-base2tone-desert-light.css
|
||
|
|
prism-base2tone-drawbridge-dark.css
|
||
|
|
prism-base2tone-drawbridge-light.css
|
||
|
|
prism-base2tone-earth-dark.css
|
||
|
|
prism-base2tone-earth-light.css
|
||
|
|
prism-base2tone-evening-dark.css
|
||
|
|
prism-base2tone-evening-light.css
|
||
|
|
prism-base2tone-forest-dark.css
|
||
|
|
prism-base2tone-forest-light.css
|
||
|
|
prism-base2tone-heath-dark.css
|
||
|
|
prism-base2tone-heath-light.css
|
||
|
|
prism-base2tone-lake-dark.css
|
||
|
|
prism-base2tone-lake-light.css
|
||
|
|
prism-base2tone-meadow-dark.css
|
||
|
|
prism-base2tone-meadow-light.css
|
||
|
|
prism-base2tone-morning-dark.css
|
||
|
|
prism-base2tone-morning-light.css
|
||
|
|
prism-base2tone-pool-dark.css
|
||
|
|
prism-base2tone-pool-light.css
|
||
|
|
prism-base2tone-sea-dark.css
|
||
|
|
prism-base2tone-sea-light.css
|
||
|
|
prism-base2tone-space-dark.css
|
||
|
|
prism-base2tone-space-light.css
|
||
|
|
prism-base2tone-suburb-dark.css
|
||
|
|
prism-base2tone-suburb-light.css
|
||
|
|
prism-cb.css
|
||
|
|
prism-coldark-cold.css
|
||
|
|
prism-coldark-dark.css
|
||
|
|
prism-coy-without-shadows.css
|
||
|
|
prism-coy.css
|
||
|
|
prism-darcula.css
|
||
|
|
prism-dark.css
|
||
|
|
prism-dracula.css
|
||
|
|
prism-duotone-dark.css
|
||
|
|
prism-duotone-earth.css
|
||
|
|
prism-duotone-forest.css
|
||
|
|
prism-duotone-light.css
|
||
|
|
prism-duotone-sea.css
|
||
|
|
prism-duotone-space.css
|
||
|
|
prism-funky.css
|
||
|
|
prism-ghcolors.css
|
||
|
|
prism-gruvbox-dark.css
|
||
|
|
prism-hopscotch.css
|
||
|
|
prism-lucario.css
|
||
|
|
prism-material-dark.css
|
||
|
|
prism-material-light.css
|
||
|
|
prism-material-oceanic.css
|
||
|
|
prism-night-owl.css
|
||
|
|
prism-nord.css
|
||
|
|
prism-okaidia.css
|
||
|
|
prism-pojoaque.css
|
||
|
|
prism-shades-of-purple.css
|
||
|
|
prism-solarizedlight.css
|
||
|
|
prism-synthwave84.css
|
||
|
|
prism-tomorrow.css
|
||
|
|
prism-twilight.css
|
||
|
|
prism-vs.css
|
||
|
|
prism-vsc-dark-plus.css
|
||
|
|
prism-xonokai.css
|
||
|
|
```
|
||
|
|
|
||
|
|
Check out a [live test](http://prismjs.com/test.html) or a [live demo](http://prismjs.com/index.html#examples).
|
||
|
|
|
||
|
|
|