Code
With Writerside, you can format pieces of text as code, insert blocks of code, command input and output examples, and compare pieces of code.
Use inline formatting to wrap a piece of text as a variable, method, or function name, a command or option.
To insert some inline code, use the <code> element. In Markdown, use single backticks `.
Call the <code>getAllItems()</code> method.Call the `getAllItems()` method. Call the getAllItems() method.
Use code blocks to provide samples of source code, configuration files, command-line interaction, or REST API calls.
To add a code block, use the <code-block> element and specify the language in the lang attribute. In Markdown, use triple backticks ``` and specify the language directly after the opening backticks.
<code-block lang="java">
class MyClass {
public static void main(String[] args) {
System.out.println("Hello, World");
}
}
</code-block>```java
class MyClass {
public static void main(String[] args) {
System.out.println("Hello, World");
}
}
```Result:
class MyClass {
public static void main(String[] args) {
System.out.println("Hello, World");
}
}Your readers can copy the contents of the code block by clicking the 
icon.
note
Writerside uses Prism for code highlighting in the produced output. For a full list of supported languages, see Supported languages.
For highlighting and other assistance features in the editor, Writerside requires the corresponding language support plugin.
If you need to provide a sample of XML or HTML code, wrap the contents of the code block with a CDATA section. This will prevent Writerside from processing tags. You can also use the corresponding intention action for this.
<code-block lang="xml">
<![CDATA[
<some-tag>text in tag</some-tag>
]]>
</code-block> Alternatively, you can escape the < and > characters using < and >.
<code-block lang="xml">
<some-tag>text in tag</some-tag>
</code-block>Specify links to topics and external URLs from code blocks as [[[text|URL]]].
<code-block lang="java">
class MyClass {
public static void [[[main(String[] args)|https://en.wikipedia.org/wiki/Entry_point]]] {
System.out.println("Hello, World");
}
}
</code-block>```java
class MyClass {
public static void [[[main(String[] args)|https://en.wikipedia.org/wiki/Entry_point]]] {
System.out.println("Hello, World");
}
}
```Result:
class MyClass {
public static void main(String[] args) {
System.out.println("Hello, World");
}
}To disable links and render [[[text|URL]]] as is, set disable-links="true".
You can add files with code samples to a dedicated directory in your documentation project and use them in multiple code blocks. This is better than adding the same code samples literally and provides a single place for managing your code samples.
Specify the name of the directory with code samples in the <snippets> element of writerside.cfg.
<snippets src="codeSnippets"/>note
This directory must be in the documentation project. Although it can be a symlink to another directory, keep in mind that the files must be available during the build.
Add a file with code to the code snippets directory, for example:
newTest.kt{...}Use the
srcattribute to specify the file name:Semantic markupMarkdown<code-block lang="kotlin" src="newTest.kt"/>```kotlin ``` { src="newTest.kt" }Result:
@Test fun testSum() { val expected = 42 assertEquals(expected, testSample.sum(40, 2)) } @Test fun testMultiply() { val expected = 42 assertEquals(expected, testSample.multiply(21, 2)) }
Although referencing files from a dedicated directory is more convenient, you do not need to do it this way. Instead of registering the snippets directory, you can reference files using a path relative to the current topic file:
<code-block lang="kotlin" src="../code-samples/newTest.kt"/>```kotlin
```
{ src="../code-samples/newTest.kt" }You can also specify which parts of the code from the file you want in a code block. For example, use the include-lines attribute to specify lines to include:
<code-block lang="kotlin" src="newTest.kt" include-lines="3"/>```kotlin
```
{ src="newTest.kt" include-lines="3" }Result:
val expected = 42Alternatively, use the include-symbol attribute to specify the symbol to include, such as a function:
<code-block lang="kotlin" src="newTest.kt" include-symbol="testMultiply"/>```kotlin
```
{ src="newTest.kt" include-symbol="testMultiply" }Result:
@Test
fun testMultiply() {
val expected = 42
assertEquals(expected, testSample.multiply(21, 2))
}Use the <compare> element to demonstrate the difference between two code blocks, for example, before and after refactoring.
<compare>
<code-block lang="kotlin">
if (true) {
doThis()
}
</code-block>
<code-block lang="kotlin">
if (true) doThis()
</code-block>
</compare>Result:
Before
if (true) { doThis()}After
if (true) doThis()