# Introducing: ‘Kirby Highlight’

**URL:** <https://forum.getkirby.com/t/introducing-kirby-highlight/8965>\
**Category:** Plugins\
**Created:** [November 8, 2017, 6:47pm UTC](https://forum.getkirby.com/t/introducing-kirby-highlight/8965 "2017-11-08T18:47:00Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![S1SYPHOS](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/s1syphos/32/3671_2.png) [@S1SYPHOS](https://forum.getkirby.com/u/S1SYPHOS)\
**Post date:** [November 8, 2017, 6:47pm UTC](https://forum.getkirby.com/t/introducing-kirby-highlight/8965/1 "2017-11-08T18:47:00Z")

</div>

Hey there,  
just recently I hacked together a plugin that highlights code snippets server-side.

## But … why?

Server-side - that means no external dependencies (especially those written in javascript like `prism.js` and `highlight.js`). I love them both, but they’re not for everyone. People disabling javascript execution (and for good reasons) should still be able to enjoy some decently highlighted code IMHO.

Why not? When I found out about Geert Bergman’s `highlight.php` library (a PHP port of [highlight.js](https://highlightjs.org)), I decided to go for it:

- Highlighting code for everyone - no javascript needed
- Extensive: currently 141 [supported languages](https://github.com/S1SYPHOS/kirby-highlight/tree/master/vendor/scrivo/highlight.php/Highlight/languages)
- Customisable: 65 different styles included (more coming soon)

 ![screenshot of the kirby-highlight plugin](https://europe1.discourse-cdn.com/flex017/uploads/getkirby/original/2X/f/ffcae9fdb00c0bc50aef2385dc91cf8d6e468dd1.gif)

## Getting started

Use one of the following methods to install & use `kirby-highlight`:

### Git submodule

If you know your way around Git, you can download this plugin as a [submodule](https://github.com/blog/2104-working-with-submodules):

```nohighlight
git submodule add https://github.com/S1SYPHOS/kirby-highlight.git site/plugins/kirby-highlight

```

### Clone or download

1. [Clone](https://github.com/S1SYPHOS/kirby-highlight.git) or [download](https://github.com/S1SYPHOS/kirby-highlight/archive/master.zip) this repository.
2. Unzip / Move the folder to `site/plugins`.

### Activate the plugin

Activate the plugin with the following line in your `config.php`:

```nohighlight
c::set('plugin.kirby-highlight', true);

```

Now proper classes are added to your code snippets, making them ‘themeable’. If you want to activate `kirby-highlight` only on specific domains, read about [multi-environment setups](https://getkirby.com/docs/developer-guide/configuration/options).

## Configuration

Change `kirby-highlight` options to suit your needs:

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `plugin.kirby-highlight.languages` | Array | `['html', 'php']` | Defines languages to be auto-detected (currently [141 languages](https://github.com/S1SYPHOS/kirby-highlight/tree/master/vendor/scrivo/highlight.php/Highlight/languages) are supported). |

## Styling

To apply one of the many available stylesheets, just include it in your `<head>` element using the `css()` helper:

```php
<?php echo css('assets/plugins/kirby-highlight/css/zenburn.css') ?>

```

**Note: Most of the included themes depend some way or another on the class `.hljs` to be added to the code’s container!**

In order to make sure the theme gets applied as planned, any of these methods will work:

- Simply use `kirby-pep` to [put it there](https://github.com/S1SYPHOS/kirby-pep): `c::set('plugin.kirby-pep.code_class', 'language-%s hljs');`
- Replace `.hljs` with `[class^="language-"]` in the included stylesheet
- Copy it to your `assets/css` directory and modify it
- Include the styles in your own workflow

## Troubleshooting

Adding an unsupported language breaks `kirbytext()` parsing of the code snippet in question. Always be sure to only include [valid languages](https://github.com/S1SYPHOS/kirby-highlight/tree/master/vendor/scrivo/highlight.php/Highlight/languages).

You can find the plugin on [Github](https://github.com/S1SYPHOS/kirby-highlight). It’s not much, but it’s something. I’d love to get some feedback on this, and since this is my second (public) plugin, try to be nice 🙂

---

<div class="post-metadata">

**Author:** ![S1SYPHOS](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/s1syphos/32/3671_2.png) [@S1SYPHOS](https://forum.getkirby.com/u/S1SYPHOS)\
**Post date:** [November 9, 2017, 1:43pm UTC](https://forum.getkirby.com/t/introducing-kirby-highlight/8965/2 "2017-11-09T13:43:50Z")

</div>

# Releasing v0.3.0-beta

Regarding language definitions & styles, this is up to `highlight.js` v9.12.0:

## New features:

- Added all 79 styles also included in `highlight.js`.
- Added optional character escaping.

## How to use:

Just define it in your `config.php`:

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `plugin.kirby-highlight.escaping` | Boolean | `false` | Enables character escaping (converting `<` to `&lt;`, `>` to `&gt;`, …), see the [docs](http://php.net/manual/en/function.htmlspecialchars.php) over at PHP’s `htmlspecialchars()`. |

## Feedback welcome!

This is still considered beta, but should nonetheless work as intended - since nobody complained, I guess that’s a good start!

However, feel free to [test this release](https://github.com/S1SYPHOS/kirby-highlight/archive/master.zip) and if something’s bothering you, just [open an issue](https://github.com/S1SYPHOS/kirby-highlight/issues/new).

---

<div class="post-metadata">

**Author:** ![jimbobrjames](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/jimbobrjames/32/5802_2.png) [@jimbobrjames](https://forum.getkirby.com/u/jimbobrjames)\
**Post date:** [November 11, 2017, 1:53pm UTC](https://forum.getkirby.com/t/introducing-kirby-highlight/8965/3 "2017-11-11T13:53:07Z")

</div>

Awesome! i’m testing this out on a documentation site i’m building at the moment. I will report back any issues.

---

<div class="post-metadata">

**Author:** ![jimbobrjames](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/jimbobrjames/32/5802_2.png) [@jimbobrjames](https://forum.getkirby.com/u/jimbobrjames)\
**Post date:** [November 11, 2017, 2:25pm UTC](https://forum.getkirby.com/t/introducing-kirby-highlight/8965/4 "2017-11-11T14:25:50Z")

</div>

@S1SYPHOS

Hmmm ok so I have some issues. I have install the plugin, and Kirby Pep, but its not quite working. I have the following options in my config:

```auto
c::set('plugin.kirby-highlight', true);
c::set('plugin.kirby-highlight.languages', ['html', 'scss', 'css']);
c::set('plugin.kirby-pep', true);
c::set('plugin.kirby-pep.code_class', 'language-%s hljs');

```

I have the styles included (as part of a SASS build, rather then standalone sheet)

My code blocks are getting partially styled. Im not seeing the `.hljs` class or a language class being applied to the code container, and the formatting is being stripped so its on one line:

```auto
<pre><code><span class="hljs-variable">$times</span>: Times, <span class="hljs-string">"Times New Roman"</span>, serif; <span class="hljs-variable">$arial</span>: Arial, sans-serif; <span class="hljs-variable">$georgia</span>: Georgia, serif; <span class="hljs-variable">$garamond</span>: <span class="hljs-string">"Apple Garamond"</span>, <span class="hljs-string">"ITC Garamond Narrow"</span>, <span class="hljs-string">"Garamond"</span>, serif; <span class="hljs-variable">$helvetica</span>: <span class="hljs-string">"Helvetica Neue"</span>, Helvetica, sans-serif; <span class="hljs-variable">$verdana</span>: <span class="hljs-string">"Verdana Ref"</span>, Verdana, sans-serif; <span class="hljs-variable">$trebuchet</span>: <span class="hljs-string">"Trebuchet MS"</span>, sans-serif; <span class="hljs-variable">$gillsans</span>: <span class="hljs-string">"Gill Sans MT"</span>, <span class="hljs-string">"Gill Sans"</span>, Tahoma, Geneva, sans-serif;</code>
</pre>

```

 ![partial-highlight](https://europe1.discourse-cdn.com/flex017/uploads/getkirby/original/2X/4/482d9413ae65608d794c7c19ca47fa28db954f5c.jpeg)

Any idea whats wrong?

---

<div class="post-metadata">

**Author:** ![S1SYPHOS](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/s1syphos/32/3671_2.png) [@S1SYPHOS](https://forum.getkirby.com/u/S1SYPHOS)\
**Post date:** [November 11, 2017, 5:07pm UTC](https://forum.getkirby.com/t/introducing-kirby-highlight/8965/5 "2017-11-11T17:07:35Z")

</div>

Three questions:

- Are you using a generic `textarea` field?
- Does your `<code>` element really not have any class (or was that just laziness 🙂 )
- Are you invoking the code snippet using the usual fenced code syntax?

Like:

```html/css/scss  
// some code  
```

Cheers!

// Edit:  
4th question: Which plugin versions are you using?

---

<div class="post-metadata">

**Author:** ![jimbobrjames](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/jimbobrjames/32/5802_2.png) [@jimbobrjames](https://forum.getkirby.com/u/jimbobrjames)\
**Post date:** [November 11, 2017, 5:17pm UTC](https://forum.getkirby.com/t/introducing-kirby-highlight/8965/6 "2017-11-11T17:17:48Z")

</div>

> [@S1SYPHOS](#):
>
> Are you using a generic textarea field?

I am using [Enhanced textarea](https://github.com/medienbaecker/kirby-enhanced-textarea) field, but i get the same result with the standard Kirby field.

> [@S1SYPHOS](#):
>
> Does your \<code\> element really not have any class (or was that just laziness 🙂

No laziness here, it really didn’t have the classes.

> [@S1SYPHOS](#):
>
> Are you invoking the code snippet using the usual fenced code syntax?

Ah ha! the missing thing, didnt realise i had to declare the language on the fence. I just did ```

So now i’m getting the classes that were missing, and a bit more styling, but the formatting is still stripped. Both highlight and pep are the most recent versions, downloaded today. Kirby 2.5.4, PHP 7x running on Homestead vagrant box.

☹

---

<div class="post-metadata">

**Author:** ![jimbobrjames](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/jimbobrjames/32/5802_2.png) [@jimbobrjames](https://forum.getkirby.com/u/jimbobrjames)\
**Post date:** [November 11, 2017, 5:25pm UTC](https://forum.getkirby.com/t/introducing-kirby-highlight/8965/7 "2017-11-11T17:25:42Z")

</div>

Ok, think i’ve figured something out, perhaps a bug. It doesn’t like the sass code block starting with a variable.

this works, and keeps its formatting and indents, but only gets classes on the code tag…

```auto
components: (
	baseform: true,
	inputs: true,
	addons: true,
	select: true,
	validation: true
),

```

This gets stripped onto one line, but does get all the classes generated:

```auto
$form-skin-default: (
  // Components
  components: (
    baseform: true,
    inputs: true,
    addons: true,
    select: true,
    validation: true
  ),
);

```

Edit: Hmm… its worse then that, this doesnt work either…

```auto
body {
  padding: 0;
  margin: 0;
  min-height: 100%;
  display: flex;
  flex-direction: column;
}

```

I tried some HTML too and the same thing happens.

---

<div class="post-metadata">

**Author:** ![S1SYPHOS](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/s1syphos/32/3671_2.png) [@S1SYPHOS](https://forum.getkirby.com/u/S1SYPHOS)\
**Post date:** [November 11, 2017, 5:52pm UTC](https://forum.getkirby.com/t/introducing-kirby-highlight/8965/8 "2017-11-11T17:52:28Z")

</div>

I’ll try to reproduce this, wait a sec …

---

<div class="post-metadata">

**Author:** ![jimbobrjames](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/jimbobrjames/32/5802_2.png) [@jimbobrjames](https://forum.getkirby.com/u/jimbobrjames)\
**Post date:** [November 11, 2017, 6:06pm UTC](https://forum.getkirby.com/t/introducing-kirby-highlight/8965/9 "2017-11-11T18:06:48Z")

</div>

Ah ha! I have found the culprit. Didnt realise i had @jenstornell HTML minifier active. It was that that was stripping the formatting. I feel silly.

---

<div class="post-metadata">

**Author:** ![S1SYPHOS](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/s1syphos/32/3671_2.png) [@S1SYPHOS](https://forum.getkirby.com/u/S1SYPHOS)\
**Post date:** [November 11, 2017, 6:07pm UTC](https://forum.getkirby.com/t/introducing-kirby-highlight/8965/10 "2017-11-11T18:07:20Z")

</div>

![Screenshot from 2017-11-11 19-05-26](https://europe1.discourse-cdn.com/flex017/uploads/getkirby/original/2X/e/e9be9340633c7b17b55974aedda8d47cd83e5834.png)

---

<div class="post-metadata">

**Author:** ![S1SYPHOS](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/s1syphos/32/3671_2.png) [@S1SYPHOS](https://forum.getkirby.com/u/S1SYPHOS)\
**Post date:** [November 11, 2017, 6:08pm UTC](https://forum.getkirby.com/t/introducing-kirby-highlight/8965/11 "2017-11-11T18:08:18Z")

</div>

Glad you worked it out!

True, highlight.js doesn’t seem to care that much for SASS/SCSS, but it gets rendered nonetheless 😉

---

<div class="post-metadata">

**Author:** ![jimbobrjames](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/jimbobrjames/32/5802_2.png) [@jimbobrjames](https://forum.getkirby.com/u/jimbobrjames)\
**Post date:** [November 11, 2017, 6:12pm UTC](https://forum.getkirby.com/t/introducing-kirby-highlight/8965/12 "2017-11-11T18:12:03Z")

</div>

Thanks for looking into it. Unfortunately the @jenstornell html minifier plugin does not have a way to exclude certain tags, only whole pages. Thats no good to me because nearly every page has a code example on it… ☹

---

<div class="post-metadata">

**Author:** ![S1SYPHOS](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/s1syphos/32/3671_2.png) [@S1SYPHOS](https://forum.getkirby.com/u/S1SYPHOS)\
**Post date:** [November 11, 2017, 6:13pm UTC](https://forum.getkirby.com/t/introducing-kirby-highlight/8965/13 "2017-11-11T18:13:06Z")

</div>

# Releasing v0.4.0

With this release, the underlying PHP port is finally at eye level with `highlight.js` v9.12.0.

- All 176 languages
- All 79 styles
- Improved language definition update process

Check it out on [Github](https://github.com/S1SYPHOS/kirby-highlight).  
Thanks for the great feedback so far and have a good night, everybody!

---

<div class="post-metadata">

**Author:** ![jenstornell](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/jenstornell/32/546_2.png) [@jenstornell](https://forum.getkirby.com/u/jenstornell)\
**Post date:** [November 11, 2017, 8:57pm UTC](https://forum.getkirby.com/t/introducing-kirby-highlight/8965/14 "2017-11-11T20:57:19Z")

</div>

`code` elements should not be minified. Do you use a `code` element?

> <https://github.com/kirby-deprecated-plugins/kirby-html-minifier/blob/master/tiny-html-minifier/tiny-html-minifier.php#L243>

---

<div class="post-metadata">

**Author:** ![jimbobrjames](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/jimbobrjames/32/5802_2.png) [@jimbobrjames](https://forum.getkirby.com/u/jimbobrjames)\
**Post date:** [November 12, 2017, 8:26am UTC](https://forum.getkirby.com/t/introducing-kirby-highlight/8965/15 "2017-11-12T08:26:54Z")

</div>

Yes, its a Markdown code fence, so its actually a `<code>` tag nested inside a `<pre>` tag. The highlight plugin renders `<span>` tags inside this. It is not being ignored by your plugin. ☹

I think the problem is that your plugin is ignoring code, pre, and textarea tags, but its not ignoring tags inside those tags.

---

<div class="post-metadata">

**Author:** ![jenstornell](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/jenstornell/32/546_2.png) [@jenstornell](https://forum.getkirby.com/u/jenstornell)\
**Post date:** [November 12, 2017, 7:35pm UTC](https://forum.getkirby.com/t/introducing-kirby-highlight/8965/16 "2017-11-12T19:35:57Z")

</div>

I have added an issue:

[https://github.com/jenstornell/kirby-html-minifier/issues/9](https://github.com/jenstornell/kirby-html-minifier/issues/9)

Because I’ve built the parser myself this time, it’s easier to fix the problem. It seems like all parsers have their own problems, now including mine.

---

<div class="post-metadata">

**Author:** ![jimbobrjames](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/jimbobrjames/32/5802_2.png) [@jimbobrjames](https://forum.getkirby.com/u/jimbobrjames)\
**Post date:** [November 12, 2017, 8:01pm UTC](https://forum.getkirby.com/t/introducing-kirby-highlight/8965/17 "2017-11-12T20:01:02Z")

</div>

Thanks @jenstornell , its a great plugin, and my use case is probably not a common one but i look forward to a resolution 🙂

---

<div class="post-metadata">

**Author:** ![jenstornell](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/jenstornell/32/546_2.png) [@jenstornell](https://forum.getkirby.com/u/jenstornell)\
**Post date:** [April 18, 2018, 2:09pm UTC](https://forum.getkirby.com/t/introducing-kirby-highlight/8965/18 "2018-04-18T14:09:50Z")

</div>

A bit late probably but I updated my [https://github.com/jenstornell/kirby-html-minifier](https://github.com/jenstornell/kirby-html-minifier) today and now I tested this code:

It keep the spaces untouched so I think it works like it should now:

```php
<pre><code>
    We have
        <span>some
        code here</span>
    </code></pre>

```

---

<div class="post-metadata">

**Author:** ![jimbobrjames](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/jimbobrjames/32/5802_2.png) [@jimbobrjames](https://forum.getkirby.com/u/jimbobrjames)\
**Post date:** [April 18, 2018, 2:15pm UTC](https://forum.getkirby.com/t/introducing-kirby-highlight/8965/19 "2018-04-18T14:15:11Z")

</div>

@jenstornell Gosh, completely forgot about that one. All good things come to those who wait. 🙂

Ill test it out later on my blog, and I have various code snippets in several different languages so ill let you know if i hit any bumps.

---

<div class="post-metadata">

**Author:** ![S1SYPHOS](https://dub1.discourse-cdn.com/flex017/user_avatar/forum.getkirby.com/s1syphos/32/3671_2.png) [@S1SYPHOS](https://forum.getkirby.com/u/S1SYPHOS)\
**Post date:** [March 25, 2019, 10:31am UTC](https://forum.getkirby.com/t/introducing-kirby-highlight/8965/20 "2019-03-25T10:31:49Z")

</div>

## Releasing v0.6.0

- Updating highlight-php to v9.15.6.0 (more languages & styles)
- Adding `hljs` class to `pre` container by default (configurable)
- Removing `kirby-pep` from README.md

Get your copy [here](https://github.com/S1SYPHOS/kirby-highlight/releases/tag/0.6.0) and enjoy server-side syntax highlighting!

[Next page](https://forum.getkirby.com/t/introducing-kirby-highlight/8965.md?page=2)