---json
{
    "page_id": "gu0x6gxoe28jqvv2q8hih"
}
---

====== ComboStrap - Prism ======


===== About =====
''Prism'' components permits to add raw external content in the web page with extra's such as
   * ''line number'', ''copy to clipboard''
   * and eventually code highlighting


The following ''component'' are ''prism component'':
  * [[docs:block:code|code]] - to highlight code
  * [[docs:block:file|file]] - to shows the content of a file,
  * [[docs:block:console|console]] - to show the output of a command at the terminal
  * [[docs:block:preformatted|preformatted]] - to quote and show unformatted text based on simple text indentation






===== Example =====
==== Line numbers ====

''HTML'' code in a [[docs:block:code|code component]] with the following syntax,
<webcode name="Default" frameborder="0">
```dw
<code html line-numbers="true">
    <p class="hey">Type some code here</p>
</code>
```
You will get this output:
</webcode>

==== Line Highlight ====

This example shows an ''HTML'' code in a [[docs:block:code|code component]] where the lines:
  * ''1'' to ''3''
  * and ''5''
are highlighted

Example:
<webcode>
```dw
<code html line-numbers="true" line-highlight="1-3, 5">
    <p>Line 1</p>
    <p>Line 2</p>
    <p>Line 3</p>
    <p>Line 4</p>
    <p>Line 5</p>
</code>
```
With this markup, you will get this output:
</webcode>



==== Prompt ====

This example shows a bash prompt.

Example with ''HTML'' code in a [[docs:block:code|code component]]:
<file html>
<code bash prompt="#">
ls -a
</code>
</file>
With this markup, you will get this output:
<code bash prompt="#">
ls -a
</code>

==== File Name ====

This example shows you how to defined a file name.

Example: A [[:docs:block:file|file block]] with the file name ''loremipsum.txt''
<code xml>
<file txt loremipsum.txt>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum
</file>
</code>
With the above  markup, you will get this output:
<file txt loremipsum.txt>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum
</file>


==== Constrained by height ====
''prism'' component may contain a big content that is not completely relevant for the reading of article. In this case, you can constrained it in [[docs:styling:dimension|height]]

<code dw>
<file txt loremipsum.txt height="150px" scroll="toggle">
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
Ut enim ad minim veniam, quis nostrud exercitation ullamco
Duis aute irure dolor in reprehenderit in voluptate velit esse
Excepteur sint occaecat cupidatat non proident, sunt in culp

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
Ut enim ad minim veniam, quis nostrud exercitation ullamco
Duis aute irure dolor in reprehenderit in voluptate velit esse
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum
</file>
</code>

Result:
<file txt loremipsum.txt height="150px" scroll="toggle">
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
Ut enim ad minim veniam, quis nostrud exercitation ullamco
Duis aute irure dolor in reprehenderit in voluptate velit esse
Excepteur sint occaecat cupidatat non proident, sunt in culp

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
Ut enim ad minim veniam, quis nostrud exercitation ullamco
Duis aute irure dolor in reprehenderit in voluptate velit esse
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum
</file>




===== Syntax =====


Except from [[docs:block:preformatted|preformatted]] that is based on indentation, they all follows the below syntax:

<file html>
<component language [file-path] line-numbers="true" prompt="$" line-highlight="x-y, z">
    .... your code
</component>
</file>
where:
  * ''language'' is the language of the code (''html'', ''xml'', ...). Find all [[https://prismjs.com/#supported-languages|supported languages in the Prism website]]
  * ''file-path'' is an optional argument that gives the name of the file that will show up in the download button when hovering over the component.
  * ''line-numbers'' will show line numbers if present
  * ''prompt'' will add a command line prompt
  * ''your code'' is a placeholder for your code
  * ''line-higlight'' defines the lines to highlight. It accepts:
    * A single number refering to the line
    * A range of lines (two numbers separated with a hyphen)
    * A serie of line numbers or ranges separated by commas.



===== Configuration =====

==== Theme ====


The ''code_theme'' [[docs:app:configuration|configuration]] permits to choose the [[https://prismjs.com/|prism theme]].

The following themes are available:
  * ''prism'' - the default prism theme
  * ''coy''
  * ''dark''
  * ''funky''
  * ''okaidia''
  * ''solarizedlight''
  * ''tomorrow''
  * ''twilight''
You can check them on the [[https://prismjs.com/|Prism website]] by clicking on the theme name in the right toolbar.

==== Prompt ====

You can define default prompt for the languages:
  * ''bash''
  * ''batch'' (''dos'')
  * ''powershell''

<note>
Windows Prompt: The prism component will add automatically a ''>'' at the end of the windows shell prompt (''batch'' and ''powershell'') if not present. This is not possible to pass the character ''>'' via the syntax argument because the dokuwiki parser is based on regular expression.
</note>

===== Note =====

The prism components are based on the [[https://prismjs.com/|Prism library]]
==== Supported Plugin ====
This component integrates the following Prism plugin:
  * [[https://prismjs.com/plugins/download-button|Download button]]
  * [[https://prismjs.com/plugins/line-numbers/|Line Numbers]]
  * [[https://prismjs.com/plugins/command-line/|Command line]]
  * [[https://prismjs.com/plugins/show-language/|Show Language]]
  * [[https://prismjs.com/plugins/normalize-whitespace/|Normalize Whitespace]]
  * [[https://prismjs.com/plugins/line-highlight/|Line Highlight]]

If you want more plugin, just [[:support|ask]]
==== Code Annotation ====
Prism does not support out of the box code annotation such as the [[https://docs.asciidoctor.org/asciidoc/latest/verbatim/callouts/|Asciidoctor callout]].

The possibilities are:
  * Just add a comment. Example:
<code bash>
myCode # (3)
</code>
  * or use the following prism plugin that permits code annotation but are not yet implemented
      * The [[https://prismjs.com/plugins/keep-markup/|Keep Markup (ie keep HTML)]]. With the keep markup, you can add HTML markup such as ''mark'' to highlight your code. It does not work yet because Dokuwiki escapes the whole block of code. Another component should be created for this purpose.
      * [[#Line highlight]] permits to highlight a line number.

See also this prism [[https://prismjs.com/faq.html#if-pre-existing-html-is-stripped-off-how-can-i-highlight|faq entry]]

===== Support =====

==== Regex language ====

''Dokuwiki'' set a ''group'' class to apply a ''clearfix'' in its ''all.css'' file. This name pollute the css global scope and competes with the output of the ''regex'' prism language that set it on the regexp ''group''. The result is that there is a new line on all ''('' and '')'' characters.

As you can see below, this is no more the case.
<code regex >
^(\\w+\\s+\\d+\\s+\\d+:\\d+:\\d+)\\s+
([^@]+?)@(\\s+)\\s+(\\S+):\\s+(\\S+)\\s+(\\S+)
\\s+((?:\\S+?,\\s+)*(?:\\S+?))\\s+(\\S+)\\s+(\\S+)
\\s+\\[([^\\]]+)\\]\\s+\"(\\w+)\\s+([^\"\\\\]*
(?:\\\\.[^\"\\\\]*)*)\\s+(\\S+)\"\\s+(\\S+)\\s+
(\\S+)\\s+\"([^\"\\\\]*(?:\\\\.[^\"\\\\]*)*)
\"\\s+\"([^\"\\\\]*(?:\\\\.[^\"\\\\]*)*)\"\\s*
(\\d*-[\\d-]*)?\\s*(\\d+)?\\s*(\\d*\\.[\\d\\.]*)?
(\\s+[-\\w]+)?.*$
</code>