Writerside

https://www.jetbrains.com/help/writerside
Admin
Writerside is a JetBrains IDE for creating, managing, and publishing technical documentation with...
Tokens:85,302
Snippets:1,446
Trust Score:10
Update:4 months ago
Show doc for...
Tokens:
Raw
### Example Keymap File Structure

Source: https://www.jetbrains.com/help/writerside/shortcuts.html

An example XML keymap file defining layouts for Windows, macOS, and Linux, along with actions and their corresponding shortcuts for each layout.

```XML
<?xml version="1.0" encoding="UTF-8"?>
<keymap id="my_keymap">
    <layouts>
        <layout name="Windows" platform="PC"/>
        <layout name="macOS" platform="MAC"/>
        <layout name="Linux" platform="PC"/>
    </layouts>
    <actions>
        <action id="$Copy">
            <description>Copy</description>
            <shortcut layout="Windows">Ctrl+C</shortcut>
            <shortcut layout="macOS">⌘ C</shortcut>
            <shortcut layout="Linux">Ctrl+C</shortcut>
        </action>
        <action id="$Paste">
            <description>Paste</description>
            <shortcut layout="Windows">Ctrl+V</shortcut>
            <shortcut layout="macOS">⌘ V</shortcut>
            <shortcut layout="Linux">Ctrl+V</shortcut>
        </action>
    </actions>
</keymap>
```

--------------------------------

### Example Preview Link

Source: https://www.jetbrains.com/help/writerside/preview-and-test-docs.html

This is an example of a preview link generated by the Writerside Preview tool. You can modify 'localhost' to your computer's IP address to share the preview.

```text
http://localhost:63335/Writerside+Help+Sources/preview/preview-build-and-publish.html
```

--------------------------------

### Example Tree File Structure

Source: https://www.jetbrains.com/help/writerside/instances.html

This XML snippet defines a Writerside instance profile, including its ID, name, start page, table of contents elements, and included external elements.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE instance-profile SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">

<instance-profile id="aug" name="App User Guide"
                  start-page="introduction.topic">

    <toc-element topic="introduction.topic"/>

    <toc-element topic="settings.topic">
        <toc-element topic="settings_general.topic"/>
        <toc-element topic="settings_advanced.topic"/>
    </toc-element>

    <include from="lib.tree" element-id="reference"/>
</instance-profile>
```

--------------------------------

### Simple writerside.cfg Example

Source: https://www.jetbrains.com/help/writerside/writerside-cfg.html

Defines directories for topics and images, and two help instances. This is a basic configuration for a Writerside project.

```XML
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ihp SYSTEM "https://resources.jetbrains.com/writerside/1.0/ihp.dtd">
<ihp xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/writerside-cfg.xsd">
    <topics dir="topics"/>
    <images dir="images"/>
    <instance src="ug.tree"/>
    <instance src="ag.tree"/>
</ihp>
```

--------------------------------

### Example JSON Response for Document Creation (Success)

Source: https://www.jetbrains.com/help/writerside/generate-api-reference.html

This is an example of a JSON response indicating successful document creation. It typically includes a success message.

```json
{
  "message": "Document created"
}
```

--------------------------------

### Full Kotlin Test Sample

Source: https://www.jetbrains.com/help/writerside/code.html

Example of a full Kotlin test file content that can be referenced.

```kotlin
@Test
fun testSum() {
    val expected = 42
    assertEquals(expected, testSample.sum(40, 2))
}

@Test
fun testMultiply() {
    val expected = 42
    assertEquals(expected, testSample.multiply(21, 2))
}
```

--------------------------------

### Example XML Topic File

Source: https://www.jetbrains.com/help/writerside/topics.html

Illustrates the basic structure of an XML topic file in Writerside.

```xml
getting-started.topic
 {...}

```

--------------------------------

### Sample buildprofiles.xml Configuration

Source: https://www.jetbrains.com/help/writerside/buildprofiles-xml.html

A comprehensive example of a buildprofiles.xml file, demonstrating various configuration options for variables, shortcuts, footer, and build profiles.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE buildprofiles SYSTEM "https://resources.jetbrains.com/writerside/1.0/build-profiles.dtd">
<buildprofiles xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/build-profiles.xsd"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <variables>
        <web-root>https://www.jetbrains.com/help</web-root>
        <download-page>https://www.jetbrains.com/writerside/download/</download-page>
        <download-title>Get Writerside</download-title>
        <showDownloadButton>true</showDownloadButton>
        <primary-color>strawberry</primary-color>
        <header-logo>writerside.svg</header-logo>
        <custom-favicons>https://www.jetbrains.com/icon-512.png</custom-favicons>
    </variables>

    <shortcuts>
        <src>keymap.xml</src>
        <layout name="Windows" display-name="Windows"/>
        <layout name="macOS" display-name="macOS"/>
        <layout name="GNOME" display-name="Linux"/>
    </shortcuts>

    <footer>
        <social type="blog" href="https://blog.jetbrains.com/writerside/">Writerside Blog</social>
        <social type="twitter" href="https://twitter.com/onwriterside">Writerside on Twitter</social>

        <link href="https://youtrack.jetbrains.com/issues/WRS">Issue tracker</link>
        <link href="https://youtrack.jetbrains.com/form/9cf3cf67-8bc0-4cbc-824c-7ade4c563338">Submit support request</link>
        <link href="mailto:writerside@jetbrains.com">Contact us</link>

        <copyright>2000 JetBrains s.r.o.</copyright>
    </footer>

    <build-profile instance="wrs">
        <sitemap priority="0.35" change-frequency="monthly"/>
        <variables>
            <noindex-content>false</noindex-content>
            <product-web-url>https://www.jetbrains.com/help/writerside/</product-web-url>
            <og-twitter>@onwriterside</og-twitter>
            <og-image>https://resources.jetbrains.com/storage/products/writerside/img/meta/preview.png</og-image>
            <images-prefix-override>https://my.company.com/images/</images-prefix-override>
        </variables>
    </build-profile>
</buildprofiles>
```

--------------------------------

### Response Examples for Document Creation

Source: https://www.jetbrains.com/help/writerside/generate-a-single-api-endpoint-reference.html

These are example responses for a document creation API endpoint, illustrating a successful creation (201) and a bad request (400).

```json
{
  "message": "Document created"
}
```

```json
{
  "message": "Bad Request"
}
```

--------------------------------

### Serve Built Help Website Locally

Source: https://www.jetbrains.com/help/writerside/local-build.html

Use the http-server command to serve the unpacked help website archive from a local directory. Ensure http-server is installed first.

```bash
http-server ~/my-help
```

--------------------------------

### Basic JSON Data Diagram Example

Source: https://www.jetbrains.com/help/writerside/plantuml-diagrams.html

Illustrates the basic syntax for visualizing JSON data with PlantUML. The PlantUML documentation provides detailed examples for JSON diagrams.

```plantuml
@startjson
{...}

```
```

--------------------------------

### Run Sample Search Service JAR

Source: https://www.jetbrains.com/help/writerside/custom-search-service.html

Command to execute the provided JAR file, starting the custom search service without any pre-configured search indexes.

```shell
java -jar writerside-search-1.0.jar run
```

--------------------------------

### Example buildprofiles.xml Structure

Source: https://www.jetbrains.com/help/writerside/customize-the-look.html

This is a basic structure for the buildprofiles.xml file used to configure Writerside output. Create this file in your help module's cfg directory.

```xml
cfg/buildprofiles.xml
{...}

```

--------------------------------

### Example Search Service Configuration

Source: https://www.jetbrains.com/help/writerside/custom-search-service.html

Illustrates the `searchService` and `searchServiceUrl` keys found in the `config.json` file of built artifacts, showing how the custom endpoint is appended with preview-search details.

```json
searchService: "custom"
searchServiceUrl: "https://my.search/endpoint/preview-search/my-docs/hi"
```

--------------------------------

### Basic Class Diagram Example

Source: https://www.jetbrains.com/help/writerside/plantuml-diagrams.html

A minimal example demonstrating the structure for a PlantUML class diagram. For more complex examples, refer to the official PlantUML documentation.

```plantuml
@startuml
{...}

```
```

--------------------------------

### Install Grazie Pro Plugin

Source: https://www.jetbrains.com/help/writerside/ai-powered-writing.html

Install the Grazie Pro plugin to enable AI-powered writing features in Writerside. Access the IDE settings, navigate to Plugins, and search for Grazie Pro in the Marketplace.

```IDE Settings
Ctrl+Alt+0S to open the IDE settings and select Plugins.
Switch to the Marketplace tab, search for Grazie Pro, select the plugin, and click Install.
```

--------------------------------

### Example JSON Response for Document Creation (Bad Request)

Source: https://www.jetbrains.com/help/writerside/generate-api-reference.html

This is an example of a JSON response for a bad request when creating a document. It indicates an error in the request parameters.

```json
{
  "message": "Bad Request"
}
```

--------------------------------

### Example Markdown Topic File

Source: https://www.jetbrains.com/help/writerside/topics.html

Illustrates the basic structure of a Markdown topic file in Writerside.

```markdown
getting-started.md
 {...}

```

--------------------------------

### Environment File for Docker Builder

Source: https://www.jetbrains.com/help/writerside/build-with-docker.html

Example content for a builder.env file, defining environment variables for the Docker build process.

```env
SOURCE_DIR=/opt/sources
MODULE_INSTANCE=Writerside/hi
OUTPUT_DIR=/opt/sources/output
RUNNER=other
PDF=PDF.xml
```

--------------------------------

### State Diagram Example

Source: https://www.jetbrains.com/help/writerside/mermaid-diagrams.html

Illustrates system behavior changes based on inputs or user actions. Use for visualizing states and transitions.

```mermaid
stateDiagram-v2
    [*] --> Draft
    RR: Ready for review
    NU: Need updates
    AC: Apply changes
    LGTM: All good
    RP: Ready to publish
    Draft --> RR
    RR --> Review
    Review --> NU
    NU --> AC
    AC --> Review
    Review --> LGTM
    LGTM --> RP
    RP --> [*]
```

--------------------------------

### Basic Gantt Chart Example

Source: https://www.jetbrains.com/help/writerside/plantuml-diagrams.html

A simple example of a PlantUML Gantt chart. For advanced features and customization options, refer to the PlantUML Gantt diagram documentation.

```plantuml
@startgantt
{...}

```
```

--------------------------------

### Git Graph Example

Source: https://www.jetbrains.com/help/writerside/mermaid-diagrams.html

Visualizes a Git branching flow. Useful for explaining branching strategies to team members or external contributors.

```mermaid
gitGraph
    commit
    commit
    branch DOC-123-update-the-doc-A
    checkout DOC-123-update-the-doc-A
    commit id: "write the procedure"
    commit id: "update screenshots"
    checkout main
    merge DOC-123-update-the-doc-A
    commit
    commit
```

--------------------------------

### Included Line from Kotlin File

Source: https://www.jetbrains.com/help/writerside/code.html

Example of a single line included from a Kotlin file using include-lines.

```kotlin
val expected = 42
```

--------------------------------

### Example PDF Generation Options

Source: https://www.jetbrains.com/help/writerside/export-to-pdf.html

This XML file defines options for PDF generation, mirroring settings available in the Writerside PDF run configuration dialog. It should be placed in the 'cfg' directory.

```xml
cfg/pdf.xml
 {"pdf": {"coverPage": {"title": "My Documentation", "logo": "logo.png", "description": "A sample description.", "copyright": "Copyright (c) 2024"}, "header": {"text": "Confidential"}, "footer": {"text": "Page {pageNumber} of {totalPages}"}, "tocTitle": "Table of Contents", "orientation": "portrait", "saveTo": "./pdf", "keymap": "default"}}
```

--------------------------------

### Define Build Group Configuration

Source: https://www.jetbrains.com/help/writerside/build-groups.html

This XML snippet defines a build group named 'all-user-docs' that includes two documentation instances: 'User Guide' (ug) and 'Client Reference' (cr). Use this file to specify which instances should be built together.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE build-groups SYSTEM "https://resources.jetbrains.com/writerside/1.0/build-groups.dtd">
<build-groups
        xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/build-groups.xsd"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <build-group name="all-user-docs">
        <instance instance-id="ug" alias="User Guide" path="/userguide"/>
        <instance instance-id="cr" alias="Client Reference" path="/clientref"/>
    </build-group>

</build-groups>
```

--------------------------------

### Basic Mind Map Example

Source: https://www.jetbrains.com/help/writerside/plantuml-diagrams.html

Demonstrates the fundamental structure for creating a PlantUML mind map. The PlantUML website offers extensive examples for mind map diagrams.

```plantuml
@startmindmap
{...}

```
```

--------------------------------

### Footer with Copyright and Social Links

Source: https://www.jetbrains.com/help/writerside/customize-the-look.html

Example of a footer configuration including a copyright notice and two social media links.

```XML
<footer>
    <copyright>Product 2023</copyright>
    <social type="blog" href="https://blog.jetbrains.com/writerside/"/>
    <social type="twitter" href="https://twitter.com/onwriterside"/>
</footer>
```

--------------------------------

### Ordered and Unordered Lists with Nested Items

Source: https://www.jetbrains.com/help/writerside/lists.html

Demonstrates semantic markup for creating ordered and unordered lists with nested items. Use `type` attribute for list markers and `start` for the starting number of an ordered list.

```xml
<list type="decimal" start="2">
    <li>First item.
        <list type="alpha-lower">
            <li>First indented item.</li>
            <li>Second indented item.</li>
        </list>
    </li>
    <li>Second item.</li>
    <li>Third item.</li>
    <li>Fourth item.</li>
</list>

<list type="bullet">
    <li>Some list item</li>
    <li>Another list item</li>
    <li>Yet another list item
        <list type="bullet">
            <li>Indented item</li>
            <li>Indented item</li>
        </list>
    </li>
    <li>One more item</li>
</list>
```

--------------------------------

### Example Search Query URL

Source: https://www.jetbrains.com/help/writerside/custom-search-service.html

Demonstrates the structure of a search request URL sent to the custom search service, including path variables and query parameters.

```url
https://my.search/endpoint/preview-search/my-docs/hi?isExactSearch=false&maxHits=25&query=hello
```

--------------------------------

### Show All Elements

Source: https://www.jetbrains.com/help/writerside/structural-elements.html

Display all structural elements with titles at all levels. Use this to get a comprehensive overview of your project's structure.

```HTML
<show-structure/>
```

--------------------------------

### Sequence Diagram Example

Source: https://www.jetbrains.com/help/writerside/mermaid-diagrams.html

Illustrate a process flow and interactions between participants using a sequence diagram. This is helpful for understanding system processes and step-by-step logic.

```mermaid
sequenceDiagram
   Tech writer -->> Developer: Hi, can you check that I've described everything correctly?
   Developer -->> Junior developer: Hi, can you, please, help our TW with the task?
   Developer --x Tech writer: Sure, I've asked Garold to take care of this, it will help him to understand the logic better.
   Junior developer -->> Developer: No problem!

   Developer --> Tech writer: Adding you both to a group chat  ...
   Note right of Developer: Adding to the chat.

   Tech writer --> Junior developer: Hi, Garold!
```

--------------------------------

### Sample Search Service Console Output

Source: https://www.jetbrains.com/help/writerside/custom-search-service.html

Expected console output when the sample search service starts without an index, indicating the TFIDF engine is created and index paths are empty.

```text
Created controller with engine TFIDF
algoliaIndexPath = 
tfidfIndexPath = 
```

--------------------------------

### Configure Search Endpoint in buildprofiles.xml

Source: https://www.jetbrains.com/help/writerside/custom-search-service.html

Set the search endpoint in the buildprofiles.xml file to point to the custom search service. This example assumes the service is running on the same machine.

```xml
<search-endpoint>http://127.0.0.1/8080</search-endpoint>
```

--------------------------------

### Set Download Button Title

Source: https://www.jetbrains.com/help/writerside/buildprofiles-xml.html

Specifies the text for the download button in the header. Defaults to 'Get %instance%', where %instance% is the current product name.

```XML
<download-title>Download Now</download-title>
```

--------------------------------

### Apply Element to Specific Help Instances

Source: https://www.jetbrains.com/help/writerside/semantic-markup-reference.html

Control the visibility of an element based on help instances using the `instance` attribute. This example shows an element that applies to all instances except 'foo' and 'bar'.

```XML
<p instance="!foo,bar">This paragraph is for any help instance except "foo" and "bar".</p>
```

--------------------------------

### Defining Instance Groups in XML

Source: https://www.jetbrains.com/help/writerside/conditional-content.html

Example of an XML file structure for defining instance groups, which can be referenced later for conditional content.

```xml
instance-groups.xml
 {...}
```

--------------------------------

### Providing JavaScript Request Sample with <sample>

Source: https://www.jetbrains.com/help/writerside/semantic-markup-reference.html

The <sample> tag can be used within a <request> tag to provide custom request examples. The `lang` attribute specifies the language for highlighting, and `title` sets the tab name.

```XML
<request>
<sample lang="javascript" title="JavaScript">
const data = {
id: 123,
name: "John Doe",
email: "john.doe@example.com"
};
</sample>
</request>
```

--------------------------------

### Configure Keymap File in buildprofiles.xml

Source: https://www.jetbrains.com/help/writerside/shortcuts.html

Configure the keymap file and desired layouts in buildprofiles.xml to enable the shortcut switcher in the rendered help.

```XML
<shortcuts>
    <src>keymap.xml</src>
    <layout name="Windows" display-name="Windows"/>
    <layout name="macOS" display-name="macOS"/>
</shortcuts>
```

--------------------------------

### Starting Page Topic Markup

Source: https://www.jetbrains.com/help/writerside/section-starting-page.html

This is the basic structure for a starting page topic in Writerside. It uses the <section-starting-page> element to define the content.

```XML
<section-starting-page>
 {...}
</section-starting-page>
```

--------------------------------

### Nullable Link Example

Source: https://www.jetbrains.com/help/writerside/links-and-references.html

Make a link nullable to prevent build failures if the target topic doesn't exist in a specific instance. Writerside will render only the link text in such cases.

```html
<a href="some.topic" nullable="true">link text</a>
```

```markdown
[link text](some.topic){nullable="true"}
```

--------------------------------

### Example TLDR Block Markup

Source: https://www.jetbrains.com/help/writerside/tl-dr-blocks.html

This markup demonstrates how to create a TLDR block in Writerside, with each fact wrapped in a <p> tag. Use this to provide quick facts like shortcuts or configuration paths.

```html
<tldr>
    <p>Shortcut: <shortcut>Ctrl+Space</shortcut></p>
    <p>Configure: <ui-path>Settings / Preferences | Editor | Code Completion</ui-path></p>
</tldr>
```

--------------------------------

### Substitution Rule Example

Source: https://www.jetbrains.com/help/writerside/style-guides.html

Use the 'substitution' block to suggest replacements for specific tokens. This example suggests replacing 'text box' with 'field'.

```yaml
extends: substitution
message: Consider using '%s' instead of '%s'
ignorecase: true
level: suggestion
swap:
    text box: field
```

--------------------------------

### Configure a Help Instance

Source: https://www.jetbrains.com/help/writerside/writerside-cfg.html

Specify the settings for a help instance, including its source tree, web path, and version.

```XML
<instance src="pd.tree" web-path="/plugin-developers/" version="main"/>
```

--------------------------------

### Conditional Rule Example

Source: https://www.jetbrains.com/help/writerside/style-guides.html

Use the 'conditional' block to enforce that the presence of one token implies the existence of another. This example requires 'bar' to be present if 'foo' is used.

```yaml
extends: conditional
message: "'%s' has no period"
ignorecase: true
first: foo
second: bar
```

--------------------------------

### Existence Rule Example

Source: https://www.jetbrains.com/help/writerside/style-guides.html

Use the 'existence' block to find and flag tokens you want to avoid, such as wordy phrases. This example targets 'a number of' and 'as a matter of fact'.

```yaml
extends: existence
message: Don't use '%s'
ignorecase: true
tokens:
    - a number of
    - as a matter of fact
```

--------------------------------

### Kotlin Hello World

Source: https://www.jetbrains.com/help/writerside/markup-reference.html

A basic 'Hello, World!' program in Kotlin. This demonstrates the concise syntax for a main function.

```kotlin
fun main() {
    println("Hello, World!")
}
```

--------------------------------

### Occurrence Rule Example

Source: https://www.jetbrains.com/help/writerside/style-guides.html

Use the 'occurrence' block to limit the number of times a token appears in a specific scope, like a sentence. This example limits commas in a sentence to a maximum of 3.

```yaml
extends: occurrence
message: "This sentence has more than 3 commas. Consider rephrasing it."
scope: sentence
ignorecase: false
max: 3
token: ','
```

--------------------------------

### Example JSON Request Body for Document Creation

Source: https://www.jetbrains.com/help/writerside/generate-api-reference.html

This is an example of a JSON request body for creating a document, as might be used in an API call. It includes fields for the document's title and content.

```json
{
  "title": "Example Document",
  "content": "This is some example content for the document."
}
```

--------------------------------

### Configure Version Switcher

Source: https://www.jetbrains.com/help/writerside/buildprofiles-xml.html

Specify the link to the `help-versions.json` file used by the help website to render the version switcher component.

```XML
<versions-switcher>https://my.documentation.com/help-versions.json</versions-switcher>
```

--------------------------------

### Sample .gitlab-ci.yml for GitLab Pages Deployment

Source: https://www.jetbrains.com/help/writerside/deploy-docs-to-gitlab-pages.html

This CI/CD pipeline configuration triggers on pushes to the `main` branch. It builds, tests, and publishes documentation from a starter project to GitLab Pages.

```yaml
.gitlab-ci.yml
 {...}
```

--------------------------------

### Define Product Versions in JSON

Source: https://www.jetbrains.com/help/writerside/support-multiple-versions.html

Create a JSON file that lists available product versions, their relative URLs, and indicates the current version. This file is used by the version switcher.

```json
[
    {"version":"1.0","url":"/help/1.0/","isCurrent":false},
    {"version":"2.0","url":"/help/2.0/","isCurrent":true}
]
```

--------------------------------

### Code Block After Refactoring

Source: https://www.jetbrains.com/help/writerside/code.html

Example of a code block representing the 'after' state in a comparison.

```kotlin
if (true) doThis()
```

--------------------------------

### Dockerfile for Building and Serving Documentation Website

Source: https://www.jetbrains.com/help/writerside/build-with-docker.html

A Dockerfile that uses the Writerside builder to create a documentation website and then serves it using an Apache HTTP server. It includes build arguments for customization.

```dockerfile
FROM jetbrains/writerside-builder:2026.04.8711 as build

ARG INSTANCE=Writerside/hi

RUN mkdir /opt/sources

WORKDIR /opt/sources

ADD Writerside ./Writerside

RUN export DISPLAY=:99 && \
Xvfb :99 & \
/opt/builder/bin/idea.sh helpbuilderinspect --source-dir /opt/sources --product $INSTANCE --runner other --output-dir /opt/wrs-output/

WORKDIR /opt/wrs-output

RUN unzip -O UTF-8 webHelpHI2-all.zip -d /opt/wrs-output/unzipped-artifact

FROM httpd:2.4 as http-server

COPY --from=build /opt/wrs-output/unzipped-artifact/ /usr/local/apache2/htdocs/
```

--------------------------------

### Configure Footer with Copyright, Social, and Links

Source: https://www.jetbrains.com/help/writerside/customize-the-look.html

Use this configuration in `buildprofiles.xml` to set up a custom footer with copyright, social media links, and general links.

```XML
<footer>
    <copyright>2000 JetBrains s.r.o.</copyright>
    <social type="twitter" href="https://twitter.com/onwriterside"/>
    <link href="https://blog.jetbrains.com">Blog</link>
</footer>
```

--------------------------------

### Code Block Before Refactoring

Source: https://www.jetbrains.com/help/writerside/code.html

Example of a code block representing the 'before' state in a comparison.

```kotlin
if (true) {
    doThis()
}
```

--------------------------------

### Included Kotlin Function

Source: https://www.jetbrains.com/help/writerside/code.html

Example of a function included from a Kotlin file using include-symbol.

```kotlin
@Test
fun testMultiply() {
    val expected = 42
    assertEquals(expected, testSample.multiply(21, 2))
}
```

--------------------------------

### Define Product-Specific Variables

Source: https://www.jetbrains.com/help/writerside/semantic-markup-reference.html

Use the 'instance' attribute to define variables that apply to specific product help instances. This allows for conditional content rendering.

```XML
<var name="product" value="Foo Sprinkler" instance="foo"/>
<var name="product" value="Bar Annotator" instance="bar"/>
```

--------------------------------

### Run Docker Container with Direct Command Options

Source: https://www.jetbrains.com/help/writerside/build-with-docker.html

Execute the helpbuilderinspect command directly within a Docker container, providing all options as arguments. Ensure DISPLAY and Xvfb are set up within the same RUN directive.

```bash
docker run --rm -v .:/opt/sources \
jetbrains/writerside-builder:2026.04.8711 \
/bin/bash -c "
export DISPLAY=:99 &&
Xvfb :99 &
/opt/builder/bin/idea.sh helpbuilderinspect \
--source-dir /opt/sources \
--product Writerside/hi \
--output-dir /opt/sources/output \
--runner other \
-pdf PDF.xml \
"
```

--------------------------------

### Build Documentation Workflow

Source: https://www.jetbrains.com/help/writerside/deploy-docs-to-github-pages.html

This workflow triggers on every push to the main branch to build the documentation website. It checks out the repository, generates the website using the Writerside GitHub Action, and uploads the generated archive as a 'docs' artifact.

```yaml
name: Build documentation

on:
  push:
    branches: [ main ]

env:
  INSTANCE: "Writerside/hi"
  DOCKER_VERSION: "2026.04.8711"

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Generate documentation website
        uses: JetBrains/writerside-github-action@v4
        with:
          instance: ${{ env.INSTANCE }}
          docker_version: ${{ env.DOCKER_VERSION }}
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: docs
          path: "artifacts/*"
```

--------------------------------

### Define Glossary Terms

Source: https://www.jetbrains.com/help/writerside/tooltips.html

Create a `glossary.xml` file to define terms and their descriptions. This file should be placed in the `cfg` directory.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE terms SYSTEM "https://resources.jetbrains.com/writerside/1.0/glossary.dtd">
<terms>
    <term name="GUI">Graphical User Interface</term>
    <term name="HTTP">Hypertext Transfer Protocol</term>
</terms>
```

--------------------------------

### Code Block with Collapsed Title

Source: https://www.jetbrains.com/help/writerside/semantic-markup-reference.html

Example of setting custom text for a collapsed code block using the `collapsed-title` attribute.

```xml
<code-block lang="python" collapsed-title="Collapsed Python Example">
print('This is a collapsed code block.')
</code-block>
```

--------------------------------

### Multiline Code Block Formatting

Source: https://www.jetbrains.com/help/writerside/writerside-code-of-conduct.html

Use triple backticks to format multiline code blocks. This is useful for longer code examples.

```text
```
multiline
code blocks
```
```

--------------------------------

### Set Rule Severity to Error

Source: https://www.jetbrains.com/help/writerside/style-guides.html

Use the 'level' argument to set a rule's severity. This example marks contractions as an error.

```yaml
extends: substitution
message: "Use '%s' instead of '%s'."
level: error
ignorecase: true
swap:
    aren't: are not
```

--------------------------------

### Java Hello World

Source: https://www.jetbrains.com/help/writerside/markup-reference.html

A basic 'Hello, World!' program in Java. This is a standard entry point for Java applications.

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

--------------------------------

### Algolia Search Environment Variables

Source: https://www.jetbrains.com/help/writerside/deploy-docs-to-github-pages.html

Example environment variables for configuring Algolia search integration within the GitHub Actions workflow.

```yaml
ALGOLIA_APP_NAME: 'NLAGB2LZHU'
ALGOLIA_INDEX_NAME: 'MY_INDEX'
CONFIG_JSON_PRODUCT: 'HI'
CONFIG_JSON_VERSION: '1.0'
```

--------------------------------

### Run Docker Builder Container with Environment File

Source: https://www.jetbrains.com/help/writerside/build-with-docker.html

Run the Writerside Docker container using an environment file to define build variables. Mounts the current directory as sources.

```bash
docker run --rm -v .:/opt/sources --env-file=builder.env \
jetbrains/writerside-builder:2026.04.8711
```

--------------------------------

### Link to a Topic

Source: https://www.jetbrains.com/help/writerside/semantic-markup-reference.html

Use the `<a>` element to create hyperlinks. This example shows linking to another topic and rendering the topic title as the link text.

```XML
<a href="my-topic.topic"/>
```

--------------------------------

### Footer with All Possible Elements

Source: https://www.jetbrains.com/help/writerside/customize-the-look.html

Demonstrates a comprehensive footer configuration including copyright, ICP, multiple social links, and various general links.

```XML
<footer>
    <copyright>Product 2000-2023</copyright>
    <icp>123456789</icp>
    <social type="blog" href="https://blog.jetbrains.com/writerside/"/>
    <social type="twitter" href="https://twitter.com/onwriterside"/>
    <social type="facebook" href="https://www.facebook.com/JetBrains"/>
    <link href="https://slack.example.com">Slack community</link>
    <link href="https://stackoverflow.com">StackOverflow</link>
    <link href="https://example.com/terms-an-conditions.html">Terms and conditions</link>
    <link href="https://example.com/code-of-conduct.html">Code of Conduct</link>
</footer>
```

--------------------------------

### Build Docker Image

Source: https://www.jetbrains.com/help/writerside/build-with-docker.html

Command to build a Docker image from a Dockerfile. This image will contain the necessary tools and configurations to build the documentation website.

```bash
docker build -t help-website .
```

--------------------------------

### Create a Primary Link Group

Source: https://www.jetbrains.com/help/writerside/semantic-markup-reference.html

Organize important topic links using the <primary> element, typically found on section starting pages.

```XML
<primary>
<title>Quick start</title>
<a href="Hello_World.topic" summary="Write your first Hello World program.">Hello, World!</a>
<a href="Barrel_Roll.topic" summary="Learn how to do a barrel roll properly.">Do a barrel
roll</a>
...
</primary>
```

--------------------------------

### GET /users/{id}

Source: https://www.jetbrains.com/help/writerside/generate-a-single-api-endpoint-reference.html

Retrieves user information by ID. Supports custom response samples for success (200) and error (400) scenarios.

```APIDOC
## GET /users/{id}

### Description
Retrieves user information by ID. This endpoint allows for custom response samples to be defined for different HTTP status codes, such as success or error responses.

### Method
GET

### Endpoint
/users/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the user.

### Response
#### Success Response (200)
- **id** (integer) - The user's ID.
- **name** (string) - The user's name.
- **email** (string) - The user's email address.

#### Response Example (200)
```json
{
    "id": 123,
    "name": "John Doe",
    "email": "john.doe@example.com"
}
```

#### Error Response (400)
- **error** (string) - A message describing the error.

#### Response Example (400)
```json
{
    "error": "text"
}
```
```

--------------------------------

### Specify Artifact Path

Source: https://www.jetbrains.com/help/writerside/build-on-teamcity.html

Define the artifact path for the build configuration to output a ZIP archive of the help content.

```text
helproot => webhelp.zip
```

--------------------------------

### Configure External Redirects in TOC Element

Source: https://www.jetbrains.com/help/writerside/8644.html

Example of a TOC element configured for external redirects, requiring specific attributes like 'hidden' and 'accepts-web-file-names'.

```xml
<toc-element hidden="true"
  accepts-web-file-names="some-removed-topic.html"
  target-for-accept-web-file-names="https://www.company.com/blog/post"/>
```

--------------------------------

### Embed D2 Diagram in Writerside

Source: https://www.jetbrains.com/help/writerside/d2-diagrams.html

Use a code block with the language set to 'd2' to embed D2 diagrams directly. Ensure D2 is installed.

```d2
direction: right
question: Do you write docs?
yes: Use Writerside
no: You should
question -> yes: Yes
question -> no: No
```

--------------------------------

### Configure Snippets Directory

Source: https://www.jetbrains.com/help/writerside/code.html

Specify the directory containing code samples in the writerside.cfg file.

```xml
<snippets src="codeSnippets"/>
```

--------------------------------

### YAML Front Matter for Topic Title

Source: https://www.jetbrains.com/help/writerside/inspectopedia.html

This example shows how to define a topic title using YAML front matter. This is an alternative to using an H1 header.

```YAML
---
title: Topic title
---
```

--------------------------------

### Linking to a Topic File

Source: https://www.jetbrains.com/help/writerside/topics.html

Demonstrates creating a hyperlink to an XML topic file.

```html
<a href="getting-started.topic"/>
```

--------------------------------

### Existence Rule for Headings

Source: https://www.jetbrains.com/help/writerside/style-guides.html

This example applies an 'existence' rule specifically to headings to avoid end punctuation. It targets words followed by '.', '?', or '!' within heading scopes.

```yaml
extends: existence
message: "Don't use end punctuation in headings."
nonword: true
scope: heading
tokens:
    - '[a-z0-9][.?!](?:\s|$)'
```

--------------------------------

### Define Instance Version in writerside.cfg

Source: https://www.jetbrains.com/help/writerside/support-multiple-versions.html

Set the version attribute for an instance in `writerside.cfg` to display the version in the help header. Remove or omit this attribute to hide the version.

```xml
<instance src="hi.tree" version="1.0"/>
```

--------------------------------

### Run Docker Builder Container with Environment Variables

Source: https://www.jetbrains.com/help/writerside/build-with-docker.html

Run the Writerside Docker container, mounting the current directory as sources and specifying build environment variables.

```bash
docker run --rm -v .:/opt/sources \
-e SOURCE_DIR=/opt/sources \
-e MODULE_INSTANCE=Writerside/hi \
-e OUTPUT_DIR=/opt/sources/output \
-e RUNNER=other \
-e PDF=PDF.xml \
jetbrains/writerside-builder:2026.04.8711
```

--------------------------------

### GitHub Actions Workflow for Deployment

Source: https://www.jetbrains.com/help/writerside/deploy-docs-to-github-pages.html

This workflow configures build, test, and deploy jobs. It downloads artifacts, unzips archives, enables GitHub Pages, and deploys the documentation.

```yaml
build-docs.yml
 {...}
```

--------------------------------

### Image Directory Settings

Source: https://www.jetbrains.com/help/writerside/writerside-cfg.html

Specifies the directory 'images/' for media files and sets a version for image sets. The 'web-path' attribute defines where images will be located after the help instance is built.

```XML
<images dir="images/"/>
```

--------------------------------

### Pull Writerside Builder Docker Image

Source: https://www.jetbrains.com/help/writerside/22562.html

Use this command to pull the Writerside builder Docker image from Docker Hub. Ensure you have Docker installed and configured.

```bash
docker pull jetbrains/writerside-builder:243.22562
```

--------------------------------

### Configure Web Path for Images

Source: https://www.jetbrains.com/help/writerside/deploy-docs-to-github-pages.html

Set the `web-path` parameter in the `<images>` element of `writerside.cfg` to your GitHub repository name for correct image deployment.

```xml
<ihp version="2.0">
    <topics dir="topics"/>
    <images dir="images" web-path="my-docs-repo"/>
    <instance src="hi.tree"/>
</ihp>
```

--------------------------------

### <response> Tag

Source: https://www.jetbrains.com/help/writerside/semantic-markup-reference.html

The <response> tag specifies response information for an API endpoint. It requires a `type` attribute for the response code and can include a `<sample>` tag for data examples.

```APIDOC
## <response>
Specify response information for an API endpoint. This tag must define a required attribute `type` to specify the response code (e.g., default, 1XX, 2XX, 4XX, 5XX).
You can include a `<sample>` tag to provide sample response data.

### Example
```xml
<api-endpoint endpoint="/users/{id}" method="GET">
<response type="200">
<sample>
{
"id": 123,
"name": "John Doe",
"email": "john.doe@example.com"
}
</sample>
</response>
<response type="400">
<sample>
{
"error": "text"
}
</sample>
</response>
</api-endpoint>
```

### Parent elements
<api-endpoint> <api-webhook>

### Child elements
<sample>

### Attributes
- **type**: Specify the response code.
```

--------------------------------

### Create a Spotlight with Featured Links

Source: https://www.jetbrains.com/help/writerside/semantic-markup-reference.html

Add a group of two cards with links to featured topics using the `<spotlight>` element. The `summary` attribute can provide a custom summary.

```xml
<spotlight>
<a href="Try_This.topic" summary="If you haven't already, you should try it.">Try this</a>
<a href="Important_Stuff.topic" summary="Learn what is most important when you begin.">Important
stuff</a>
</spotlight>
```

--------------------------------

### Resolving PlantUML Variables (Default Behavior)

Source: https://www.jetbrains.com/help/writerside/plantuml-diagrams.html

By default, Writerside ignores variables in PlantUML code, rendering them literally. This example shows the default behavior where %v1% and %v2% are not substituted.

```plantuml
<var name="v1" value="1.0"/>
<var name="v2" value="2.0"/>

<code-block lang="plantuml">
    @startuml
    [Component] --> "Interface %v1%"
    [Component] --> "Interface %v2%"
    @enduml
</code-block>
```

--------------------------------

### Run Search Service with Algolia Indexes

Source: https://www.jetbrains.com/help/writerside/custom-search-service.html

Run the search service JAR file, specifying the path to the directory containing Algolia indexes.

```bash
java -jar writerside-search-1.0.jar run --algolia-indexes=/path/to/algolia-indexes-HI/
```

--------------------------------

### Define Custom Card Summary

Source: https://www.jetbrains.com/help/writerside/semantic-markup-reference.html

Use the <card-summary> tag to provide a custom summary for a topic, which will be displayed on section starting pages. This text is only used in cards and not within the topic itself.

```xml
<topic title="Foo" id="foo">
<card-summary>
This topic is about Foo.
This text will not render in the topic.
It is used only in cards on a section starting page.
</card-summary>

...
</topic>
```

--------------------------------

### <sample> Tag

Source: https://www.jetbrains.com/help/writerside/semantic-markup-reference.html

The <sample> tag defines a custom request or response example for an API endpoint. It can include attributes for language highlighting, source file referencing, and line number inclusion.

```APIDOC
## <sample>
Define a custom request or response example to help developers understand the expected input and output of an API endpoint.
Use the `<sample>` tag inside a `<request>` or a `<response>` tag.

### Example (Request)
```xml
<request>
<sample lang="javascript" title="JavaScript">
const data = {
id: 123,
name: "John Doe",
email: "john.doe@example.com"
};
</sample>
</request>
```

### Example (Response with src)
```xml
<response>
<sample src="example.js" include-lines="5-10"/>
</response>
```

### Parent elements
<request> <response>

### Attributes
- **filter**: Specify a custom filter for an element.
- **id**: Specify an identifier for an element.
- **include-lines**: Specify line numbers from the source file to include in the sample.
- **instance**: Specify the conditions for an element.
- **lang**: Specify the language for highlighting in this sample.
- **src**: Specify the source file with code that you want to include as a sample.
- **title**: Name of the tab with the sample.
```

--------------------------------

### Referencing Sample from File with <sample>

Source: https://www.jetbrains.com/help/writerside/semantic-markup-reference.html

Samples can be stored in separate files using the `src` attribute. The `include-lines` attribute can reference specific lines from the source file.

```XML
<response>
<sample src="example.js" include-lines="5-10"/>
</response>
```

--------------------------------

### Formatting Text with Color and Style

Source: https://www.jetbrains.com/help/writerside/paragraphs.html

Demonstrates using the <format> element to apply specific styling, such as bold and a custom color, to text.

```html
<format style="bold" color="#654321">Hello, world!</format>
```

--------------------------------

### Defining API Responses with <response>

Source: https://www.jetbrains.com/help/writerside/semantic-markup-reference.html

The <response> tag specifies response information for an API endpoint and requires a `type` attribute for the response code. It can include a <sample> tag for example data.

```XML
<api-endpoint endpoint="/users/{id}" method="GET">
<response type="200">
<sample>
{
"id": 123,
"name": "John Doe",
"email": "john.doe@example.com"
}
</sample>
</response>
<response type="400">
<sample>
{
"error": "text"
}
</sample>
</response>
</api-endpoint>
```

--------------------------------

### Markdown Topic with H1 Header for Title

Source: https://www.jetbrains.com/help/writerside/inspectopedia.html

This example shows a Markdown topic where the first H1 header serves as the topic title. This is the standard way to define a topic title in Markdown.

```Markdown
# Topic title
```

--------------------------------

### Run Docker Container from Custom Image

Source: https://www.jetbrains.com/help/writerside/build-with-docker.html

Command to run a Docker container from a custom-built image. This container will serve the built documentation website on the specified host port.

```bash
docker run -dit -p 8080:80 help-website
```
Tokens:
Raw