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:
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:
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
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.