Generate AsciiDoc Documentation and Publish it with GitLab Pages

We setup a repository and add a directory named docs there .. this is the home of our AsciiDoc files.

We’re using asciidoctor/docker-asciidoctor as Docker image for tool provisioning

This is the .gitlab-ci.yml, we’re running the stage only when something in the docs directory has changed.

stages:
  - "Build docs"

# The name of the job activates the GitLab pages publication
pages:
  image: asciidoctor/docker-asciidoctor
  stage: "Build docs"
  tags:
    - build
  script:
    - sh ./gen_docs.sh
    - mv output public
  only:
    refs:
      - master
    changes:
      - /docs/*
  artifacts:
    paths:
      - public
    expose_as: 'Documentation Archive'

Our shell script gen_docs.sh simply cleans up our output directory and then executes the asciidoctor binary.

gen_docs.sh
#!/bin/bash

set -e
set -x

rm -rf output
mkdir -p output

ASCIIDOC_HTML="asciidoctor \
    -B `pwd`/docs \
    -b html5 \
    -r asciidoctor-diagram \
    -a data-uri \
    -a icons=font \
    -a toc=left \
    -a idprefix \
    -a idseparator=- \
    -a source-highlighter=coderay \
    -D `pwd`/docs/output"


$ASCIIDOC_HTML docs/ourfile.adoc

Push without Pipeline Trigger

Either git push using a special push option

git push -o ci.skip

Or append [skip ci] to your commit message