Org-mode was originally created to take notes and organizing assignments with Emacs. Today, however, it's used to get things done, clock tasks, manage pomodoros and Jira issues and (why not?!) write blog posts with it.

All of these features are written using org syntax, which can be considered a markup language. For blogging purposes, org-mode gives us a pandoc-like experience and can export its files to the most used formats, like html, PDF and even Markdown, inside Emacs.

To publish a blog, we have to convert the org-mode files to html files of all of our posts.

In short, we gotta go from this:

To this:

The builtin way to do that is to simply assign a variable called org-publish-project-alist with an alist containing the following information:

(setq org-publish-project-alist
  `(("org-files"
     ;; ommited other configurations for brevity
     :base-directory "~/blog/org/"
     :base-extension "org"
     :recursive t
     :publishing-directory "~/blog/_posts/"
     :publishing-function org-html-publish-to-html)
    ("static-files"
     :base-directory "~/blog/org/"
     :base-extension "png\\|jpg"
     :publishing-directory "~/blog/res/"
     :recursive t
     :publishing-function org-publish-attachment)
    ("blog" :components ("org-files" "static-files"))))

After this variable is loaded, we can call the command M-x org-publish, then the prompt will let you choose among three values: blog, org-files and static-files.

When we select the org-files value, for example, org-mode will search recursively for files with the .org extension (base-extension) in ~/blog/org folder (base-directory), perform the conversion of org to html with the function org-html-publish-to-html (publishing-function) and, lastly, copy the resulting file in ~/blog/_posts (publishing-directory). The same idea applies to static-files, but, in this case, it'll copy the .png and .jpg files without any modification to ~/blog/res. The blog option will perform these two actions automatically.

A cool feature is that the publishing-function will determine how org-mode will export your content. If, instead of org-html-publish-to-html, we had specified org-beamer-publish-to-pdf, our org files would be converted to a beamer presentation.

This is a programming blog, so the way that code snippets are presented here is really important. There are tons of methods of displaying code in a blog: with Javascript, Ruby or Github gist.

But, with org-mode, there's a better way to highlight this code. With the htmlize package and org-mode itself, it's possible to take a "snapshot" of the Emacs appearance and translate it to the browser.

Basically, htmlize converts all existing Emacs faces into CSS properties. Emacs faces are graphical attributes responsible for the presentation of a text, i.e, they are the how text is presented to the user in Emacs.

To make it clearer, I'll try to give a small example of how this process works. Based on the movie The Shining and the iconic scene which Jack Nicholson loses his mind and breaks down a door with an axe, every time the word "Axe" appears, it will be highlighted in white and red. This is a silly example, but the idea is to show a small and practical example of how the conversion between faces to CSS happens. A particular context was chosen, but that's exactly the same concept used to highlight brackets, parentheses, keywords and comments.

You can host your blog here with any static website generator that you want as long as it is black Jekyll – Github Pages

After the html files are ready with your juicy content, you need a place to host it. A popular option is to host it in Github Pages; however, a major drawback is that you can only use Jekyll and, to make it worse, they limit you with only a collection of plugins.

This is where Gitlab Pages really shines. Because of its unique way to tie the blog generation with their continuous integration process (Gitlab CI), you have the flexibility and freedom to choose any library or framework that you desire to host your blog. It's possible to build your site with Hugo, hexo, middleman or insert your prefered static site generator.

Fundamentally, Gitlab CI uses the file .gitlab-ci.yml to configure the tasks of the project. With it, you choose the docker images in which your job will run, install the packages required for the blog generation and invoke the necessary commands to generate your static site. As an example, the .gitlab-ci.yml of this blog is similar to this:

Beyond the freedom that Gitlab CI gives to you, Gitlab Pages also supports HTTPs for custom domains. With Let's Encrypt you can semi-automate the process of certificate renewal manually or with Jekyll. In the future, maybe we won't need to do this since there's an open issue to automate this part of the process.

If this process is too manual and if you trust Cloudflare owning your keys, a fire and forget option is to let Cloudflare manage your certificates. However, if you choose this path, remember to always choose the full strict mode. Not to mention that it's always nice to use a CDN to improve the performance and reliability of a website.

And, for SEO reasons, we can redirect naked domains to www or vice-versa and to force the use of HTTPS with Cloudflare Page Rules feature. Don't worry about the price because these options are all available in the free tier.

In this article, I tried to talk a little about this blog setup and the process of creating it. Without spending a dime, you can have a professional website with any static site generator and use the awesome functionalities of org-mode and Emacs.

Also, you are not tied to use Gitlab Pages only for blogging. Any static site, like a resume exported to LaTeX or a presentation exported to PDF, can use the same principles presented here.

If you wanna try it out, fork the project that hosts this lame blog.