docker run -p 4000:4000 --volume="$PWD:/srv/jekyll" -it jekyll/jekyll:3.5 jekyll serve --drafts
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.
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.
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.
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.
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.
Jekyll:Asciidoc is a Jekyll plugin which renders Asciidoc source files to HTML.
Using Docker, it’s really simple to test Jekyll-Asciidoc.
Clone Jekyll Asciidoc Quickstart.
Inside cloned project, simply run (You may have Docker installed on your system) :
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/
.
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 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 file inside _posts
directory.
Name pattern : YYYY-MM-DD-my-post-title.adoc
A valid name : 2018-01-28-jekyll-asciidoc-blog.adoc
= 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 files are not rendered when build, but available when serving using |
For each required category (or tag), you may create a file in _category
, with the following content :
:page-root: ../../../
:page-title: MyCategory
:page-category: mycategory
Within a post, use :page-categories: […]
header to categorize it.
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 :
.Image title
[link=/assets/img/my-post/image1.jpg]
image::/assets/img/my-post/image1.jpg[600,400]
Still using docker, use the following command from the root of your project :
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.