README.adoc

About

A simple containerized Asciidoctor build that you can use build a clean and responsive single-page website.

Figure 1. Example output

CSS based on https://github.com/uroesch/asciidoctor-readthedocs-theme

Prerequisites

• Install Podman

• Add the following line to your source repo .gitignore and commit the change:

  assets

Running the build locally

1. Open a shell prompt at the folder containing your assembly.

2. Pull the container image with Podman:

   $ podman pull quay.io/redhat-docs/redhat-docs-template

3. Load the build assets to the local context:

   $ podman cp $(podman run --detach quay.io/redhat-docs/redhat-docs-template):/assets ./assets

4. Optional. Add a custom SVG format logo:

   $ cp <path_to_logo> assets/img/logo.svg

5. Run the build:

   $ podman run --rm -it -v "$(pwd)":/docs:Z quay.io/redhat-docs/redhat-docs-template <asciidoc_assembly_file> <optional_parameters>

   Note	Pass optional Asciidoctor format build parameters by using the -a switch. For example: $ podman run --rm -it -v "$(pwd)":/docs:Z quay.io/redhat-docs/redhat-docs-template main.adoc -a internal

Using the container build in a GitHub action

Copy the following YAML to the .github/workflows/deploy-site.yml file in your repository. Adjust as required. Commit and push the changes to deploy the site with GitHub pages.

Build assumes main.adoc is in the project root.

Example deploy-site.yml

name: Build and deploy website

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v3

      - name: Extract assets
        run: docker cp $(docker run --detach quay.io/redhat-docs/redhat-docs-template):/assets ./assets

      - name: Build AsciiDoc
        uses: docker://quay.io/redhat-docs/redhat-docs-template
        with:
          args: main.adoc

      - name: Copy output to docs/
        run: |
          mkdir docs
          cp -r assets/ docs/assets
          cp -r images/ docs/images
          mv index.html docs/

      - name: Publish to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs

Using the container build in a GitLab pipeline

Copy the following YAML to the .gitlab-ci.yml file in your repository root. Adjust as required. Commit and push the changes to deploy the site using GitLab pages.

Build assumes main.adoc is in the project root.

Example .gitlab-ci.yml

image:
  name: quay.io/redhat-docs/redhat-docs-template
  entrypoint: [""]

pages:
  stage: deploy
  before_script:
    - cp -r /assets assets
  script:
    - /build.sh main.adoc
    - mkdir public
    - cp -r /assets public/assets
    - cp -r images/ public/images
    - mv index.html public/
  artifacts:
    paths:
    - public
  only:
    - main
  tags:
    - shared
    - docker

Adding a custom navbar logo to the GitHub action build

1. Add the custom SVG format logo file to your repo.

2. Add the following line to the Copy output to docs/ stage in .github/workflows/deploy-site.yml:

   cp <relative_path_to_logo> docs/assets/img/logo.svg

3. Commit the changes to redeploy the site with the new logo.