README.md
1:boom: **[SyntaxHighlighter 4 Plugin](https://github.com/crazy-max/dokuwiki-plugin-syntaxhighlighter4) is now available!** :boom:
2
3<p align="center">
4 <a href="https://github.com/crazy-max/dokuwiki-plugin-syntaxhighlighter3/releases"><img src="https://img.shields.io/github/release/crazy-max/dokuwiki-plugin-syntaxhighlighter3.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%20Ponder%20Stibbons-yellow.svg?style=flat-square" alt="Minimum DokuWiki Version"></a>
6 <a href="https://www.codacy.com/app/crazy-max/dokuwiki-plugin-syntaxhighlighter3"><img src="https://img.shields.io/codacy/grade/9901ac6898434b05a75b5d9bfcd81029.svg?style=flat-square" alt="Code Quality"></a>
7 <a href="https://styleci.io/repos/61027126"><img src="https://styleci.io/repos/61027126/shield?style=flat-square" alt="StyleCI"></a>
8 <a href="https://beerpay.io/crazy-max/dokuwiki-plugin-syntaxhighlighter4"><img src="https://img.shields.io/beerpay/crazy-max/dokuwiki-plugin-syntaxhighlighter4.svg?style=flat-square" alt="Beerpay"></a>
9 <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NMMSKWE5DPNFU"><img src="https://img.shields.io/badge/donate-paypal-blue.svg?style=flat-square" alt="Donate Paypal"></a>
10</p>
11
12## About
13
14This plugin is an alternative to GeSHi server-side code highlighting of DokuWiki with client-side [SyntaxHighlighter](http://alexgorbatchev.com/wiki/SyntaxHighlighter) by Alex Gorbatchev with copy to clipboard functionality based on [SyntaxHighlighter DokuWiki Plugin by David Shin](https://www.dokuwiki.org/plugin:syntaxhighlighter2).<br />
15
16The subfolder `sxh3` contains an untouched build of [SyntaxHighlighter 3.0.90](https://github.com/syntaxhighlighter/syntaxhighlighter/releases/tag/v3.0.90).<br />
17
18For compatibility and conflicts with others plugins, please refer to the official [DokuWiki SyntaxHighlighter3 plugin page](http://www.dokuwiki.org/plugin:syntaxhighlighter3).
19
20## Download and Installation
21
22Download 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 />
23
24If you install this plugin manually, make sure it is installed in `lib/plugins/syntaxhighlighter3/`. If the folder is called different it will not work!
25
26## Syntax and Usage
27
28* Does not use `<code>` tags, enables parallell use with DokuWikis own server side syntax highlighter (GeSHi).
29* Does not require Flash for copy to clipboard functionality.
30
31Usage:
32```
33<sxh [brush alias][; options for SyntaxHighlighter]>
34... code/text ...
35</sxh>
36```
37
38### Brush alias
39
40The brush alias (language) that SyntaxHighlighter should use. Defaults to "text" if none is provided. See [SyntaxHighlighter Brushes](http://alexgorbatchev.com/SyntaxHighlighter/manual/brushes/) for a complete list of available brushes.<br />
41Add new brushes to the scripts directory and the alias(es) and brush file name to the available brushes string in [Config Manager](https://www.dokuwiki.org/plugin:config) (example: "...,bat cmd shBrushBat.js"). The brush file name is case sensitive.
42
43### Options
44
45Semicolon separated options for SyntaxHighlighter, see [SyntaxHighlighter Configuration](http://alexgorbatchev.com/SyntaxHighlighter/manual/configuration/).<br />
46[Block Title](http://alexgorbatchev.com/SyntaxHighlighter/whatsnew.html#blocktitle) isn't a normal configuration option, but the plugin handles it as if it was, i.e. `title: <title string>;`.
47
48> Do not collapse code and hide the toolbar at the same time, title will not show.
49
50### Defaults
51
52Some [Syntaxhighlighter defaults](http://alexgorbatchev.com/SyntaxHighlighter/manual/configuration/#syntaxhighlighterdefaults) can be overrided via the [Config Manager](https://www.dokuwiki.org/plugin:config) :
53* **auto-links**: 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 on)`
54* **collapse**: Allows you to force highlighted elements on the page to be collapsed by default `(default off)`
55* **first-line**: Allows you to change the first (starting) line number `(default 1)`
56* **gutter**: Allows you to turn gutter with line numbers on and off `(default on)`
57* **html-script**: 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 off)`
58* **smart-tabs**: Allows you to turn smart tabs feature on and off `(default on)`
59* **tab-size**: Allows you to adjust tab size `(default 4)`
60* **toolbar**: Toggles toolbar on/off `(default on)`
61
62## Example
63
64```
65<sxh php; first-line: 70; highlight: [89,92]; title: New title attribute in action>
66 public function render($mode, &$renderer, $data) {
67
68 if($mode != 'xhtml') return false;
69
70 if (count($data) == 3) {
71 list($syntax, $attr, $content) = $data;
72 if ($syntax == 'sxh') {
73 // Check if there's a title in the attribute string. It can't be passed along as a normal parameter to SyntaxHighlighter.
74 if (preg_match("/title:/i", $attr)) {
75 // Extract title(s) from attribute string.
76 $attr_array = explode(";",$attr);
77 $title_array = preg_grep("/title:/i", $attr_array);
78 // Extract everything BUT title(s) from attribute string.
79 $not_title_array = preg_grep("/title:/i", $attr_array, PREG_GREP_INVERT);
80 $attr = implode(";",$not_title_array);
81 // If there are several titles, use the last one.
82 $title = array_pop($title_array);
83 $title = preg_replace("/.*title:\s{0,}(.*)/i","$1",$title);
84 // Add title as an attribute to the <pre /> tag.
85 $renderer->doc .= "<pre class=\"brush: ".$attr."\" title=\"".$title."\">".$renderer->_xmlEntities($content)."</pre>";
86 } else {
87 // No title detected, pass all attributes as parameters to SyntaxHighlighter.
88 $renderer->doc .= "<pre class=\"brush: ".$attr."\">".$renderer->_xmlEntities($content)."</pre>";
89 }
90 } else {
91 $renderer->file($content);
92 }
93 }
94
95 return true;
96 }
97</sxh>
98```
99
100Expected result:
101
102
103
104## Features
105
106### Copy to clipboard
107
108Double click anywhere inside SyntaxHighlighter code area to highlight the text and then copy it using Ctrl/Cmd+C or mouse right click > Copy.<br />
109Click outside the code area to restore highlighting.
110
111### Highlight a range of lines
112
113Example:
114
115```
116<sxh php; highlight: [9-18]>
117// Check highlight attr for lines ranges
118if (preg_match("/highlight:/i", $attr, $matches)) {
119 // Extract highlight from $attr string.
120 $attr_array = explode(";",$attr);
121 $highlight_array = preg_grep("/highlight:/i", $attr_array);
122 // Extract everything BUT highlight from $attr string.
123 $not_highlight_array = preg_grep("/highlight:/i", $attr_array, PREG_GREP_INVERT);
124 $attr = implode(";",$not_highlight_array);
125 // If there are multiple hightlights, use the last one.
126 $highlight_str = array_pop($highlight_array);
127 $highlight_str = preg_replace("/.*highlight:\s{0,}(.*)/i","$1", $highlight_str);
128 // Remove [ ]
129 $highlight_str = str_replace(array('[', ']'), '', $highlight_str);
130 // Process ranges if exists
131 $highlight_exp = explode(',', $highlight_str);
132 foreach ($highlight_exp as $highlight_elt) {
133 if (!empty($highlight)) {
134 $highlight .= ',';
135 }
136 $highlight_elt = trim($highlight_elt);
137 $highlight_elt_exp = explode('-', $highlight_elt);
138 if (count($highlight_elt_exp) == 2) {
139 foreach (range($highlight_elt_exp[0], $highlight_elt_exp[1]) as $key => $lineNumber) {
140 if ($key > 0) {
141 $highlight .= ',';
142 }
143 $highlight .= $lineNumber;
144 }
145 } else {
146 $highlight .= $highlight_elt;
147 }
148 }
149 $highlight = ' highlight: [' . $highlight . ']';
150}
151</sxh>
152```
153
154Expected result:
155
156
157
158## Issues and Features
159
160* https://github.com/crazy-max/dokuwiki-plugin-syntaxhighlighter3/issues
161
162## Changelog
163
164See `CHANGELOG.md`.
165
166## How can i help ?
167
168All kinds of contributions are welcomed :raised_hands:!<br />
169The most basic way to show your support is to star :star2: the project, or to raise issues :speech_balloon:<br />
170But we're not gonna lie to each other, I'd rather you buy me a beer or two :beers:!
171
172[](https://beerpay.io/crazy-max/dokuwiki-plugin-syntaxhighlighter4)
173or [](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NMMSKWE5DPNFU)
174
175## License
176
177> This is a modified version (fork) of SyntaxHighlighter3 Plugin for DokuWiki based on Daniel Lindgren's work.
178
179GPLv2. See `LICENSE` for more details.
180
){kind=link}
