`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:
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.
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:
To customize the Prism you will need to customize the `prism.js` file. This requires cloning our Forked repository (it contains some extra languages and styling tweaks) from: https://github.com/getgrav/prism
Then run the following commands:
```shell
npm run build
npm run start
```
The second command starts a built-in webserver. Locate the `prism.js` file included in this plugin, and view the source, Find the build URL and paste that into your browser. It should look something like:
Make your changes, including adding additional languages, plugins etc. Then click **DOWNLOAD JS** and **DOWNLOAD CSS** buttons and upload your copies to a safe location, e.g. `/user/data/prims-highlight/`.
You can then edit the configuration of the `prism-highlight` plugin and point the `custom.js_location` and `custom.css_location` options to the custom file locations (default is already `user://data/prismjs` folder).
