~~PAGEIMAGE:{{:tools:dokuwiki:codeprism:media:20231026-160617.png}}~~

====== CodePrism ======

{{template>meta:template:pageinfo#tpl
|desc=Introduce Dokuwiki plugin <wrap pkg>Codeprism</wrap>.}}

This plugin is designed to get great syntax highlighting by using
[[https://prismjs.com/index.html|Prism]]. You can watch the [[#demo|Demo]]
first to check if it meets your needs. <wrap pkg>Codeprism</wrap> has been
posted to the Dokuwiki community at [[https://www.dokuwiki.org/plugin:codeprism]].

<mermaid auto 400px>
timeline
  title History of Codeprism
  Jul 12, 2023 : Start developing beta version
  Jul 14, 2023 : Start using beta in self-hosted site
  Dec 3, 2023 : Release Ver 1.0 and manual
</mermaid>

===== Syntax =====

<wrap pkg>Codeprism</wrap> supports two syntax: 
  * <wrap cmd>%%<%%codeprism <wrap cmdp>attributes</wrap>%%>%%</wrap>Your code...<wrap cmd>%%<%%/codeprism%%>%%</wrap>
  * <wrap cmd>%%<%%fileprism <wrap cmdp>attributes</wrap>%% />%%</wrap>

[[#tab-1|Table 1]] and [[#tab-2|Table 2]] list the attributes supported by the above syntax.

<TEXT align="center"><wrap #tab-1 />Table 1. Attributes supported by ''%%<codeprism>%%''</TEXT>

^ Key                         ^ Description                                        ^ Value                                                                                                                                                                                                                                                                 ^ Example                  ^
| <wrap #title />''title''    | Specify code title                                 | A string without spaces.                                                                                                                                                                                                                                              | ''title=codeprism.css''  |
| <wrap #el />''el''          | Enable line numbers                                | ''true'', ''false''.                                                                                                                                                                                                                                                  | ''el=true''              |
| ''sl''                      | Start line number                                  | One number.                                                                                                                                                                                                                                                           | ''sl=10''                |
| <wrap #hl />''hl''          | Highlight line numbers                             | One number or multiple numbers with '','' or ''-'' (''-'' indicates range).                                                                                                                                                                                           | ''hl=1,3,4-9''           |
| ''lang''                    | Language                                           | See [[https://prismjs.com/index.html#supported-languages|this page]].                                                                                                                                                                                                 | ''lang=php''             |
| <wrap #cmd />''cmd''        | Command line style                                 | ''true''. (If ''[[#cmdout|cmdout]]'' is set, ''cmd'' is set to ''true'' by default.)                                                                                                                                                                                  | ''cmd=true''             |
| <wrap #cmdout />''cmdout''  | Command output line numbers                        | One number or multiple numbers with '','' or ''-'' (''-'' indicates range).                                                                                                                                                                                           | ''cmdout=2,4,6-9''       |
| <wrap #css />''css''        | Assign a custom CSS to the code block              | Default is ''dft''. You can create a CSS named ''pre.dokuwiki-plugin-codeprism-**custom**'' ((note:>''custom'' is any word you like to use)) in <wrap file>[[https://www.dokuwiki.org/devel:css#user_styles|conf/userstyle.css]]</wrap>and use it by ''css=custom''.  | ''css=custom''           |
| ''user''                    | Specify the user name at the command shell prompt  | A string without spaces. (If the ''user'' is not specified, the default user name configured in the <wrap menu>Configuration Settings</wrap> is used. You can also use ''user'' to re-specify a new user name.)                                                       | ''user=Source''          |
| ''host''                    | Specify the host name at the command shell prompt  | A string without spaces. (If the ''host'' is not specified, the default host name configured in the <wrap menu>Configuration Settings</wrap> is used. You can also use ''host'' to re-specify a new host name.)                                                       | ''host=Debian''          |

<TEXT align="center"><wrap #tab-2 />Table 2. Attributes supported by ''%%<fileprism>%%''</TEXT>

^ Key        ^ Description                                      ^ Value                                                                                                         ^ Example                                      ^
| ''src''    | Specifies file path                              | File path.                                                                                                    | ''src=:media:code:test.py''                  |
| ''range''  | Specifies the lines to be displayed in the file  | ''n'' for display line n.\\ ''n,'' for display all lines start at n.\\ ''m,n'' for display line m to line n.  | ''range=4''\\ ''range=4,''\\ ''range=4,20''  |
| ''hl''     | See ''[[#hl|hl]]'' in ''codeprism''              |                                                                                                               |                                              |
| ''el''     | See ''[[#el|el]]'' in ''codeprism''              |                                                                                                               |                                              |
| ''css''    | See ''[[#css|css]]'' in ''codeprism''            |                                                                                                               |                                              |
| ''title''  | See ''[[#title|title]]'' in ''codeprism''        |                                                                                                               |                                              |

===== Configuration and Settings =====

<WRAP not>Table 3. Configuration and Settings</WRAP>
^ Setting               ^ Description                                                                                                  ^
| ''theme''             | Specify Codeprism theme.                                                                                     |
| <wrap #cdn />''cdn''  | Specify a CDN which provide PrismJS.                                                                         |
| ''custom-cdn''        | Specify the CDN yourself if the CDNs listed in the <wrap menu>[[#cdn|cdn]]</wrap> does not meet your needs.  |
| ''override-code''     | **True** to override ''code'' syntax.                                                                        |
| ''show-invis''        | **True** to show hidden characters such as tabs and line breaks.                                             |
| ''hl-brace''          | **True** to highlight brace pairs when the cursor hovers over one of the braces.                             |
| ''previewer''         | **True** to enable preview angle, color, gradient, easing, and time.                                         |
| ''user''              | Specify the default user name at the command shell prompt when using [[#cmd|command line style]].            |
| ''host''              | Specify the default host name at the command shell prompt when using [[#cmd|command line style]].            |

===== Demo =====
==== Highlight ====
=== Demo 1 ===

{{template>meta:template:codedemo#tpl|code=
<codeprism lang=php title=codeprism.php>
        switch ($state) {
        case DOKU_LEXER_ENTER:
            list(, $opt_arr) = $data;

            ...
            foreach($opt_arr as $key => $val) {
                $renderer->doc .= ' ' . $key . '="' . $val . '"';
            }

            $renderer->doc .='>';
            $renderer->doc .='<code class="language-'. $opt_arr['data-language']  .'">';
            break;
            ...
</codeprism>}}

=== Demo 2 ===

{{template>meta:template:codedemo#tpl|code=
<codeprism lang=php hl=3,6-8>
        switch ($state) {
        case DOKU_LEXER_ENTER:
            list(, $opt_arr) = $data;

            ...
            foreach($opt_arr as $key => $val) {
                $renderer->doc .= ' ' . $key . '="' . $val . '"';
            }

            $renderer->doc .='>';
            $renderer->doc .='<code class="language-'. $opt_arr['data-language']  .'">';
            break;
            ...
</codeprism>}}

=== Demo 3 ===

{{template>meta:template:codedemo#tpl|code=
<codeprism lang=php sl=21 hl=23,26-28 el=true>
        switch ($state) {
        case DOKU_LEXER_ENTER:
            list(, $opt_arr) = $data;

            ...
            foreach($opt_arr as $key => $val) {
                $renderer->doc .= ' ' . $key . '="' . $val . '"';
            }

            $renderer->doc .='>';
            $renderer->doc .='<code class="language-'. $opt_arr['data-language']  .'">';
            break;
            ...
</codeprism>}}

==== File ====

=== Demo 1 ===

{{template>meta:template:codedemo#tpl|code=
<fileprism src=:tools:dokuwiki:codeprism:media:codeprism.txt range=4,20 hl=16/>}}

=== Demo 2 ===

{{template>meta:template:codedemo#tpl|code=
<fileprism src=:tools:dokuwiki:codeprism:media:codeprism.txt range=20, el=true/>}}

==== Command Line ====
{{template>meta:template:codedemo#tpl|code=
<codeprism lang=bash cmd=true cmdout=2-15 user=source host=debian>
tree 
.
├── action.php
├── codeprism.css
├── conf
│   ├── default.php
│   └── metadata.php
├── lang
│   └── en
│       └── settings.php
├── plugin.info.txt
├── README.md
└── syntax.php

3 directories, 8 files.
</codeprism>}}

==== CSS Preview ====

{{template>meta:template:codedemo#tpl|code=
<codeprism lang=css>
.example-gradient {
	background: -webkit-linear-gradient(left,     #cb60b3 0%, #c146a1 50%, #a80077 51%, #db36a4 100%); /* Chrome10+, Safari5.1+ */
	background:    -moz-linear-gradient(left,     #cb60b3 0%, #c146a1 50%, #a80077 51%, #db36a4 100%); /* FF3.6+ */
	background:     -ms-linear-gradient(left,     #cb60b3 0%, #c146a1 50%, #a80077 51%, #db36a4 100%); /* IE10+ */
	background:      -o-linear-gradient(left,     #cb60b3 0%, #c146a1 50%, #a80077 51%, #db36a4 100%); /* Opera 11.10+ */
	background:         linear-gradient(to right, #cb60b3 0%, #c146a1 50%, #a80077 51%, #db36a4 100%); /* W3C */
}
.example-angle {
	transform: rotate(10deg);
}
.example-color {
	color: rgba(255, 0, 0, 0.2);
	background: purple;
	border: 1px solid hsl(100, 70%, 40%);
}
.example-easing {
	transition-timing-function: linear;
}
.example-time {
	transition-duration: 3s;
}
</codeprism>}}

==== Custom Code Block ====

I've created two CSS in <wrap file>codeprism.css</wrap> of the <wrap pkg>codeprism</wrap> plugin,
so let's see how the ''css'' attribute works.

<codeprism lang=css title=codeprism.css>
pre.dokuwiki-plugin-codeprism-dft {
	max-height: 30rem;
	overflow: auto;
}

pre.dokuwiki-plugin-codeprism-full {
	overflow: auto;
}
</codeprism>

=== Default Code Block ===

By default, code block is limited to **30rem** in height. Therefore,
when there are too many lines of code, vertical scrollbar appears.

{{template>meta:template:codedemo#tpl|code=
<fileprism src=:tools:dokuwiki:codeprism:media:codeprism.txt el=true/>}}

=== Full Code Block ===

The height of the code block is __no longer limited__ after ''full'' CSS is applied.

{{template>meta:template:codedemo#tpl|code=
<fileprism src=:tools:dokuwiki:codeprism:media:codeprism.txt el=true css=full/>}}

{{template>meta:template:refnote#note}}

===== Further Reading =====

  * [[https://prismjs.com/index.html]]