Introduction

Given that we at millross have to write different kinds of documentation, it seems less than ideal to write our blog in one markup language (MarkDown), but other technical documentation in AsciiDoc, so we thought we’d look at writing our own blog in AsciiDoc and generating HTML ready for upload. This is how we went about it: it may not be the perfect (or even the best) approach, but it’s how we got this blog up and running.

AsciiDoc is a simple and powerful lightweight markup language for authoring of all kinds - whether technical documentation such as that hosted at the Spring documentation site, notes, books/ebooks, slide decks, web pages/blogs etc. While Markdown is also lightweight, I’d say that AsciiDoc is far more of a universal tool for all kinds of writing.

Getting AsciiDoctor

If you’re going to write your blog in AsciiDoc, you will need the tools to convert your AsciiDoc markup into HTML. For this we chose AsciiDoctor, which you can install by following the instructions available on this page.

Since we already have Ruby installed, we chose the "gem install method".

Our first blog page and home page

So now let’s create our first - trivial blog post. Pick your favourite text editor - remember AsciiDoc is all about concentrating on content rather than formatting, and copy and paste the following block into it:-

= Our first blog post

Now a short paragraph to represent a summary or abstract of our blog post, which we'll
use later for our blog post list page.

== And now the first real section of the blog post

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec quis pharetra mauris,
at faucibus libero. Nunc at fermentum tortor, at congue purus. Ut nec tempus quam,
nec rutrum orci. Donec at imperdiet odio. Cras non nisi tempus, accumsan lectus at,
rutrum ante. Nulla auctor felis a diam gravida mollis. In efficitur neque quis diam
rutrum, maximus iaculis lectus sagittis. Proin quis hendrerit risus, id congue diam.
Vivamus ultricies quam erat, sed molestie nunc tempus vel. Vivamus sollicitudin, arcu
ut euismod placerat, odio tellus accumsan augue, nec pulvinar tortor nulla ac ligula.
Sed ullamcorper mattis faucibus. Vivamus in justo a eros eleifend malesuada. Suspendisse
quis consectetur tortor. Quisque orci leo, euismod in quam id, iaculis euismod nulla.
Aliquam vel purus sed nunc tempor volutpat. Integer diam erat, euismod eu faucibus sed,
finibus eget risus.

Nulla nec massa lectus. Nulla vel consequat neque, nec varius dolor. Vivamus tincidunt
nunc felis, at tempus libero pretium a. Pellentesque vel elit et nibh congue fringilla
vel at leo. Vivamus nibh eros, condimentum eget urna scelerisque, rutrum euismod sem.
Maecenas odio elit, elementum at erat nec, aliquet iaculis massa. Interdum et malesuada
fames ac ante ipsum primis in faucibus. Phasellus finibus lacus augue, sed hendrerit
rci malesuada eu. Morbi et iaculis nibh. Maecenas magna turpis, cursus ut fringilla non,
lobortis vel eros.

Ut et congue dolor, quis pretium urna. Pellentesque quis nulla tempus, sollicitudin
massa et, scelerisque mauris. Pellentesque sagittis mauris ac ullamcorper vulputate.
Curabitur eleifend non arcu sit amet efficitur. Fusce suscipit augue id turpis accumsan,
nec mattis nulla aliquet. Proin convallis ipsum lorem, non aliquam dui porta a. Nullam
sed aliquet orci, eu mattis nibh. Cras et felis vitae tortor tempus pellentesque dictum
sed erat. Morbi in justo nisl. Phasellus mauris sapien, posuere nec velit et, pellentesque
rutrum eros. Maecenas dui dolor, fringilla vitae lacus in, gravida laoreet elit. Etiam
finibus leo at iaculis imperdiet.

Now save this file as blogpost1.adoc, this is our first notional blog post, which we will make a few changes to later, this is just to demonstrate how easy it is to process.

Conversion to HTML

Now we have our initial blog post in AsciiDoc format, the next stage is to convert it to an HTML file. While you can make it dependent on external CSS (we will revisit it later) for now let’s use the default styles/formatting, which are pretty nice.

I suggest writing the output html files into a separate directory to your source files - create a subdirectory called web (to hold your generated HTML files).

Issue the command

asciidoctor --destination-dir web *.adoc

If you now list the contents of the "web" directory, you should see a file called blogpost1.html. Open this in a browser and you should see a nicely formatted HTML version of the text we put into that file. It’s that easy to take the AsciiDoc markup and turn it into a nice-looking blog.

Syntax Highlighting in your favourite editor

There is widespread editor support for syntax highlighting for AsciiDoc files. We use vim for editing our adoc files, so we basically adapted the instructions found here to configure vim to display with highlighting.

The reason I write "adapted" is because we use pathogen to manage our vim syntax plugins, and autoloading, so although we use the syntax file recommended for AsciiDoc, we actually installed the syntax support by cloning gnperdue’s asciidoc for vim pathoten repository which, used with pathogen, works immediately.

Creating a blog post list for the index

So now we have a simple blog post. What remains is to generate a blog post list to act as an entry point for the blog, most recent blogs first. The format we intend to adopt is the blog post title, linked to the actual blog post file, then a display of the summary/abstract paragraph we defined earlier, and then a "See more" link, which again links to the actual blog post file.

For now we’ve made this a manual process at millross, but the intent is that it should be possible to automate this (we simply haven’t looked at doing so yet, as the additional work per post is relatively small).

To include the summary, we’ll use the magic of AsciiDoc inclusion from other source files. By using Tagged regions it’s possible to include just a subset of a given blog post file (in this case the summary) tags, it’s possible to only include a subsection from another file.

So first let’s open up blogpost1.adoc and tag the summary section. The // character combination in AsciiDoc represents a comment and tags should be identified with this character, so add a comment above the "short paragraph to represent a summary" - // tag::summary[] and then immediately after that paragraph another comment to close the tag - // end:summary[].

Now save blogpost1.adoc again, now we need to create our blog list.

Open a new file in your favourite text editor, this will be our blog list file. Enter the following text into the editor

= My Blog
Fred Bloggs <fred@example.com>

=== Our first blog post
*2014-09-05* +
include::blogpost1.adoc[tags=summary]
link:blogpost1.html[Read more]

(Note you will need to insert your own date - I haven’t yet found a mechanism within AsciiDoctor for extracting attributes from other files, which is what I really want to do, creation of a pre- processor to generate this index should resolve this.)

Save this as blog_list.adoc, then re-run the command to generate the html

asciidoctor --destination-dir web *.adoc

Now open blog_list.html from the web subdirectory in your browser and you should see the summary of your first blog entry in there, along with the date of writing and a "Read more" link which will take you to the actual blog entry.

Automate, automate, automate

Finally, anticipating future work with the styles for the HTML we generate, I would recommend saving the generation of html command into a shell script/batch file so that you can add additional processing/preprocessing later.