How to write articles in Jekyll
I love Markdown! it is such a wonderful format to write content in.
My last blog was hosted on WordPress, but I stopped blogging a few years ago. Why?
Because I had to be online in order to be able to write. Actually I am writing this article using Vim on Termux on Android. Offline.
In this article I want to explain my authoring workflow.
Collecting ideas
While outside ideas tend to come. I started to jot them down in an to-do app, which focus on simplicity and GTD.
They usually just contains some keywords to remind me on what I want to do or write about.
Preparing an article
Since I am using Jekyll for blogging, I’ve created a _drafts
directory.
In that I create files which first are empty and just maps to a title.
Later on I start writing headlines (one <h1>
, the rest lower) to have an
outline. the <h1>
should match the title and contain key words you want to be
found with on search engines.
The other headlines should be written in a way that you get an idea about what the article is about by just reading them.
A good idea is to explain first, what the reader can take away after the reading, than laying out prerequisites (with links to other posts explaining them in more detail).
Start filling the gaps between the headlines without worrying about typos.
You can fix those later. Same with checking for understandably. Don’t care
for now. You want to get the content out of your head. Things like looking,
whether you write from I
or you
perspective can be adjusted later.
After you have written down, think about keywords. There are some people out
there suggesting to have keywords in the title, in the only <h1>
of the
article, as <strong>
and in alt
attributes of images.
In my opinion you should look after the article would satisfy your query when you would have stumbled upon it on the Internet looking for a solution to a problem. After all you are writing for humans, not machines ;-)
One thing which is admittedly cool is semantic markup. Say you are writing down your experience of a conference or meetup you participated in lately. Wouldn’t it be cool if you could make a machine understand, that it is about an event?
In fact you can do this today!
There are mechanics like schema.org or microformats to assist you.
schema.org (or microdata) has the backing of large Internet, while microformats
is defined by the crowd. The latter requires markup, while the former allows
you to use a <script>
plus a defined JSON scheme (use yandex validator, since
Google is doing a bad job here).
This way you can write a Jekyll plugin and define information about the article
in the front matter. The plugin will generate the <script>
for you.
Publishing an article
So you are satisfied. What now?
Of course, get it out of _drafts
!
Therefore create a new directory _pages
, if you have a page, or _posts
, if
it is a blog article.
Then move the article from _drafts
to _posts
and rename it to
YYYY-MM-DD-<my-target-url>.md
. This way it gets sorted for you.
Personally I tweaked my _config.yml
to omit date and categories from URL and
just output the title:
permalink: /:title/
does that for me. I want to have a short URL and don’t need to have date or category information in the URL. I can create filtered pages for that.
Publishing pages
Add a directory _pages
where you put markdown files in. Specify page
as
layout. You need to add a permalink
as well. The last thing is to add
include: ['_pages']
to your _config.yml
.
Updating the blog
That is merely a job of executing
JEKYLL_ENV=production bundle exec jekyll build -s from -d to
,
where from
is the path to the project root and to
is the path to the
directory, where the HTML should land.
I had to pass in the environment for some plugins to run. bundle
is used
because I encountered issues with sass (found in two places).
Keep on blogging!