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.

XML and HTML code

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">
                &lt;some-tag&gt;text in tag&lt;/some-tag&gt;
                </code-block>
            

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)) }

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 = 42

Alternatively, 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))
}

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()

        import sys

        if __name__ == "__main__":
            print("Hello world")
    

Last modified: 11 November 2024