Publishing AsciiDoc documentation from a GitHub repo

1. Introduction

This repository is an example of how to publish your Asciidoc documentation on GitHub Pages. This allows you to easily include code snippets in your documentation. E.g. if this was an HTML tutorial, we could include the code as:

src/html/hello-world.html

<!DOCTYPE html>
<html>
  <head>
    <title>Page Title</title>
  </head>
  <body>
    <h1>This is a Heading</h1>
    <p>This is a paragraph.</p>
  </body>
</html>

2. Steps

2.1. Create a new repository on GitHub

Login to GitHub, click on New and give the repository a name.
Add a README. Although we’ll be renaming this file later, the repo needs at least one file in order to have a default branch.
Click Create Repository
As we will be using , we need to configure access. Under Settings > Actions > General > Workflow permissions, select Read and write permissions and press [Save].

2.2. Clone to local repository

After the repository is created, click on the green Code button and click Local > HTTPS to copy the URL.
Navigate to the folder in which you want to create a new folder with the repository.
Clone the repository using the URL previously copied:
```
git clone https://github.com/username/project.git
```

2.3. Create folder/file structure

cd into the git repo
```
cd project
```

Rename the README and create folders using the following commands:

git mv README.md README.adoc
mkdir src
mkdir src\docs
mkdir .github
mkdir .github\workflows

Edit README.adoc
Create src/docs/index.adoc
You can use the file in this repo as an example

Create file .github/workflows/build-asciidoc.yml as

name: build adocs

on:
  workflow_dispatch:
  push:
    branches:
    - main
jobs:
  adoc_build:
    runs-on: ubuntu-latest
    name: Asciidoctoring the docs to pretty HTML
    steps:
    - name: Checkout code
      uses: actions/checkout@v4
    - name: Get build container
      id: adocbuild
      uses: tonynv/asciidoctor-action@master
      with:
          program: "asciidoctor --destination-dir=docs --backend=html5 --out-file=index.html --attribute=data-uri src/docs/index.adoc"
    - name: Deploy docs to ghpages
      uses: peaceiris/actions-gh-pages@v4
      with: 
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_branch: gh-pages
        publish_dir: ./docs/

Add these new files to the repository:
```
git add .
```

Commit and push the files:

git commit -m "Initial Structure"
git push -u origin main

On GitHub.com, navigate to the Actions tab. You will probably see a failed run of the of the workflow. See instructions on https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-first-deployment-with-github_token

2.4. Configure GitHub Pages

The Asciidoc source has been rendered to HTML in branch gh-pages.

Navigate to Settings > Pages.
Set the source to gh-pages (root) and save.
At the top you will see the site URL. Copy it.
Click on the code tab
On the right hand side (About), click on the Settings icon.
Set the website field to Use your GitHub Pages website and press Save.

3. Notes on how it works

This project takes inspiration from a blogpost by James Read. Read this post if you want to add CSS styling or deploy on your own domain name.

The workflow contains two steps as shown below.

Manual triggering of the workflow is enabled by adding workflow_dispatch.

3.1. Notes on Asciidoctor

3.1.1. Single Page Output

This approach generates a single HTML file. If you want to generate a separate file per section, then look into these options:

3.1.2. Managing Images

Your Asciidoc source may reference images, as shown in the example above. Asciidoctor does not copy images from the source directory to the target directory. There are several solutions here:

Embed the images in the HTML file using the data-uri attribute. This is the approach used here.
Put the images and the Asciidoc sources in the /docs directory. The publish step will copy the directory contents across to gh-pages. A slight drawback of this method: it will also copy the Asciidoc sources.
Use Antora.

3.2. Notes on the GitHub Pages action

See documentation at https://github.com/peaceiris/actions-gh-pages