blog.arkey.fr

This blog is generated by Hugo.

Local Setup

To avoid a permission error when installing gem, I propose to use rbenv to set up a local ruby environment.

permission error

Fetching asciidoctor-2.0.16.gem
ERROR:  While executing gem ... (Gem::FilePermissionError)
    You don't have write permissions for the /Library/Ruby/Gems/2.6.0 directory.

brew install rbenv
eval "$(rbenv init -)" # should set rbenv in the .zshrc
rbenv install 2.7.5
rbenv global 2.5.1
rbenv rehash
gem install asciidoctor
gem install asciidoctor-diagram

cargo install svgbob_cli --version 0.5.0-alpha.8

brew install hugo

And serve, the ./serve.sh script runs Hugo and build draft as well as future content.

./serve.sh

This script prepends the $PATH variable with this repository’s ./bin folder in order to trick Hugo to use my custom asciidoctor script which configures asciidoctor with wanted options, like -r asciidoctor-diagram.

exec env PATH=$PWD/bin:$PATH hugo serve --baseUrl=blog.local --bind=0.0.0.0 --buildDrafts

Interesting attributes

This site now rely on asciidoc content, in order to ease content edition and publication, it is useful to set a few attributes in the editor.

Attribute	Value	Description
image-assets	path to the static/assets local folder	This attribute is used to allow images to show up in the IDE preview. Site images are published on /assets/…​, whn this path is used, the IDE will look this path on the local disk which will not work of course ; also when an image path has a leading slash, the imagesdir / imagesoutdir are ignored, and this didn’t work well anyway with diagram generation asciidoctor-diagram#110. Note 1: it is set to /assets in the site config.toml. Note 2: this is a custom attribute.
ditaa-format	svg	Renders DITAA diagrams as SVG, better legibility on high dpi screens
plantuml-format	svg	Renders PlantUML diagrams as SVG, better legibility on high dpi screens
svgbob	path to svgbob binary	If the IDE don’t correctly detect svgbob path, it can be set with this attribute. The svgbob tool is used to generate SVG from ascii character.
icons	font	Tells asciidoctor to use font-awesome for admonition blocks.

Publish locally

There’s also the publish.sh script which allows to publish locally the site and commit the files to the master branch.

Server

The blog is served by Github Pages, and the job is run by Github Actions. With the current setup, the HTML files are served from the master branch.

name: GitHub Pages

on:
  push:
    branches:
      - hugo-sources

jobs:
  build-deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true
          fetch-depth: 0

      - name: Build
        run: docker run --rm --volume $PWD:/src bric3/hugo-builder hugo # (1)

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          publish_branch: master
          publish_dir: ./public
          cname: blog.arkey.fr
#          force_orphan: true

1. Custom docker builder image

In order to build asciidoc content, I created a custom Docker image, that install asciidoctor and asciidoctor-diagram, also this Docker image prepends the $PATH environment variable in order to customize the asciidoctor configuration.