This won’t be a super chatty post. We have two websites for Game On! (our microservices text adventure): a jekyll-based markdown blog and a legacy-gitbook-based asciidoc book. For various reason, I want to combine them,and I woukd rather not spend gobs of time converting between markdown and asciidoc.

To keep things quick: I knew I wanted a static site generator, and I’ve used hugo before and found it fast, straight-forward and unconfusing. So in my mind, I’d already picked hugo.

I found these two posts on hugo with asciidoc:

• Better Hugo/AsciiDoc HTML
• Get Hugo to render (nice) Asciidocs

The second references the first. The first is also referenced in a git issue about some issues with how hugo invokes external helpers like asciidoc. The bottom line is that I can use hugo to do what I want, but there are some tricks required to influence how asciidoc is invoked to get better output.

Thinking about deployment

The existing two sites use Travis. They’ve existed so long (and have been running so well) that I forgot how to set them up. And, in the interim, the travis-ci.org vs. travis-ci.com shift has happened, and for one of the repos in particular, it feels like the settings have disappeared entirely. So. I can either figure out what happened with Travis and set that up again, or go fiddle with the new shiny thing, GitHub Actions.

The new shiny toy won because of these two actions:

• peaceiris/actions-hugo
• peaceiris/actions-gh-pages

These two actions (found easily in the marketplace) are well-documented and do exactly what I want. I will likely fork/clone/copy them over time, but it was nice to just see them already there.

At this point, I’m nowhere near ready for deployment, so I haven’t done much with the second. I used the first to start putting together a workflow that builds a new hugo-based site, with baby steps: First set-up hugo, then set up asciidoc with the tweaks noted above.

So far, this experiment looks like this:

 1name: publish
 2
 3on:
 4  push:
 5    branches:
 6    - hugo
 7
 8jobs:
 9  build:
10    runs-on: ubuntu-latest
11    steps:
12    - name: check out
13      uses: actions/checkout@v1
14
15    - name: Setup ruby
16      uses: actions/setup-ruby@v1
17      with:
18        ruby-version: '2.x'
19
20    - name: Setup Asciidoctor
21      run: |
22        gem install asciidoctor
23        gem install asciidoctor-html5s
24        gem install asciidoctor-diagram
25        . ./wrap_asciidoc.sh
26        asciidoctor --version        
27
28    - name: Setup Hugo
29      uses: peaceiris/actions-hugo@v2
30      with:
31        hugo-version: '0.62.2'
32
33    - name: Build
34      run: |
35        export PATH=$PWD/bin:$PATH
36        which asciidoctor
37        hugo --minify        

I defined one custom script (wrap_asciidoc.sh) used in the ‘Setup asciidoctor’ step to create a wrapper script to add required arguments when hugo makes the syscall to invoke asciidoctor. The path is updated in the ‘Build’ step to ensure the customized asciidoc script is used by hugo.

Take a look at the build output for these steps

I’ll stop here for now. The next bit of work is all about setting up the base set of templates I’ll need.