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.

Inline 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.

Code blocks

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.

Links in code blocks

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)|https://en.wikipedia.org/wiki/Entry_point]]] {
                        System.out.println("Hello, World");
                    }
                }
            

To disable links and render [[[text|URL]]] as is, set disable-links="true".

Reference code from file

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"/>
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:
@Test fun testSum() { val expected = 42 assertEquals(expected, testSample.sum(40, 2)) } @Test fun testMultiply() { val expected = 42 assertEquals(expected, testSample.multiply(21, 2)) }
Use the src attribute to specify the file name:
<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)) }

You can also insert specific pieces of the code from the file in separate code blocks. 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 = 42

Alternatively, use the include-symbol attribute to specify the symbol to include, such as a specific 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))
}

Compare code blocks

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:

                    if (true) {
                        doThis()
                    }
                

if (true) doThis()

Last modified: 14 May 2024