Blogging with EMACS Org mode with Org publishing

Org mode is for keeping notes, maintaining TODO lists, planning projects, and authoring documents with a fast and effective plain-text system.

It can be installed with M-x package-install RET org RET or with cloning from GIT with git clone https://code.orgmode.org/bzg/org-mode.git and adding it to the EMACS load path.

This post is not about Org mode, but the way to set it up for publishing sites with it. The Org manual is very extensive and easy to understand though.

It is integrated into my text editor, it is in the same software where I manage my projects and documents. What could be more convenient than using the same tool for handling todo lists, writing documentation and publish websites?

I would like to use a directory structure that I can keep in SCM, and hopefully use with Gitlab Pages. It must contain the "source code" and the exported HTML files as well. I want to collect posts by topic, and it must be reflected in the exported pages. Later on I want some kind of sulution for archiving old posts.

Considering the above circumstances I came up with the following directory structure:

.
├── css                                          # Design files for the exported data
│   └── style.css                                # First design file
├── posts                                        # Org files as posts under topic directories
│   ├── emacs                                    # A topic collector directory
│   │   └── blogging-with-emacs-orgmode.org      # A post in org file
│   └── index.org                                # A sitemap file called index
└── public                                       # The generated files for publishing reside here
    ├── css
    │   └── style.css
    ├── emacs
    │   └── blogging-with-emacs-orgmode.html
    └── index.html

Org publishing is configured through the org-publish-project-alist variable, and each element of the list configures one project.

My current publishing variable looks like this (as of <2020-03-08 Sun>):

(setq org-publish-project-alist
      '(("blog"
         :base-directory "~/stuff/projects/tmolnar0831.gitlab.io/posts"
         :publishing-directory "~/stuff/projects/tmolnar0831.gitlab.io/public"
         :publishing-function org-html-publish-to-html
         :recursive t
         :section-numbers nil
         :table-of-contents nil
         :with-toc nil
         :html-validation-link nil
         :html-link-home "/"
         :html-link-up "../"
         :html-head-include-default-style nil
         :html-head-include-scripts nil
         :html-home/up-format "<div id=\"org-div-home-and-up\"><a accesskey=\"H\" href=\"%s\">HOME</a></div>"
         :auto-sitemap t
         :sitemap-sort-files anti-chronologically
         :sitemap-title "Coffee and System Administration"
         :sitemap-filename "index.org"
         :sitemap-style list
         :author "Tamas Molnar"
         :email "tmolnar0831@gmail.com"
         :with-creator t
         :html-head "<link rel=\"stylesheet\" href=\"/css/style.css\" type=\"text/css\"/>"
         :html-preamble t)
        ("css"
          :base-directory "~/stuff/projects/tmolnar0831.gitlab.io/css"
          :base-extension "css"
          :publishing-directory "~/stuff/projects/tmolnar0831.gitlab.io/public/css"
          :publishing-function org-publish-attachment
          :recursive t)
        ("all" :components ("blog" "css"))))

The above code controls entirely the whole process. As my EMACS is running with the same configuration when I am at any of my computers, I can start and publish a post anywhere I have internet.

My solution may change in the future as I expriment with it a lot, but this current post is generated with it. I do not do any fancy configuration in the posts/*/*.org files, only giving them a #+title and that's it.

Finally I call the M-x org-publish-all function that will publish all projects.

I double check my post with changing directory to the public directory and using

python3 -m http.server

It fires up a local HTTP server on 127.0.0.1:8000.

When everything is fine, then I use Magit to commit it to SCM, and the CI handles the website creation.

You can visit my GitLab account if you have any questions.