Writerside Help

Build and publish on GitHub

This article describes how to use GitHub Actions to build a help instance that you will host somewhere else or deploy it to GitHub Pages.

Writerside maintains a GitHub Action for building documentation in a Docker container: https://github.com/marketplace/actions/build-writerside-docs-using-docker

Build artifacts

  1. Create the file .github/workflows/deploy.yml file in your project with the following workflow configuration:

    name: Build documentation on: # If specified, the workflow will be triggered automatically once you push to the `main` branch. # Replace `main` with your branch’s name push: branches: ["main"] # Specify to run a workflow manually from the Actions tab on GitHub workflow_dispatch: env: # 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 # Add the variable below to upload Algolia indexes # Replace HI with the ID of the instance in capital letters ALGOLIA_ARTIFACT: algolia-indexes-HI.zip jobs: build: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v3 - name: Build Writerside docs using Docker uses: JetBrains/writerside-github-action@v4 with: instance: ${{ env.INSTANCE }} artifact: ${{ env.ARTIFACT }} docker-version: ${{ env.DOCKER_VERSION }} - name: Upload documentation uses: actions/upload-artifact@v3 with: name: docs path: | artifacts/${{ env.ARTIFACT }} artifacts/report.json retention-days: 7 # Add the step below to upload Algolia indexes - name: Upload algolia-indexes uses: actions/upload-artifact@v3 with: name: algolia-indexes path: artifacts/${{ env.ALGOLIA_ARTIFACT }} retention-days: 7 # Add the job below and artifacts/report.json on Upload documentation step above if you want to fail the build when documentation contains errors test: # Requires build job results needs: build runs-on: ubuntu-latest steps: - name: Download artifacts uses: actions/download-artifact@v1 with: name: docs path: artifacts - name: Test documentation uses: JetBrains/writerside-checker-action@v1 with: instance: ${{ env.INSTANCE }}
  2. Set the correct values for the following environment variables:

    INSTANCE

    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.

    ARTIFACT

    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.

    DOCKER_VERSION

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

    ALGOLIA_ARTIFACT

    The name of the produced archive with search indexes is algolia-indexes-XX.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 ALGOLIA_ARTIFACT: algolia-indexes-FH.zip.

  3. Commit the new workflow file and push it to GitHub. To find the built artifact, on GitHub go to the Actions tab, click the particular workflow run, and scroll down to the Artifacts section.

Build and publish to GitHub Pages

  1. On GitHub, go to your repository and open Settings | Pages.

  2. In the Source field of the Build and deployment section, select GitHub Actions and click Save.

  3. Create the file .github/workflows/deploy.yml file in your project with the following workflow configuration:

    name: Build documentation on: # If specified, the workflow will be triggered automatically once you push to the `main` branch. # Replace `main` with your branch’s name push: branches: ["main"] # Specify to run a workflow manually from the Actions tab on GitHub workflow_dispatch: # Gives the workflow permissions to clone the repo and create a page deployment permissions: id-token: write pages: write env: # 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 # Add the variable below to upload Algolia indexes # Replace HI with the ID of the instance in capital letters ALGOLIA_ARTIFACT: algolia-indexes-HI.zip jobs: build: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v3 - name: Build Writerside docs using Docker uses: JetBrains/writerside-github-action@v4 with: instance: ${{ env.INSTANCE }} artifact: ${{ env.ARTIFACT }} docker-version: ${{ env.DOCKER_VERSION }} - name: Upload documentation uses: actions/upload-artifact@v3 with: name: docs path: | artifacts/${{ env.ARTIFACT }} artifacts/report.json retention-days: 7 # Add the step below to upload Algolia indexes - name: Upload algolia-indexes uses: actions/upload-artifact@v3 with: name: algolia-indexes path: artifacts/${{ env.ALGOLIA_ARTIFACT }} retention-days: 7 # Add the job below and artifacts/report.json on Upload documentation step above if you want to fail the build when documentation contains errors test: # Requires build job results needs: build runs-on: ubuntu-latest steps: - name: Download artifacts uses: actions/download-artifact@v1 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 }} # Requires the build job results needs: test runs-on: ubuntu-latest steps: - name: Download artifact uses: actions/download-artifact@v3 with: name: docs - name: Unzip artifact uses: montudor/action-zip@v1 with: args: unzip -qq ${{ env.ARTIFACT }} -d dir - name: Setup Pages uses: actions/configure-pages@v2 - name: Upload artifact uses: actions/upload-pages-artifact@v1 with: path: dir - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v1
  4. 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="github-repository-name"/> <instance src="hi.tree"/> </ihp>
  5. Set the correct values for the following environment variables:

    INSTANCE

    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.

    ARTIFACT

    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.

    DOCKER_VERSION

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

    ALGOLIA_ARTIFACT

    The name of the produced archive with search indexes is algolia-indexes-XX.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 ALGOLIA_ARTIFACT: algolia-indexes-FH.zip.

  6. Commit the new workflow file and push it to GitHub. To find the built artifact, on GitHub go to the Actions tab, click the particular workflow run, and scroll down to the Artifacts section.

Last modified: 04 August 2023