ebullient·works

[ About · Archive ]

From Jekyll and GitBook to Hugo and Asciidoc, care of Github Actions

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:

name: publish

on:
  push:
    branches:
    - hugo

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: check out
      uses: actions/checkout@v1

    - name: Setup ruby
      uses: actions/setup-ruby@v1
      with:
        ruby-version: '2.x'

    - name: Setup Asciidoctor
      run: |
        gem install asciidoctor
        gem install asciidoctor-html5s
        gem install asciidoctor-diagram
        . ./wrap_asciidoc.sh
        asciidoctor --version

    - name: Setup Hugo
      uses: peaceiris/actions-hugo@v2
      with:
        hugo-version: '0.62.2'

    - name: Build
      run: |
        export PATH=$PWD/bin:$PATH
        which asciidoctor
        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.

Scripts for the win! Updating git repositories for the lazy.

I love scripts! I treat them as my extended memory. Blog posts used to do this, but life and children have eaten up the capacity I used to have for writing.

But I thought I would share my latest script for the lazy (which I have now duplicated several times. I know, I know. WET, DRY. I can’t be bothered). This script iterates over all of the git repositories in a sub-directory (where I have several related ones), fetches everyting, fast-forwards if it can, and otherwise tries to rebase on the upstream branch if there is one that matches.

There is an extra case statement at the bottom as I inevitably extend this to do more things specific to this group of projects. This kind of approach grew out of the scripts written for Game On!, which still work well, and do their extra duty reminding me what on earth I was doing the last time I worked on it.

[more]

Monsters and Metrics at SpringOne 2019

Two things collided in my brain this year ahead of SpringOne: Preparing a new talk from scratch covering the Micrometer (and the related Spring implementation), and learning everything I needed to know to be a Dungeon Master for my 10-year-old son and his friends.

Thanks to a brilliant suggestion from a friend, these two things collided in the talk, too. Which lightened the mental load (or at least reduced the amount of full stack swapping going on).

Github repository: ebullient/monster-combat with Spring Boot 2, WebFlux, and Micrometer

Debug gulp

I had a gulp build unhelpfully finishing with:

(node:12030) UnhandledPromiseRejectionWarning: null
(node:12030) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). (rejection id: 1)
(node:12030) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

So I added this to my gulpfile:

process.on('unhandledRejection', (reason, p) => {
  console.log('Unhandled Rejection at: Promise', p, ', reason:', reason);
});

which netted me this:

Unhandled Rejection at: Promise Promise {
  <rejected> null,
  domain:
   Domain {
     domain: null,
     _events: { error: [Object] },
     _eventsCount: 1,
     _maxListeners: undefined,
     members: [] } } reason: null

Not much better.

Let’s try debugging gulp! How do I do that again?

In VS Code, let’s create a debug configuration that is brain-bashingly simple. Add this to launch.json:

      {
        "type": "node",
        "request": "attach",
        "name": "Attach to Remote",
        "address": "127.0.0.1",
        "port": 9229,
        "localRoot": "${workspaceFolder}/resources",
        "remoteRoot": "Absolute path to the remote directory containing the program"
      }

Now launch gulp with some options. I’m using npx here because I detest npm install -g:

$ npx -n --inspect-brk gulp build

This process will now wait until VS Code attaches. At which time, do check the “Uncaught Exceptions” box in the breakpoint section of the debug panel.

Press play, and .. there it is. A much clearer picture of what tipped over. I feel so much better.

(Hope this helps, future self)

Doing the scary thing: Mainstage at SpringOne

I will absolutely confess that it was daunting to start with, but that once I was out on the stage, everything was fine.

I will also confess to ad nauseum rehearsal. To reciting what I had to cram into two segments (one only 2 minutes long, and the other 2 minutes and 30 seconds) to every inanimate object in my hotel room: lamps, laptops, mirrors, showerheads, and I’m pretty sure my pillow while I was sleeping.

I didn’t really wrap my head around what I wanted to say until the night before. Things just didn’t fall into place before then. But hey, I lived! It was quite the experience.

Git with edit on an iPad?

We shall see how this goes over time, but so far? Oh hell yes.

I am experimenting with a cute little app (I have, sad to say, fallen head over feet into the Apple ecosystem. Other devices might seem cool, but not worth the gymnastics. Ecosystem stickiness is a thing.) that allows me to edit. code. from. my. iPad.

Why would I want to do that?

  • Device junky that I am, I totes splurged and got an iPad Pro, with its little keyboard.
  • I would really really really like to make more entries to this blog, for example. This is a nice alternative to hauling laptop around.
  • I want to see how far I can push this über tiny device thing, that ALSO happens to have a stylus (yes, I am one of those people that thinks better long-hand).

So exciting!

The one challenge with this, in particular, is that I can’t get the Jekyll preview that I could if I were running locally. The iPad Pro is quite the workhorse… but it doesn’t (yet, ha!) run Docker containers.

Oh, right. The app: Working Copy. It also integrates with iOctocat.

posted
tags:

Jekyll templates with Docker containers

It took me a few tries (divided attention, grr), but I realized that after messing with blogs for over 10 years, I’ve seen all the things! Way back in the beginning was Movable Type (which I didn’t realize was still a thing), followed by PHP-based CMS like Textpattern and Nucleus CMS, and then a brief flirtation with Blogger (someone made me do it). I have somehow avoided ever having to maintain templates for WordPress (?!). These systems all come back to some pretty basic concepts around templating.

The one snag was loathing having to do anything with ruby. I have never had anything but grief and pain installing ruby anywhere. But hey! We have docker now! Put it in a container and forget about it. WOOT!

[more]

From then to now.. blogs over 12 years

Yes, I confess, I did .. umm.. censor my blogs over the years. When facebook arrived, blog posts about nasty headaches and reactions to the latest headlines could all go away. The exodus of content continued with the advent of Twitter. Which left this blog, which I’ve tended on and off for close to 14 years, in the lurch!

There is also the small matter of how much time I have to spend on blog posts between work, kids, and this mammoth garden we have going in the back yard. The mammoth garden is totally my fault, we started it as an excuse to get me outside. It worked.

However, it has become obvious that a return to blogging is overdue. To start with, Game On! needed a blog! We kept having little tidbits to share, that needed a home. I made an initial foray into creating a blog with Jekyll to build a new blog for Game On!. I kind of liked how that worked, AND it meant I could stop having to edit posts via the web, and so I’ve now brought that to my own blog, too.

Next post: the jekyll stuff.

posted
tags: