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!