Creating a blog using Asciidoc and Hugo

This repo contains source materials to accompany the article on opensource.com for getting started with Hugo and asciidoc as a web development platform.

Figure 1. The server

Installing Asciidoc and Asciidoctor.

Ubuntu

Asciidoc is available in the default repos.

sudo apt-get install asciidoc asciidoctor -y

Fedora

Asciidoctor can be installed using the gem command. Asciidoc is installed through the standard repos.

yum install asciidoc
gem install asciidoctor

For more detailed installation information, visit the following guides.

Installation Guides

• Asciidoc.

• Asciidoctor.

Installing Hugo

The best guide for installing Hugo is on their website. I found it was worth following this guide rather than use the package maintained in the Ubuntu repo as it was older and caused problems with modern themes.

How do I use these files?

The repo contains a demo website with some sample articles in Asciidoc. The following folders are useful starting points.

Clone the repo

git clone git@github.com:opensourceway/asciidoc-blog.git

Figure 2. Folder Structure

For more information, checkout the documentation on the Hugo Homepage

Starting the server

From the root directory of the cloned repo:

hugo server  --buildDrafts

This will run the server where you can see your website locally on http://localhost:1313.

Figure 3. The server

To make changes to the setup, you can edit the config.toml file and set your website preferences up. The site contains initial setup parameters.

Content is available under the folder content/post. There are some example articles available to get you started.

Working with Asciidoc

My personal preference is to use Vim for working with Asciidoc, there are a number of plugins which make working with Asciidoc easier as well as a syntax file for highlighting your document.

If you are looking for something more visual, I would recommend the Atom editor from GitHub. It has plugins which provide a real-time preview of your work and makes it easier to work with GitHub. Using Hugo, Asciidoc and the Atom editor, you have a complete publishing system with real time previews and a local server to run validation against.

Figure 4. Atom Editor, click for full screen

Where to go from here?

You can tailor the site in the config.toml file to personalise your setup. There are a number of themes available to further customise your site. The language behind the more dynamic elements is very well implemented and there’s excellent documentation on the Hugo website on how to get started working with content and theming. The theme used in this demo is the Strata Theme by Digitalcraftsman which has detailed documentation on configuration options available on it’s github page.

Thanks and credit due.

Thanks to Steve Francia for Hugo, for producing a fun platform to play with. The Strata theme port and the Hugo community.

Useful resources

Hugo

• Hugo

  • Installation

  • Quick Start Guide

  • Github Repo

  • Starter Kits

• Hugo Themes

• Community

Asciidoc

• Asciidoc

  • Code Examples

  • User Guide

  • Cheat Sheet

• Asciidoctor

Editors and Frontends

• Atom Editor

• Vim Plugins

  • Asciidoc Syntax

  • Markdown Syntax

Demo and source materials

• Strata Theme

• Steve Francia’s homepage maintainer of Hugo