SwarmLab-HowTos/labs/Howtos/asciidoc/_includes/src.adoc

////
Included in:

- user-manual: Syntax Highlighting Source Code
////

Developers are accustomed to seeing source code colorized to emphasize the code's structure (i.e., keywords, types, delimiters, etc.).
This technique is known as [.term]_syntax highlighting_.
Since this technique is so prevalent--one could say expected--Asciidoctor integrates a wealth of libraries to syntax highlight the source code blocks in your document.
The list of integrated libraries includes Rouge, CodeRay, Pygments, highlight.js, and prettify.

=== Enabling Source Highlighting

When enabled, syntax highlighting gets applied to listing or literal blocks that have the `source` block style and a source language.
However, syntax highlighting is _not_ enabled by default.

To enable syntax highlighting in a document, you must set the `source-highlighter` document attribute.
You can set this attribute in the document or from the CLI or API.

If you set the attribute in the document, it _must_ be defined in the <<user-manual#doc-header,document header>>.

[source]
----
= Document Title
:source-highlighter: <value>
----

For example, here's how to enable syntax highlighting using Rouge:

[source]
----
= Document Title
:source-highlighter: rouge
----

.Source Highlighter vs. Syntax Highlighter
****
You might notice that the `source-highlighter` attribute uses the term "`source highlighter`", whereas the library that performs the highlighting is referred to as a "`syntax highlighter`".
What's the difference?

* The generally accepted term for a syntax (aka code) highlighter is "`syntax highlighter`".
* The syntax highlighter is applied to source blocks in AsciiDoc, hence why we say "`source highlighter`".

In other words, the `source-highlighter` attribute means "`use this syntax highlighter to colorize source blocks`".
****

=== Available Source Highlighters

The following table lists the recognized values for the `source-highlighter` attribute.

.Recognized values and supported environments for the `source-highlighter` attribute
[cols="1,1m,2"]
|===
|Library Name |Attribute Value |Supported Environments

|http://coderay.rubychan.de[CodeRay]
|coderay
|Asciidoctor, AsciidoctorJ, Asciidoctor PDF

|https://highlightjs.org[highlight.js]
|highlightjs
|Asciidoctor, AsciidoctorJ, Asciidoctor.js

|https://github.com/google/code-prettify[prettify]
|prettify
|Asciidoctor, AsciidoctorJ, Asciidoctor.js

|http://pygments.org[Pygments]
|pygments
|Asciidoctor, Asciidoctor PDF

|http://rouge.jneen.net[Rouge]
|rouge
|Asciidoctor, Asciidoctor PDF
|===

[IMPORTANT]
====
To use Rouge, CodeRay, or Pygments, you must have the appropriate library installed on your system.
See the <<rouge>>, <<coderay>>, or <<pygments>> section to find installation instructions.

On the other hand, if you're using a client-side syntax highlighting library like highlight.js or prettify, there's no need to install additional libraries.
The generated HTML will load the required source files from a CDN (or custom URL or file path).
====

=== Applying Source Highlighting

To apply highlighting to source code, you must add the `source` block style to a listing block, literal block, or paragraph and also specify a source language.

[listing]
.Code block with title and syntax highlighting
....
include::ex-src.adoc[tag=src-base-co]
....
<1> An optional title can be added to the block.
<2> An optional ID can be added to the block. See <<anchordef>>.
<3> Assign the block name `source` to the first position in the attribute list.
<4> Assign a source language to the second position.
<5> The source block name is typically assigned to listing and literal blocks.

.Result: Source block with title and syntax highlighting
====
include::ex-src.adoc[tag=src-base-co-res]
====

.Source paragraph
----
include::ex-src.adoc[tag=src-para-co]
----
<1> Place the attribute list directly on the paragraph.
<2> Once an empty line is encountered the syntax highlighting is unset.

.Result: Source paragraph
====
include::ex-src.adoc[tag=src-para]
====

If the majority of your source blocks use the same source language, you can set the `source-language` attribute in the document header and assign a language to it.

[listing]
.Source language attribute
....
include::ex-src.adoc[tag=src-lang]
....

Additionally, you can use an <<user-manual#include-directive,include directive>> to insert source code into an AsciiDoc document directly from a file.

[listing]
.Code block inserted from another file
....
include::ex-src.adoc[tag=src-inc]
....

//TODO mention the use of AsciiDoc tags to include code snippets and the indent flag to reset indentation

TIP: If you specify custom substitutions on the source block using the `subs` attribute, make sure to include the `specialcharacters` substitution if you want to preserve syntax highlighting.
However, if you do plan to modify the substitutions, we recommend using <<incremental-substitutions,incremental substitutions>> instead.

.Highlighting PHP source code
****
The PHP language has two modes.
It can either be used as a standalone language (pure mode) or it can be mixed with HTML (mixed mode) by putting it inside PHP tags (a form that resembles an XML processing instruction).
This presents some challenges for the syntax highlighter.

If the code in the source block is pure PHP, you should use the language tag `php`.
For example:

[listing]
....
[source,php]
----
echo "Hello, World!";
----
....

If the PHP source is mixed with HTML, you should either use the language tag `html+php`, as shown here:

[listing]
....
[source,html+php]
----
<p>
<?php echo "Hello, World!"; ?>
</p>
----
....

Or you could use the language tag `php` and set the `mixed` option on the source block, as shown here:


[listing]
....
[source%mixed,php]
----
<p>
<?php echo "Hello, World!"; ?>
</p>
----
....

Under the covers, the syntax highlighter is configured to assume an implicit start PHP tag is present when the language tag is `php`.
Both the `mixed` option and the language tag `html+php` disable this setting.
****