Repo: community/formatter/highlight/hljs.php

https://github.com/highlightjs/highlight.js
Highlight.js Documentation

Highlight.js is a syntax highlighter written in JavaScript. It works in the browser as well as on the server. It can work with pretty much any markup, doesn’t depend on any other frameworks, and has automatic language detection.

1. Usage

Call via (hljs [language])

%%(hljs php) source%%

2. Install

1. download highlight.js
2. place the Highlight.js lib and default.min.css under the lib/highlight.js/ folder
3. add hljs.php highlighter to the formatter/highlight/ folder
4. add hljs.tpl template to the formatter/highlight/template/ folder
5. link the js and css file in the theme header or add the hljs action to the action/ folder

2.1. Formatter

formatter/highlight/hljs.php

<?php

// WackoWiki Wrapper for Highlight.js
// https://wackowiki.org/doc/Dev/PatchesHacks/Highlight.js

/*
    %%(hljs [language])
    content
    %%

    requires Highlight.js script <https://highlightjs.org/>
    The Highlight.js script must be loaded once either via the {{hljs}} action or the theme header.
*/

// comment this out when you've set this statically in the theme header
if (!isset($this->hljs))
{
    $this->hljs            = true;
    $tpl->action_name    = 'hljs';
}

if ($options['_default'])
{
    $language    = $options['_default'];

    if (!empty($language))
    {
        $class = match ($language)
        {
            'nohighlight'        => 'nohighlight',
            default                => 'language-' . $language
        };
    }

    if ($class)
    {
        $tpl->class = ' class="' . $class . '"';
    }
}

$tpl->text = Ut::html($text);

	

formatter/highlight/template/hljs.tpl

[ === main === ]
[ '' action '' ]
<ignore>
<!--notypo-->
	[ ' error ' ]
	<pre><code[ ' class ' ]>[ ' text | pre ' ]</code></pre>
<!--/notypo-->
</ignore>

[ == action == ]
<ignore><!--notypo--><!--action:begin-->[ ' name ' ]<!--action:end--><!--/notypo--></ignore>	

2.2. Link to the library and one of the themes

The Highlight.js script and the stylesheet must be loaded once either dynamically via

• the {{hljs}} action (formatter sets action call) or
• the theme header.

<?php

// add to theme/_common/_header.php (above $tpl->additions)

// highlight.js
$this->add_html('header', '<link rel="stylesheet" href="' . $this->db->base_path . 'js/highlight.js/default.min.css' . '">');
$this->add_html('footer', '<script src="' . $this->db->base_path . 'js/highlight.js/highlight.min.js' . '"></script>');
$this->add_html('footer', '<script>hljs.highlightAll();</script>');

	

or load them dynamically via a action set once only via formatter when needed.

action/hljs.php

<?php

if (!defined('IN_WACKO'))
{
    exit;
}

// chose your favorite style (e.g. stackoverflow-dark.min.css)
$hljs_css        = 'default.min.css';

// local
$hljs_styles    = $this->db->base_path . 'js/highlight.js/' . $hljs_css;
$hljs_script    = $this->db->base_path . 'js/highlight.js/highlight.min.js';

// CDN (see Highlight.js README.md)
#$hljs_styles    = 'https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.7.0/build/styles/' . $hljs_css;
#$hljs_script    = 'https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.7.0/build/es/highlight.min.js';

// highlight.js
$this->add_html('header', '<link rel="stylesheet" href="' . $hljs_styles .  '">');
$this->add_html('footer', '<script src="' . $hljs_script . '"></script>');
$this->add_html('footer', '<script>hljs.highlightAll();</script>');

	

2.2.1. Fetch via CDN & Subresource Integrity

If you prefer Highlight.js via CDN replace the local resources accordingly.

If you are loading Highlight.js via CDN you may wish to use Subresource Integrity to guarantee that you are using a legimitate build of the library.

To do this you simply need to add the integrity attribute for each JavaScript file you download via CDN. These digests are used by the browser to confirm the files downloaded have not been modified.

<script
  src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/highlight.min.js"
  integrity="sha384-d8KTBLFjg2IVNtohjj32TAh8+MOFPukj5WKbkfk83mLz1ctxujsIN0jnKaRw3rW7"></script>

2.3. Use custom CSS files

Chose a style like stackoverflow-dark.min.css from the styles/ folder of the downloaded highlight.zip and replace default.min.css with it. Don't forget to change the CSS file name in the action or your theme header accordingly.

2.4. Router configuration

Add the js/highlight.js directory to your router.conf if you hosting your own copy of Highlight.js.

config/router.conf

diff --git a/src/config/router.conf b/src/config/router.conf
index 6649fc2..24698d1 100644
--- a/src/config/router.conf
+++ b/src/config/router.conf
@@ -107,7 +107,7 @@
 `^(theme/{}/css|theme/_common|admin/style)/{}$`                _ok!            // css
 `^image/(wikiedit/)?{}$`                                    _ok!            // icons
 `^theme/{}/icon/{}$`                                        _ok!            // icons
-`^js/(lang/|photoswipe/)?{}$`                                _ok!            // js
+`^js/(lang/|photoswipe/|highlight.js/)?{}$`                    _ok!            // js
 `^file/(global/){}$`                                        _ok!            // global uploads
 `^file/thumb/{}$`                                            _ok!            // global thumbs
 `^setup/(image|css)/{}$`                                    _ok! unlock=1    // setup inlines

2.5. CSP

Add the domain of the CDN to style-src and script-src in your csp.custom.conf if you do use a Highlight.js CDN server.

config/csp.custom.conf

style-src 'self' cdn.jsdelivr.net;
	script-src 'self' 'unsafe-inline' cdn.jsdelivr.net;	

3. Supported Formats

The table below shows the full list of languages (and corresponding classes/aliases) supported by Highlight.js. Languages that list a Package below are 3rd party languages and are not bundled with the core library. You can find their repositories by following the links.

Note: The languages available will depend on how you've built or are included the library in your app. For example our default minified web build includes only ~40 popular languages.

4. Basic Usage

The bare minimum for using highlight.js on a web page is linking to the library along with one of the themes and calling [highlightAll][1]:

<link rel="stylesheet" href="/path/to/styles/default.min.css">
<script src="/path/to/highlight.min.js"></script>
<script>hljs.highlightAll();</script>

This will find and highlight code inside of <pre><code> tags; it tries to detect the language automatically. If automatic detection doesn’t work for you, or you simply prefer to be explicit, you can specify the language manually in the using the class attribute:

<pre><code class="language-html">...</code></pre>

4.1. Plaintext Code Blocks

To apply the Highlight.js styling to plaintext without actually highlighting it, use the plaintext language:

<pre><code class="language-plaintext">...</code></pre>

4.2. Ignoring a Code Block

To skip highlighting of a code block completely, use the nohighlight class:

<pre><code class="nohighlight">...</code></pre>

5. Changelog

0.1 Initial version
0.2

6. ToDo

• test formatter and settings
• improve code and documentation