README.adoc

About

A simple containerized asciidoctor-pdf build that you can use build a Red Hat themed PDF.

Prerequisites

• Install Podman

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

  pdf-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-pdf-template

3. Load the build assets to the local context:

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

4. Optional. Add a custom SVG format logo:

   $ cp <path_to_logo> pdf-assets/images/logo.svg

5. Run the build:

   $ podman run --rm -it -v "$(pwd)":/docs:Z quay.io/redhat-docs/redhat-docs-pdf-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-pdf-template main.adoc -a internal

Using the container build in a GitHub action

Copy the following YAML to the .github/workflows/build-pdf-release.yml file in your repository. Commit and push the changes to create the PDF as a GitHub release artifact.

Example build-pdf-release.yml

name: Build and deploy PDF

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-pdf-template):/pdf-assets ./pdf-assets

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

       - name: Create PDF release
         run: |
           echo $GITHUB_RUN_NUMBER > version.txt
           mv main.pdf redhat-docs-pdf-template.pdf
           gh release create v$GITHUB_RUN_NUMBER redhat-docs-pdf-template.pdf
         env:
           GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

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-pdf-template
  entrypoint: [""]

pages:
  stage: deploy
  before_script:
    - cp -r /pdf-assets pdf-assets
  script:
    - /build.sh main.adoc
  artifacts:
    paths:
    - ./main.pdf
  only:
    - main
  tags:
    - shared
    - docker