Writerside Help

Build and publish on GitHub

If your documentation sources are hosted on GitHub, you can use GitHub Actions to build your documentation website and deploy it to GitHub Pages.

For more information about hosting your documentation sources on GitHub, see Git integration.

Build documentation website

  1. In the root of your project, create the .github/workflows/ directory to store workflow files.

  2. In the .github/workflows/ directory, create a new YAML file named build-docs.yml.

    The following sample workflow will trigger on every push to the main branch in the repository and build the starter project, where the default module name is Writerside and the default instance ID is hi:

    name: Build documentation on: push: branches: ["main"] workflow_dispatch: env: INSTANCE: 'Writerside/hi' ARTIFACT: 'webHelpHI2-all.zip' DOCKER_VERSION: '233.14938' jobs: build: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v4 - name: Build docs using Writerside Docker builder uses: JetBrains/writerside-github-action@v4 with: instance: ${{ env.INSTANCE }} artifact: ${{ env.ARTIFACT }} docker-version: ${{ env.DOCKER_VERSION }} - name: Save artifact with build results uses: actions/upload-artifact@v4 with: name: docs path: | artifacts/${{ env.ARTIFACT }} retention-days: 7
  3. If necessary, set the correct values for environment variables:

    env.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 module icon in the Project tool window.

    For example, the default module name in a starter project is Writerside and the instance ID is hi. So in this case, set the variable to Writerside/hi.

    env.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 to webHelpHI2-all.zip.

    env.DOCKER_VERSION

    The version of the Writerside Docker builder to use for generating the documentation artifacts. The current latest version is 233.14938.

    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.

After you commit and push build-docs.yml, the Build documentation workflow will automatically trigger and run the build job. Go to the project repository on GitHub and open the Actions tab to see the workflow and the produced artifacts.

The build job runs on the latest Ubuntu virtual machine and consists of three steps:

Build and test produced artifacts

The Writerside builder produces a report with all problems that occurred during the build. You can view this report manually or configure a separate job that automatically checks the report and fails the workflow if it contains errors.

  1. Add report.json to the artifact that the build job produces and saves.

  2. Add the test job to the workflow.

Here is what the workflow from the previous example will look like:

name: Build documentation on: push: branches: ["main"] workflow_dispatch: env: INSTANCE: 'Writerside/hi' ARTIFACT: 'webHelpHI2-all.zip' DOCKER_VERSION: '233.14938' jobs: build: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v4 - name: Build docs using Writerside Docker builder uses: JetBrains/writerside-github-action@v4 with: instance: ${{ env.INSTANCE }} artifact: ${{ env.ARTIFACT }} docker-version: ${{ env.DOCKER_VERSION }} - name: Save artifact with build results uses: actions/upload-artifact@v4 with: name: docs path: | artifacts/${{ env.ARTIFACT }} artifacts/report.json retention-days: 7 test: needs: build runs-on: ubuntu-latest steps: - name: Download artifacts uses: actions/download-artifact@v4 with: name: docs path: artifacts - name: Test documentation uses: JetBrains/writerside-checker-action@v1 with: instance: ${{ env.INSTANCE }}

After you commit and push this workflow, the test job will run only if the build job finished successfully, and it consists of the following steps:

Build, test, and publish to GitHub Pages

You can publish the produced artifacts manually or in a separate workflow. However, if you want continuous delivery automation, configure a job in the same workflow that will deploy every successfully built and tested artifact to GitHub Pages.

  1. Enable publishing to GitHub Pages with a custom GitHub Actions workflow.

    Open the repository on GitHub, click Settings, then click Pages under Code and automation, and then select GitHub Actions as the Source under Build and deployment.

  2. In the writerside.cfg file, set the web-path parameter for images to the GitHub repository name.

    <ihp version="2.0"> <topics dir="topics"/> <images dir="images" web-path="my-docs-repo"/> <instance src="hi.tree"/> </ihp>
  3. Assign write permissions for the id-token and pages scopes in your workflow.

  4. Add the deploy job to the workflow.

Here is what the workflow from the previous example will look like:

name: Build documentation on: push: branches: ["main"] workflow_dispatch: permissions: id-token: write pages: write env: INSTANCE: 'Writerside/hi' ARTIFACT: 'webHelpHI2-all.zip' DOCKER_VERSION: '233.14938' jobs: build: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v4 - name: Build docs using Writerside Docker builder uses: JetBrains/writerside-github-action@v4 with: instance: ${{ env.INSTANCE }} artifact: ${{ env.ARTIFACT }} docker-version: ${{ env.DOCKER_VERSION }} - name: Save artifact with build results uses: actions/upload-artifact@v4 with: name: docs path: | artifacts/${{ env.ARTIFACT }} artifacts/report.json retention-days: 7 test: needs: build runs-on: ubuntu-latest steps: - name: Download artifacts uses: actions/download-artifact@v4 with: name: docs path: artifacts - name: Test documentation uses: JetBrains/writerside-checker-action@v1 with: instance: ${{ env.INSTANCE }} deploy: environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} needs: [build, test] runs-on: ubuntu-latest steps: - name: Download artifacts uses: actions/download-artifact@v4 with: name: docs - name: Unzip artifact run: unzip -O UTF-8 -qq '${{ env.ARTIFACT }}' -d dir - name: Setup Pages uses: actions/configure-pages@v4 - name: Package and upload Pages artifact uses: actions/upload-pages-artifact@v3 with: path: dir - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4

After you commit and push this workflow, the deploy job will run only if both build and test finish successfully, and it consists of the following steps:

If the workflow is successful, the deploy job will output the URL to the published documentation.

If you also configure Algolia search, the complete workflow that automatically updates the search indexes after a successful deployment will look like this:

name: Build documentation on: push: branches: ["main"] workflow_dispatch: permissions: id-token: write pages: write env: INSTANCE: 'Writerside/hi' ARTIFACT: 'webHelpHI2-all.zip' DOCKER_VERSION: '233.14938' ALGOLIA_ARTIFACT: 'algolia-indexes-HI.zip' ALGOLIA_APP_NAME: 'NLAGB2LZHU' ALGOLIA_INDEX_NAME: 'MY_INDEX' ALGOLIA_KEY: '${{ secrets.ALGOLIA_KEY }}' CONFIG_JSON_PRODUCT: 'HI' CONFIG_JSON_VERSION: '1.0' jobs: build: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v4 - name: Build docs using Writerside Docker builder uses: JetBrains/writerside-github-action@v4 with: instance: ${{ env.INSTANCE }} artifact: ${{ env.ARTIFACT }} docker-version: ${{ env.DOCKER_VERSION }} - name: Save artifact with build results uses: actions/upload-artifact@v4 with: name: docs path: | artifacts/${{ env.ARTIFACT }} artifacts/report.json artifacts/${{ env.ALGOLIA_ARTIFACT }} retention-days: 7 test: needs: build runs-on: ubuntu-latest steps: - name: Download artifacts uses: actions/download-artifact@v4 with: name: docs path: artifacts - name: Test documentation uses: JetBrains/writerside-checker-action@v1 with: instance: ${{ env.INSTANCE }} deploy: environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} needs: [build, test] runs-on: ubuntu-latest steps: - name: Download artifacts uses: actions/download-artifact@v4 with: name: docs - name: Unzip artifact run: unzip -O UTF-8 -qq '${{ env.ARTIFACT }}' -d dir - name: Setup Pages uses: actions/configure-pages@v4 - name: Package and upload Pages artifact uses: actions/upload-pages-artifact@v3 with: path: dir - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 publish-indexes: needs: [build, test, deploy] runs-on: ubuntu-latest container: image: registry.jetbrains.team/p/writerside/builder/algolia-publisher:2.0.32-3 steps: - name: Download artifact uses: actions/download-artifact@v4 with: name: docs - name: Unzip artifact run: | unzip -O UTF-8 -qq '${{ env.ALGOLIA_ARTIFACT }}' -d algolia-indexes env algolia-key='${{env.ALGOLIA_KEY}}' java -jar /opt/builder/help-publication-agent.jar \ update-index \ --application-name '${{env.ALGOLIA_APP_NAME}}' \ --index-name '${{env.ALGOLIA_INDEX_NAME}}' \ --product '${{env.CONFIG_JSON_PRODUCT}}' \ --version '${{env.CONFIG_JSON_VERSION}}' \ --index-directory algolia-indexes/ \ 2>&1 | tee algolia-update-index-log.txt
    Last modified: 19 April 2024