Introducing: ‘Kirby Highlight’

S1SYPHOS · November 8, 2017, 6:47pm

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), I decided to go for it:

Highlighting code for everyone - no javascript needed
Extensive: currently 141 supported languages
Customisable: 65 different styles included (more coming soon)

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:

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

Clone or download

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

Activate the plugin

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

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.

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 are supported).

Styling

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

<?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: 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.

You can find the plugin on Github. 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

S1SYPHOS · November 9, 2017, 1:43pm

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 `<`, `>` to `>`, …), see the docs 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 and if something’s bothering you, just open an issue.

jimbobrjames · November 11, 2017, 1:53pm

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

jimbobrjames · November 11, 2017, 2:25pm

@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:

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:

<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>

Any idea whats wrong?

S1SYPHOS · November 11, 2017, 5:07pm

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?

jimbobrjames · November 11, 2017, 5:17pm

I am using Enhanced textarea field, but i get the same result with the standard Kirby field.

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

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.

jimbobrjames · November 11, 2017, 5:25pm

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…

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

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

$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…

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

I tried some HTML too and the same thing happens.

S1SYPHOS · November 11, 2017, 5:52pm

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

jimbobrjames · November 11, 2017, 6:06pm

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.

S1SYPHOS · November 11, 2017, 6:07pm

S1SYPHOS · November 11, 2017, 6:08pm

Glad you worked it out!

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

jimbobrjames · November 11, 2017, 6:12pm

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…

S1SYPHOS · November 11, 2017, 6:13pm

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.
Thanks for the great feedback so far and have a good night, everybody!

jenstornell · November 11, 2017, 8:57pm

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

github.com

kirby-deprecated-plugins/kirby-html-minifier/blob/master/tiny-html-minifier/tiny-html-minifier.php#L243


      
          <?php
          class TinyHtmlMinifier {
              function __construct($options) {
                  $this->options = $options;
                  $this->build = [];
                  $this->skip = 0;
                  $this->skipName = '';
                  $this->head = false;
                  $this->elements = [
                      'skip' => [
                          'code',
                          'pre',
                          'textarea',
                          'script'
                      ],
                      'hard' => [
                          '!doctype',
                          'body',
                          'html',
                      ]
                  ];
              }
          
              // Run minifier
              function minify($html) {
                  $html = $this->removeComments($html);
                  $this->walk($html);
                  return $this->buildHtml();
              }
          
              // Walk trough html
              function walk($html) {
                  $parts = explode('<', $html, 2);
                  $part = $parts[0];
          
                  $tag_parts = explode('>', $part);
                  $tag_content = $tag_parts[0];
                  
                  if(!empty($tag_content)) {
                      $name = $this->findName($tag_content);
                      $element = $this->toElement($tag_content, $parts[0], $name);
                      $type = $this->toType($element);
          
                      if($name == 'head') {
                          $this->head = ($type == 'open') ? true : false;
                      }
                      
                      $this->build[] = [
                          'name' => $name,
                          'content' => $element,
                          'type' => $type
                      ];
          
                      $this->setSkip($name, $type);
          
                      if(!empty($tag_content)) {
                          $content = (isset($tag_parts[1])) ? $tag_parts[1] : '';
                          if(!empty($content)) {
                              $this->build[] = [
                                  'content' => $this->compact($content, $name, $element),
                                  'type' => 'content'
                              ];
                          }
                      }
                  }
          
                  $rest = (isset($parts[1])) ? $parts[1] : '';
          
                  if(!empty($rest)) {
                      $this->walk($rest);
                  }
              }
          
              // Remove comments
              function removeComments($content = '') {
                  return preg_replace('/<!--(.|\s)*?-->/', '', $content);
              }
          
              // Check if string contains string
              function contains($needle, $haystack) {
                  return strpos($haystack, $needle) !== false;
              }
          
              // Return type of element
              function toType($element) {
                  $type = (substr($element, 1, 1) == '/') ? 'close' : 'open';
                  return $type;
              }
          
              // Create element
              function toElement($element, $noll, $name) {
                  $element = $this->stripWhitespace($element);
                  $element = $this->addChevrons($element, $noll);
                  $element = $this->removeSelfSlash($element);
                  $element = $this->removeMeta($element, $name);
                  return $element;
              }
          
              // Remove unneeded element meta
              function removeMeta($element, $name) {
                  if($name == 'style') {
                      $element = str_replace([
                          ' type="text/css"',
                          "' type='text/css'"
                      ],
                      ['', ''], $element);
                  } elseif($name == 'script') {
                      $element = str_replace([
                          ' type="text/javascript"',
                          " type='text/javascript'"
                      ],
                      ['', ''], $element);
                  }
                  return $element;
              }
          
              // Strip whitespace from element
              function stripWhitespace($element) {
                  if($this->skip == 0) {
                      $element = preg_replace('/\s+/', ' ', $element);
                  }
                  return $element;
              }
          
              // Add chevrons around element
              function addChevrons($element, $noll) {
                  $char = ($this->contains('>', $noll)) ? '>' : '';
                  $element = '<' . $element . $char;
                  return $element;
              }
          
              // Remove unneeded self slash
              function removeSelfSlash($element) {
                  if(substr($element, -3) == ' />') {
                      $element = substr($element, 0, -3) . '>';
                  }
                  return $element;
              }
          
              // Compact content
              function compact($content, $name, $element) {
                  if($this->skip != 0) {
                      $name = $this->skipName;
                  } else {
                      $content = preg_replace('/\s+/', ' ', $content);
                  }
          
                  if(
                      $this->isSchema($name, $element) &&
                      !empty($this->options['collapse_json_ld'])
                      ) {
                      return json_encode(json_decode($content));
                  } if(in_array($name, $this->elements['skip'])) {
                      return $content;
                  } elseif(
                      in_array($name, $this->elements['hard']) ||
                      !empty($this->options['collapse_whitespace']) ||
                      $this->head
                      ) {
                      return $this->minifyHard($content);
                  } else {
                      return $this->minifyKeepSpaces($content);
                  }
              }
          
              function isSchema($name, $element) {
                  if($name != 'script') return false;
          
                  $element = strtolower($element);
                  if($this->contains('application/ld+json', $element)) return true;
                  return false;
              }
          
              // Build html
              function buildHtml() {
                  $out = '';
                  foreach($this->build as $build) {
                      $out .= $build['content'];
                  }
                  return $out;
              }
          
              // Find name by part
              function findName($part) {
                  $name_cut = explode(" ", $part, 2)[0];
                  $name_cut = explode(">", $name_cut, 2)[0];
                  $name_cut = explode("\n", $name_cut, 2)[0];
                  $name_cut = preg_replace('/\s+/', '', $name_cut);
                  $name_cut = strtolower(str_replace('/', '', $name_cut));
                  return $name_cut;
              }
          
              // Set skip if elements are blocked from minification
              function setSkip($name, $type) {
                  foreach($this->elements['skip'] as $element) {
                      if($element == $name && $this->skip == 0) {
                          $this->skipName = $name;
                      }
                  }
                  if(in_array($name, $this->elements['skip'])) {
                      if($type == 'open') {
                          $this->skip++;
                      }
                      if($type == 'close') {
                          $this->skip--;
                      }
                  }
              }
          
              // Minify all, even spaces between elements
              function minifyHard($element) {
                  $element = preg_replace('!\s+!', ' ', $element);
                  $element = trim($element);
                  return trim($element);
              }
          
              // Strip but keep one space
              function minifyKeepSpaces($element) {
                  return preg_replace('!\s+!', ' ', $element);
              }
          }
          
          class TinyMinify {
              static function html($html, $options = []) {
                  $minifier = new TinyHtmlMinifier($options);
                  return $minifier->minify($html);
              }
          }

This file has been truncated. show original

jimbobrjames · November 12, 2017, 8:26am

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.

jenstornell · November 12, 2017, 7:35pm

I have added an issue:

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.

jimbobrjames · November 12, 2017, 8:01pm

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

jenstornell · April 18, 2018, 2:09pm

A bit late probably but I updated my 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:

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

jimbobrjames · April 18, 2018, 2:15pm

@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.

S1SYPHOS · March 25, 2019, 10:31am

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 and enjoy server-side syntax highlighting!

Topic		Replies	Views
Introducing: 'Kirby3 Highlight' Kirby 3 plugin 🧩	4	825	March 9, 2020
Use GeShi syntax highlight with Kirby Solved ✅	10	1879	August 26, 2015
Problems with the comment-plugin Solved ✅	19	1613	August 17, 2018
Our brand new plugin directory	4	367	March 31, 2022
Introducing getkirby-plugins.com Plugins	7	1338	March 11, 2015