Grav Plugin Highlight

# Grav Highlight Plugin

![Highlight](assets/readme_1.png)

`highlight` is a [Grav](http://github.com/getgrav/grav) plugin that adds simple and powerful code highlighting functionality utilizing [Highlight.js](https://highlightjs.org/).

> Highlight.js: v10.5.0  
> Highlight.js line numbers [plugin](https://github.com/wcoder/highlightjs-line-numbers.js/): v2.8.0

# 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 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/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 `highlight`. You can find these files either on [GitHub](https://github.com/getgrav/grav-plugin-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/highlight

>> NOTE: This plugin is a modular component for Grav which requires [Grav](http://github.com/getgrav/grav), the [Error](https://github.com/getgrav/grav-plugin-error) and [Problems](https://github.com/getgrav/grav-plugin-problems) plugins, and a theme to be installed in order to operate.

# Usage

To best understand how Highlight works, you should read through the original project [documentation](https://highlightjs.org/usage/).

You can override any default settings from the page headers:

eg:

    ---
    title: Sample Code With Custom Theme
    highlight:
        theme: monokai
    ---

    ```
    @font-face {
      font-family: Chunkfive; src: url('Chunkfive.otf');
    }

    body, .usertext {
      color: #F0F0F0; background: #600;
      font-family: Chunkfive, sans;
    }

    @import url(print.css);
    @media print {
      a[href^=http]::after {
        content: attr(href)
      }
    }
    ```


You can also disable highlighting for a particular page if causes issues:

    ---
    title: Sample Code with Highlight disabled
    highlight:
        enabled: false
    ---

    ```
    @font-face {
      font-family: Chunkfive; src: url('Chunkfive.otf');
    }

    body, .usertext {
      color: #F0F0F0; background: #600;
      font-family: Chunkfive, sans;
    }

    @import url(print.css);
    @media print {
      a[href^=http]::after {
        content: attr(href)
      }
    }
    ```

Further, you can also enable line numbers on a specific page, or globally (in highlight.yaml):

    ---
    title: Sample Code with Highlight and line numbers enabled
    highlight:
        enabled: true
        lines: true
    ---

Valid theme options include: 

|                           |                          |                        |
| :------------------------ | :--------------------    | :--------------------- |
| a11y-dark                 | darcula                  | nnfx-dark
| a11y-light                | dark                     | nord
| agate                     | default                  | obsidian
| an-old-hope               | docco                    | ocean
| androidstudio             | dracula                  | paraiso-dark
| arduino-light             | far                      | paraiso-light
| arta                      | foundation               | pojoaque
| ascetic                   | github                   | purebasic
| atelier-cave-dark         | github-gist              | qtcreator_dark
| atelier-cave-light        | gml                      | qtcreator_light
| atelier-dune-dark         | googlecode               | railscasts
| atelier-dune-light        | gradient-dark            | rainbow
| atelier-estuary-dark      | gradient-light           | routeros
| atelier-estuary-light     | grayscale                | school-book
| atelier-forest-dark       | gruvbox-dark             | school-book
| atelier-forest-light      | gruvbox-light            | shades-of-purple
| atelier-heath-dark        | highlightjs-line-numbers | solarized-dark
| atelier-heath-light       | hopscotch                | solarized-light
| atelier-lakeside-dark     | hybrid                   | srcery
| atelier-lakeside-light    | idea                     | stackoverflow-dark
| atelier-plateau-dark      | ir-black                 | stackoverflow-light
| atelier-plateau-light     | isbl-editor-dark         | sunburst
| atelier-savanna-dark      | isbl-editor-light        | tomorrow
| atelier-savanna-light     | kimbie.dark              | tomorrow-night
| atelier-seaside-dark      | kimbie.light             | tomorrow-night-blue
| atelier-seaside-light     | learn                    | tomorrow-night-bright
| atelier-sulphurpool-dark  | lightfair                | tomorrow-night-eighties
| atelier-sulphurpool-light | lioshi                   | vs
| atom-one-dark             | magula                   | vs2015
| atom-one-dark-reasonable  | mono-blue                | xcode
| atom-one-light            | monokai                  | xt256
| brown-paper               | monokai-sublime          | zenburn
| codepen-embed             | night-owl                | 
| color-brewer              | nnfx                     | 

Check out a [live demo](https://highlightjs.org/static/demo/) of these themes.

Following languages are supported:

|                        |                          |                           |
| :--------------------- | :--------------------    | :----------------------   |
| .properties            | JSON                     | R                         |
| Apache config          | Kotlin                   | Ruby                      |
| Bash                   | Less                     | Rust                      |
| C                      | Lua                      | SCSS                      |
| C#                     | Makefile                 | Shell Session             |
| C++                    | Markdown                 | SQL                       |
| CoffeeScript           | Nginx config             | Swift                     |
| CSS                    | Objective-C              | TOML, also INI            |
| Diff                   | Perl                     | Twig                      |
| Go                     | PHP                      | TypeScript                |
| HTML, XML              | PHP Template             | Visual Basic .NET         |
| HTTP                   | Plain text               | YAML                      |
| Java                   | Python                   |                           |
| JavaScript             | Python REPL              |                           |

# Updating

As development for the Highlight plugin continues, new versions may become available that add additional features and functionality, improve compatibility with newer Grav releases, and generally provide a better user experience. Updating Highlight is easy, and can be done through Grav's GPM system, as well as manually.

## GPM Update (Preferred)

The simplest way to update this plugin is via the [Grav Package Manager (GPM)](http://learn.getgrav.org/advanced/grav-gpm). You can do this with this by navigating to the root directory of your Grav install using your system's Terminal (also called command line) and typing the following:

    bin/gpm update highlight

This command will check your Grav install to see if your Highlight plugin is due for an update. If a newer release is found, you will be asked whether or not you wish to update. To continue, type `y` and hit enter. The plugin will automatically update and clear Grav's cache.

## Manual Update

Manually updating Highlight is pretty simple. Here is what you will need to do to get this done:

* Delete the `your/site/user/plugins/highlight` directory.
* Downalod the new version of the Highlight plugin from either [GitHub](https://github.com/getgrav/grav-plugin-highlight) or [GetGrav.org](http://getgrav.org/downloads/plugins#extras).
* Unzip the zip file in `your/site/user/plugins` and rename the resulting folder to `highlight`.
* Clear the Grav cache. The simplest way to do this is by going to the root Grav directory in terminal and typing `bin/grav clear-cache`.

> Note: Any changes you have made to any of the files listed under this directory will also be removed and replaced by the new set. Any files located elsewhere (for example a YAML settings file placed in `user/config/plugins`) will remain intact.