Writerside Help

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.

In semantic markup, use the <code> tag. 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 illustrate pieces of source code, configuration files, command-line interaction, and REST API calls.

In semantic markup, use the <code-block> tag 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"); } } ```
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 Code-block Copy button icon icon.

Code blocks can have the following attributes:

lang

Specify the programming or markup language. In Markdown, specify it after the opening ```.

collapsible=[true|false]

Make the code block collapsible if it is long.

<code-block lang="java" collapsible="true"> 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"); } } ``` {collapsible="true"}

Result:

class MyClass { public static void main(String[] args) { System.out.println("Hello, World"); } }
default-state=[collapsed|expanded]

By default, a collapsible code block is rendered collapsed. Set default-state="expanded" if you want to expand the code block by default.

<code-block lang="java" collapsible="true" default-state="expanded"> 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"); } } ``` {collapsible="true" default-state="expanded"}

Result:

class MyClass { public static void main(String[] args) { System.out.println("Hello, World"); } }
collapsed-title

Specify the title to when the code block is collapsed.

<code-block lang="java" collapsible="true" collapsed-title="MyClass.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"); } } ``` {collapsible="true" collapsed-title="MyClass.java"}

Result:

class MyClass { public static void main(String[] args) { System.out.println("Hello, World"); } }
collapsed-title-line-number

Specify the line to use as the title when the code block is collapsed.

<code-block lang="java" collapsible="true" collapsed-title-line-number="2"> 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"); } } ``` {collapsible="true" collapsed-title-line-number="2"}

Result:

class MyClass { public static void main(String[] args) { System.out.println("Hello, World"); } }
src

Name of the file with the source code that you want to use in the code block.

For more information, see Reference code from file.

include-lines

Range or comma-separated list of lines that you want to include. For example, include-lines="1-5,10" will include lines 1 to 5, and line 10.

include-symbol

Specify the code symbol to include, such as the name of the class, function, or variable. For example, include-symbol="MyClass.myfunction()" will include myFunction() of MyClass.

validate=[true|false]

Set true to validate the code in a snippet.

prompt

Add a non-selectable prompt symbol to the beginning of the code block. This is useful for command-line examples, where you need to show the prompt, such as >>> or $.

echo "Hello"

Readers cannot select and copy the prompt in rendered output, so if the block of code is a runnable command, the user can copy and paste it without having to clean up the prompt marker.

ignore-vars

Do not resolve %variables% in code blocks. Alternatively, you can escape the percent character with &percnt;.

noinject

Do not inject the code block content as the specified language. This means there will be no assistance in the editor, such as highlighting and completion.

Do not resolve links in code blocks.

id

Specify a unique identifier to use as a link anchor and generate a meaningful URL for this code block. You can reference and reuse any element that has an ID.

filter

Define a set of custom filters for conditionally including this code block.

instance

Define a set of instances for conditionally filtering this code block.

switcher-key

Make this code block switchable depending on the selected key.

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.

  1. Specify the name of the directory with code samples in the <snippets> element of writerside.cfg.

    <snippets src="codeSnippets"/>
  2. 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)) }
  3. 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:

val expected = 42

Alternatively, use the include-symbol attribute to specify the symbol to include, such as a specific function:

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

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

The <compare> element has the following attributes:

style=[left-right|top-bottom]

Select the arrangement of code blocks. By default, they are left-right.

first-title

Specify the first code block title. By default: Before.

second-title

Specify the second block title. By default: After.

id

Specify a unique identifier to use as a link anchor and generate a meaningful URL for this comparison block. You can reference and reuse any element that has an ID.

filter

Define a set of custom filters for conditionally including this comparison block.

instance

Define a set of instances for conditionally filtering this comparison block.

switcher-key

Make this comparison block switchable depending on the selected key.

Last modified: 20 February 2024