Build and publish on GitLab
If your documentation sources are hosted on GitLab, you can use GitLab CI/CD to build your documentation website and deploy it to GitLab Pages.
Enable GitLab Pages for the project. Open your project on GitLab, select Visibility, project features, permissions section, and enable Pages.
, expand theIn the writerside.cfg file, set the
web-path
parameter forimages
toimg
.<ihp version="2.0"> <topics dir="topics"/> <images dir="images" web-path="img"/> <instance src="hi.tree"/> </ihp>In the project root, create a file named .gitlab-ci.yml, where you will define your CI/CD pipeline.
The following sample pipeline will trigger on every push to the
main
branch in the repository. the pipeline builds, tests, and publishes documentation from the starter project, where the default module name isWriterside
and the default instance ID ishi
:variables: INSTANCE: 'Writerside/hi' ARTIFACT: 'webHelpHI2-all.zip' DOCKER_VERSION: '243.21565' 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 "Testing existence of $ARTIFACT..." - test -e public/$ARTIFACT artifacts: paths: - public/$ARTIFACT - public/report.json expire_in: 1 week 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 needs: [build, test] image: ubuntu:latest before_script: - apt-get update -y && apt-get install unzip -y script: - cd public - unzip -O UTF-8 $ARTIFACT - ls -l artifacts: paths: - public expire_in: 1 weekIf necessary, set the correct values for environment variables:
- INSTANCE
The name of the module and instance ID separated by a slash. The module name is the directory with writerside.cfg. It is designated by the icon in the Project tool window.
For example, the default module name in a starter project is
Writerside
and the instance ID ishi
. So in this case, set the variable toWriterside/hi
.- ARTIFACT
The name of the archive produced by the Writerside builder is webHelpXX2-all.zip, where XX is the ID of the instance in capital letters.
For example, if the instance name is Help Instance and its ID is
hi
, then set this variable towebHelpHI2-all.zip
.- DOCKER_VERSION
The version of the Writerside Docker builder to use for generating the documentation artifacts. The current latest version is 243.21565.
When you update to a newer version of Writerside, set the new Docker builder version to ensure results similar to what you see in the local preview and local builds.
Commit the .gitlab-ci.yml and push it to GitLab.
Upload search indexes
If you also configure Algolia search, you can modify the CI/CD pipeline further and add the publish-indexes
stage that will automatically update the search indexes after a successful deployment.
You will also need to add Algolia indexes to the public
artifacts' folder that the build
stage produces, and specify the following additional environment variables:
- ALGOLIA_ARTIFACT
The name of the ZIP archive with Algolia indexes from the build
- ALGOLIA_APP_NAME
Algolia application ID
- ALGOLIA_INDEX_NAME
Name of Algolia index
- ALGOLIA_KEY
Algolia Admin API Key.
This is a private key. Store it as a CI/CD variable and reference via
$ALGOLIA_KEY
.- CONFIG_JSON_PRODUCT
Help instance ID from the tree file or the value of the
web-path
attribute specified in writerside.cfg if it is different from the ID- CONFIG_JSON_VERSION
Help instance version (usually the same as the branch name) specified in writerside.cfg
Here is how it all looks in a single workflow file:
Build to PDF
You can configure a separate pipeline or stage in an existing pipeline to produce a PDF artifact. Here is an example of a separate pipeline with a build_pdf
stage that produces a PDF: