About
A simple containerized Asciidoctor build that you can use build a clean and responsive single-page website.
Prerequisites
-
Install Podman
-
Add the following line to your source repo
.gitignore
and commit the change:assets
Running the build locally
-
Open a shell prompt at the folder containing your assembly.
-
Pull the container image with Podman:
$ podman pull quay.io/redhat-docs/redhat-docs-template
-
Load the build assets to the local context:
$ podman cp $(podman run --detach quay.io/redhat-docs/redhat-docs-template):/assets ./assets
-
Optional. Add a custom SVG format logo:
$ cp <path_to_logo> assets/img/logo.svg
-
Run the build:
$ podman run --rm -it -v "$(pwd)":/docs:Z quay.io/redhat-docs/redhat-docs-template <asciidoc_assembly_file> <optional_parameters>
NotePass 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.
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.
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
-
Add the custom SVG format logo file to your repo.
-
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
-
Commit the changes to redeploy the site with the new logo.