https://github.com/redhat-documentation/redhat-docs-template
Simple containerized Asciidoctor single-page website build
https://github.com/redhat-documentation/redhat-docs-template
Last synced: 4 months ago
JSON representation
Simple containerized Asciidoctor single-page website build
- Host: GitHub
- URL: https://github.com/redhat-documentation/redhat-docs-template
- Owner: redhat-documentation
- License: mit
- Created: 2023-06-01T08:20:11.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2023-06-22T09:13:58.000Z (almost 3 years ago)
- Last Synced: 2025-02-17T16:52:22.664Z (over 1 year ago)
- Language: CSS
- Homepage:
- Size: 166 KB
- Stars: 2
- Watchers: 4
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE
Awesome Lists containing this project
README
== About
A simple containerized Asciidoctor build that you can use build a clean and responsive single-page website.
.Example output
image::site.png[width=600px]
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:
+
[source,text]
----
assets
----
== Running the build locally
. Open a shell prompt at the folder containing your assembly.
. Pull the container image with Podman:
+
[source,terminal]
----
$ podman pull quay.io/redhat-docs/redhat-docs-template
----
. Load the build assets to the local context:
+
[source,terminal]
----
$ podman cp $(podman run --detach quay.io/redhat-docs/redhat-docs-template):/assets ./assets
----
. Optional. Add a custom SVG format logo:
+
[source,terminal]
----
$ cp assets/img/logo.svg
----
. Run the build:
+
[source,terminal]
----
$ podman run --rm -it -v "$(pwd)":/docs:Z quay.io/redhat-docs/redhat-docs-template
----
+
[NOTE]
====
Pass optional Asciidoctor format build parameters by using the `-a` switch. For example:
[source,terminal]
----
$ 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
[source,yaml]
----
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
[source,yaml]
----
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`:
+
[source,terminal]
----
cp docs/assets/img/logo.svg
----
. Commit the changes to redeploy the site with the new logo.