A Jekyll Asciidoc blog

Static Site versus CMS

Since a while, creating a blog or any content-oriented website involves using a CMS, such as Drupal or Wordpress.

Create a static blog using raw html and css seems old school and unefficient.

That’s true for the most part ; write and manage content without using a content-management-system is quite complicated and may not be very efficient, especially for non-technical people.

Simple, faster, secure

A static site could be a lot faster. No API calls, no server side processing, no database requests.

Without any back end, it’s also more secure by definition. There’s nothing to hack, no admin password, no possible sql injections.

Keeping a CMS safe from hacking require frequent updates, sometimes with unattended problems, suck as no backward compatibility with some modules.

Static Site Generator

A Static Site Generator builds a static site from plain text and templates. It could be seen as an offline CMS back end.

There’s a few generator available, such as Hugo or Hexo. I’ve chose Jekyll, especially because of the Asciidoc plugin.

A Static Site with Jekyll

Jekyll is a Static Site Generator written in Ruby.

Jekyll is behing Git Hub Server Pages, which makes it quite popular.

Jekyll transforms text files and templates and render them as static pages.

Asciidoc

Jekyll, by default, renders Markdown, which is nice and efficient.

I prefer using Asciidoc, which is also a markup language. To me it seems more evolved than markdown, with useful features, especially when writing technical posts or documentation.

Asciidoctor is a text processor which converts Asciidoc to html or pdf formats.

Quickstart Jekyll:Asciidoc

Jekyll:Asciidoc is a Jekyll plugin which renders Asciidoc source files to HTML.

Using Docker, it’s really simple to test Jekyll-Asciidoc.

Inside cloned project, simply run (You may have Docker installed on your system) :

Run jekyll serve
docker run -p 4000:4000 --volume="$PWD:/srv/jekyll" -it jekyll/jekyll:3.5 jekyll serve --drafts

Then your site is served from http://localhost:4000/.

dev.kprod.net (this blog)

This blog is based on Jekyll:Quickstart.

A sample version with sources is available is available on Github.

I’m briefly describing below some of the basic usage of Jekyll:Asciidoc with my modifications.

Layouts

Layouts are stored in _layouts directory.

  • default.html : Layout for a simple page. Used for index page.

  • post.html : Standard layout for a post.

  • category.html : Layout for category page, listing all posts in current category

Create a new post

Create a new file inside _posts directory.

Name pattern : YYYY-MM-DD-my-post-title.adoc

A valid name : 2018-01-28-jekyll-asciidoc-blog.adoc

Post header
= My Post title
:showtitle:
:page-layout: post
:page-navtitle: Short title
:page-excerpt: Excerpt goes here.
:page-root: ../../../
:page-liquid:
:page-permalink: my-post-permalink
:page-categories: [category1,category2]

The rest of the file is the content of your post.

While writing, _drafts directory could be used instead of _posts.

Drafts files are not rendered when build, but available when serving using --drafts

Categories

For each required category (or tag), you may create a file in _category, with the following content :

Define a category
:page-root: ../../../
:page-title: MyCategory
:page-category: mycategory

Within a post, use :page-categories: […​] header to categorize it.

Images

For each post I create an individual directory in assets/img, for example assets/img/my-post.

To display an image with a link to full version :

Including an image
.Image title
[link=/assets/img/my-post/image1.jpg]
image::/assets/img/my-post/image1.jpg[600,400]

Build you site

Still using docker, use the following command from the root of your project :

Jekyll site build
docker run -p 4000:4000 --volume="$PWD:/srv/jekyll" -it jekyll/jekyll:3.5 jekyll build

The result of this building process is available in _site directory.

comments powered by Disqus