Writerside Help

Build and publish on GitLab

This article describes how to use GitLab CI to build a help instance and deploy it to GitLab Pages.

  1. Make sure the GitLab Pages feature is enabled for the project. To enable it, in your GitLab project, go to Settings | General, expand the Visibility, project features, permissions section, and turn on the Pages toggle.

  2. In the writerside.cfg file set the web-path parameter for images to img.

    <ihp version="2.0"> <topics dir="topics"/> <images dir="images" web-path="img"/> <instance src="hi.tree"/> </ihp>
  3. Create the file .gitlab-ci.yml file in your project with the following workflow configuration:

    variables: # Name of module and id separated by a slash INSTANCE: 'Writerside/hi' # Replace HI with the ID of the instance in capital letters ARTIFACT: 'webHelpHI2-all.zip' # Writerside Docker image version DOCKER_VERSION: '232.10275' stages: - build - test - deploy build: stage: build image: registry.jetbrains.team/p/writerside/builder/writerside-builder:$DOCKER_VERSION script: - set -e - export DISPLAY=:99 - Xvfb :99 & - /opt/builder/bin/idea.sh helpbuilderinspect -source-dir . -product $INSTANCE --runner gitlab -output-dir public/ || true - echo "Test existing of $ARTIFACT artifact" - test -e public/$ARTIFACT artifacts: paths: # The folder that contains the built HTML files to be published and a test report - public/$ARTIFACT - public/report.json expire_in: 1 week # Add the job below if you want to fail the build when documentation contains errors. test: stage: test image: openjdk:18-jdk-alpine before_script: - apk add curl script: - cd public - curl -o wrs-checker.jar -L https://packages.jetbrains.team/maven/p/writerside/maven/com/jetbrains/writerside/writerside-ci-checker/1.0/writerside-ci-checker-1.0.jar - java -jar wrs-checker.jar report.json $INSTANCE pages: stage: deploy image: ubuntu:20.04 before_script: - apt-get update -y && apt-get install unzip -y script: - cd \public - unzip -O UTF-8 $ARTIFACT artifacts: paths: - public expire_in: 1 week
  4. Set the correct values for the following environment variables:


    The name of the help module and help instance ID separated by a slash.

    When you create a new Writerside project or a help instance in an existing project, the default help module name is Writerside and the default instance ID is hi. So, in this case, set INSTANCE: Writerside/hi.

    To locate the help module name, check the folder name with the following icon module icon in the Project tool window.


    The name of the produced archive is webHelpXX2-all.zip, where XX is the ID of the help instance in capital letters.

    For example, if the help instance is Foo Help, and its ID is fh, then set ARTIFACT: webHelpFH2-all.zip.


    Change the DOCKER_VERSION in the configuration above to the one corresponding to the plugin version you're using.

  5. Commit the .gitlab-ci.yml and push it to GitLab.

Last modified: 08 December 2023