1<p align="center"><a href="https://github.com/crazy-max/dokuwiki-plugin-syntaxhighlighter4" target="_blank"><img width="100" src="https://raw.githubusercontent.com/crazy-max/dokuwiki-plugin-syntaxhighlighter4/master/resources/logo-128.png"></a></p>
2
3<p align="center">
4  <a href="https://github.com/crazy-max/dokuwiki-plugin-syntaxhighlighter4/releases"><img src="https://img.shields.io/github/release/crazy-max/dokuwiki-plugin-syntaxhighlighter4.svg?style=flat-square" alt="Github Release"></a>
5  <a href="https://www.dokuwiki.org/releasenames"><img src="https://img.shields.io/badge/dokuwiki-%3E%3D%20Elenor%20of%20Tsort-yellow.svg?style=flat-square" alt="Minimum DokuWiki Version"></a>
6  <a href="https://www.codacy.com/app/crazy-max/dokuwiki-plugin-syntaxhighlighter4"><img src="https://img.shields.io/codacy/grade/440e4b5de2ee4d37978a8e9e19f4b76f.svg?style=flat-square" alt="Code Quality"></a>
7  <br /><a href="https://github.com/sponsors/crazy-max"><img src="https://img.shields.io/badge/sponsor-crazy--max-181717.svg?logo=github&style=flat-square" alt="Become a sponsor"></a>
8  <a href="https://www.paypal.me/crazyws"><img src="https://img.shields.io/badge/donate-paypal-00457c.svg?logo=paypal&style=flat-square" alt="Donate Paypal"></a>
9</p>
10
11## About
12
13This plugin is an alternative to GeSHi server-side code highlighting of DokuWiki with client-side [SyntaxHighlighter](https://github.com/syntaxhighlighter/syntaxhighlighter) by Alex Gorbatchev.<br />
14
15The subfolder `syntaxhighlighter4/dist` contains a build of [SyntaxHighlighter 4.x](https://github.com/syntaxhighlighter/syntaxhighlighter).<br />
16
17For compatibility and conflicts with others plugins, please refer to the official [DokuWiki SyntaxHighlighter4 plugin page](http://www.dokuwiki.org/plugin:syntaxhighlighter4).
18
19## Download and Installation
20
21Download and install the plugin using the [Plugin Manager](https://www.dokuwiki.org/plugin:plugin) using the download link given above. Refer to [Plugins](https://www.dokuwiki.org/plugins) on how to install plugins manually.<br />
22
23If you install this plugin manually, make sure it is installed in `lib/plugins/syntaxhighlighter4/`. If the folder is called different it will not work!
24
25## Syntax and Usage
26
27```
28<sxh [brush][; options]>
29... code/text ...
30</sxh>
31```
32
33### Brush
34
35The brush (language) that SyntaxHighlighter should use. Defaults to "text" if none is provided.<br />
36See the section [brushes and themes](#list-of-brushes-and-themes) for a complete list of available brushes.
37
38### Options
39
40Semicolon separated options for SyntaxHighlighter, see [SyntaxHighlighter Configuration](https://github.com/syntaxhighlighter/syntaxhighlighter/wiki/Configuration#per-element-configuration).<br />
41The plugin handles the [Block Title from SyntaxHighlighter 3](http://alexgorbatchev.com/SyntaxHighlighter/whatsnew.html#blocktitle) as an option, i.e. `title: <title string>;`.
42
43### Defaults
44
45[Syntaxhighlighter default options](https://github.com/syntaxhighlighter/syntaxhighlighter/wiki/Configuration#options) can be overrided via the [Config Manager](https://www.dokuwiki.org/plugin:config) :
46* **autoLinks**: Allows you to turn detection of links in the highlighted element on and off. If the option is turned off, URLs won’t be clickable `(default true)`
47* **firstLine**: Allows you to change the first (starting) line number `(default 1)`
48* **gutter**: Allows you to turn gutter with line numbers `(default true)`
49* **htmlScript**: Allows you to highlight a mixture of HTML/XML code and a script which is very common in web development. Setting this value to true requires that you have shBrushXml.js loaded and that the brush you are using supports this feature `(default false)`
50* **smartTabs**: Allows you to turn smart tabs feature on and off `(default true)`
51* **tabSize**: Allows you to adjust tab size `(default 4)`
52* **override**: List of tags to override
53
54## Example
55
56```
57<sxh php; first-line: 89; highlight: [106,107]; title: New title attribute in action>
58    /**
59     * Render xhtml output or metadata
60     *
61     * @param string         $mode      Renderer mode (supported modes: xhtml)
62     * @param Doku_Renderer  $renderer  The renderer
63     * @param array          $data      The data from the handler() function
64     * @return bool If rendering was successful.
65     */
66    public function render($mode, Doku_Renderer &$renderer, $data) {
67        if($mode != 'xhtml') return false;
68
69        if (count($data) != 3) {
70            return true;
71        }
72
73        list($syntax, $attr, $content) = $data;
74        if ($syntax == 'sxh') {
75            $title = $this->procTitle($attr);
76            $highlight = $this->procHighlight($attr);
77            $renderer->doc .= '<pre class="brush: ' . strtolower($attr . $highlight) . '"' . $title . '>' . $renderer->_xmlEntities($content) . '</pre>';
78        } else {
79            $renderer->file($content);
80        }
81
82        return true;
83    }
84</sxh>
85```
86
87Expected result:
88
89![](resources/example.png)
90
91## Features
92
93### Copy to clipboard
94
95Double click anywhere inside SyntaxHighlighter code area to highlight the text and then copy it using Ctrl/Cmd+C or mouse right click > Copy.<br />
96Click outside the code area to restore highlighting.
97
98### Highlight a range of lines
99
100Example:
101
102```
103<sxh php; highlight: [11-15]>
104    /**
105     * [Custom event handler which performs action]
106     *
107     * @param Doku_Event $event  event object by reference
108     * @param mixed      $param  [the parameters passed as fifth argument to register_hook() when this
109     *                           handler was registered]
110     * @return void
111     */
112
113    public function handle_metaheader(Doku_Event &$event, $param) {
114        // Add SyntaxHighlighter theme.
115        $event->data['link'][] = array('rel' => 'stylesheet',
116            'type' => 'text/css',
117            'href' => DOKU_BASE . 'lib/plugins/syntaxhighlighter4/dist/'.$this->getConf('theme'),
118        );
119
120        // Register SyntaxHighlighter javascript.
121        $event->data["script"][] = array("type" => "text/javascript",
122            "src" => DOKU_BASE . "lib/plugins/syntaxhighlighter4/dist/syntaxhighlighter.js",
123            "_data" => ""
124        );
125    }
126</sxh>
127```
128
129Expected result:
130
131![](resources/highlight-range.png)
132
133### List of brushes and themes
134
135* **[Official brushes](https://github.com/syntaxhighlighter/syntaxhighlighter/wiki/Brushes-and-Themes)**
136  * applescript
137  * as3
138  * base
139  * bash
140  * coldfusion
141  * cpp
142  * csharp
143  * css
144  * delphi
145  * diff
146  * erlang
147  * groovy
148  * haxe
149  * java
150  * javafx
151  * javascript
152  * perl
153  * php
154  * plain
155  * powershell
156  * python
157  * ruby
158  * sass
159  * scala
160  * sql
161  * swift
162  * tap
163  * typescript
164  * vb
165  * xml
166* **Custom brushes**
167  * halcon
168  * IEC61131
169  * kotlin
170  * latex
171  * Makefile
172  * mel
173  * objective-c
174  * yaml
175* **[Official themes](https://github.com/syntaxhighlighter/syntaxhighlighter/wiki/Brushes-and-Themes)**
176  * default
177  * django
178  * eclipse
179  * emacs
180  * fadetogrey
181  * mdultra
182  * midnight
183  * rdark
184  * swift
185* **Custom themes**
186
187## How can I help ?
188
189All kinds of contributions are welcome :raised_hands:! The most basic way to show your support is to star :star2: the project, or to raise issues :speech_balloon: You can also support this project by [**becoming a sponsor on GitHub**](https://github.com/sponsors/crazy-max) :clap: or by making a [Paypal donation](https://www.paypal.me/crazyws) to ensure this journey continues indefinitely! :rocket:
190
191Thanks again for your support, it is much appreciated! :pray:
192
193## License
194
195GPLv2. See `LICENSE` for more details.<br />
196Icon credit to [Snip Master](http://www.snipicons.com/).
197