Static blog with org-mode

Why?
How?
Current Solution

tl;dr: Full code for the impatient↓. Read the full blog post to have all the details.

This is the first article using my new blog system.

Once in a while, I create a new personal website. A long time ago, I used PHP for my first website. I used include and took care of XHTML pages validation. Then I used nanoc, a ruby static website generator. Then I switched to hakyll because I wanted to switch to a Haskell's written tool. Now I'll try to use org-mode directly with org-publish. I am became a quite extensive emacs user now. So using org-mode and org-publish is a bit like not having to install any 3rd party software.

Why?

Everything started when I was hired in a place where I was given a terrible keyboard. After a few weeks I started to feel a lot of pain in both my wrists. So I started to go from classical IDE to being able to use vim correctly¹.

Then I started to work in Clojure and I heard that emacs might certainly be a better fit for LISP dialiects. But, I couldn't switch to an editor without vim keybindings support because they are so great once you're used to them. By chance it was about the same time that spacemacs appeared and I switched. Is is really impressive how well the vim keybindings are supported. Even most of the advanced vim features I used to use worked like a charm.

The first benefit of emacs is you can configure emacs with elisp. Which unlike vimscript looks like a correct language to work with.

One unexpected benefit of emacs was org-mode. I always heard good things about it but it took me a while to really get it and to understand why it is so great.

If you don't know anything about org-mode, it is many things. First imagine a Markdown but more TODO list oriented. But along with this, emacs has a lot of helper functions to work with those org-mode files.

One real game changer is org-capture. You can add a task quite easily while doing other work in emacs.

How?

You can easily follow the org-mode doc to make your own website. But I have added a few "goodies".

attempt to obfuscate contact email,

Basic Blog

I put the need minimal code in a .project.el.gpg file of my blog repository. Inspired by this blog post I enhanced this version to be both more user friendly and secure (see Autoload Emacs Script by Project).

But even before that, I simply put the code in has an elisp code block of my index.org that I exectued with C-c C-c.

I have a code block in my index.org page that I do not export containing the elisp code I use to load all the information needed by org-publish. Do not export an org-mode subtree you can simply tag it with :noexport:.

org-publish suppose that you'll export one html page per org file. You need to provide a minimum set of information:

base directory that should contain your org files
publish directory, where you will export the html from the org files

A very basic publish rule would be:

* Magic Script                     :noexport:
#+begin_src elisp :results none
  (setq org-publish-project-alist
        '(("orgfiles"
           :base-directory "/users/me/blog/src"
           :publishing-directory "/users/me/blog/_site"
           :recursive t)))
#+end_src

So now, if you put org files in the base directory it will copy recursively the tree in that base directory and will copy it to the publishing directory exporting all org files to html files.

Nice.

If you are not familiar with emacs or orgmode, orgpublish. This block of code set the variable named org-publish-project-alist. The alist in the end is for "associative list".

☞ So when you'll execute the command org-publish in emacs. You will get prompted to enter the name of what to publish. You should see a single proposition named orgfiles. Once selected the export and publish will occurs. Notice, org-publish does what you expect and do not re-export all files each time but only the one that have changed.

Relative Paths

A first issue with this is that I don't want to put that in my emacs preferences. I would like to be able to publish my website for anyone that could clone my git repository. So I will use emacs projectile to find the root directory of the current project.

  (setq base-dir (concat (projectile-project-root) "src"))
  (setq publish-dir (concat (projectile-project-root) "_site"))
  (setq org-publish-project-alist
        `(("orgfiles"
           :base-directory ,base-dir
           :publishing-directory ,publish-dir
           :recursive t
           :base-extension "org")))

That's better. Now anyone can clone the repository. Open my index.org file, and execute the code in it by C-e C-e and then will be able to publish the website locally in the _site directory.

Assets

Generally you want a bit more features than that for publishing a blog. Typically you would like to have a common template, an header, some CSS.

For that you need to work a bit more. First, important thing, add an org publish section to publish your assets (CSS, images, etc…)

  (setq base-dir (concat (projectile-project-root) "src"))
  (setq publish-dir (concat (projectile-project-root) "_site"))
  (setq assets-dir (concat base-dir "/assets"))
  (setq publish-assets-dir (concat publish-dir "/assets"))
  (setq org-publish-project-alist
        `(("orgfiles"
           :base-directory ,base-dir
           :publishing-directory ,publish-dir
           :recursive t
           :base-extension "org"
           :exclude ".*drafts/.*")

          ("assets"
           :base-directory ,assets-dir
           :base-extension ".*"
           :publishing-directory ,publish-assets-dir
           :publishing-function org-publish-attachment
           :recursive t)

          ("blog" :components ("orgfiles" "assets"))))

With that you will copy the assets and export org file to html. You can do both by selecting `blog` when doing an `org-publish`.

That's better. But for a blog you also generally want to have your own CSS.

Current Solution

  ;; Global variables
  (setq domainname "https://her.esy.fun")
  (setq base-dir (concat (projectile-project-root) "src"))
  (setq publish-dir (concat (projectile-project-root) "_site"))
  (setq assets-dir (concat base-dir "/assets"))
  (setq publish-assets-dir (concat publish-dir "/assets"))
  (setq rss-dir base-dir)
  (setq publish-rss-dir publish-dir)
  (setq css-name "minimalist.css")
  (setq author-name "Yann Esposito")
  (setq author-email "yann.esposito@gmail.com")

  (require 'org)
  (require 'ox-publish)
  (require 'ox-html)
  (require 'org-element)
  (require 'ox-rss)

  (defun org-blog-prepare (project-plist)
    "With help from `https://github.com/howardabrams/dot-files'.
  Touch `index.org' to rebuilt it.
  Argument `PROJECT-PLIST' contains information about the current project."
    (let* ((base-directory (plist-get project-plist :base-directory))
           (buffer (find-file-noselect (expand-file-name "index.org" base-directory) t)))
      (with-current-buffer buffer
        (set-buffer-modified-p t)
        (save-buffer 0))))

  (defvar org-blog-head
    (concat
     "<link rel=\"stylesheet\" type=\"text/css\" href=\"/assets/css/" css-name "\"/>"
     "<meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">"
     "<link rel=\"alternative\" type=\"application/rss+xml\" title=\"Subscribe to articles\" href=\"/archives.xml\" />"
     "<link rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/assets/img/favicon.ico\">"))

  (defun menu (lst)
    "Blog menu"
    (concat
     "<navigation class=\"menu\">"
     (mapconcat 'identity
                (append
                 '("<a href=\"/index.html\">Home</a>"
                   "<a href=\"/archive.html\">Posts</a>")
                 lst)
                " | ")
     "</navigation>"))

  (defun str-time-to-year-float (date-str)
    (/ (float-time
        (apply 'encode-time
               (mapcar (lambda (x) (if (null x) 0 x))
                       (parse-time-string date-str))))
       (* 365.25 24 60 60)))

  (defvar blog-creation-date "2019-07-01")

  (defun delta-date (date-str)
    "Number of year since the begining of this blog"
    (let ((y (- (str-time-to-year-float date-str)
                (str-time-to-year-float blog-creation-date))))
      (format "∆t=%.2f" y)))

  (defun org-blog-preamble (info)
    "Pre-amble for whole blog."
    (concat
     "<div class=\"content\">"
     (menu '("<a href=\"#postamble\">↓ bottom ↓</a>"))
     "<h1>"
     (format "%s" (plist-get info :title))
     (when-let ((date (get-from-info info :date)))
       (format " - <span class=\"article-date\">%s</span>" date))
     "</h1>"
     "</div>"))

  (defun get-from-info (info k)
    (let ((i (car (plist-get info k))))
      (when (and i (stringp i))
        i)))

  (defun rand-obfs (c)
    (let ((r (% (random) 20)))
      (cond ((eq 0 r) (format "%c" c))
            ((< 0 r 10) (format "&#%d;" c))
            (t (format "&#x%X;" c)))))

  (defun obfuscate-html (txt)
    (apply 'concat
           (mapcar 'rand-obfs txt)))

  (defun org-blog-postamble (info)
    "Post-amble for whole blog."
    (concat
     "<div class=\"content\">"
     "<footer>"
     (when-let ((author (get-from-info info :author)))
       (if-let ((email (plist-get info :email)))
           (format "<div class=\"author\">Author: <a href=\"%s%s\">%s</a></div>"
                   (obfuscate-html "mailto:")
                   (obfuscate-html email)
                   (obfuscate-html author))
         (format "<div class=\"author\">Author: %s</div>" author)))
     (when-let ((date (get-from-info info :date)))
       (format "<div class=\"date\">Created: %s (%s)</div>" date (delta-date date)))
     (when-let ((keywords (plist-get info :keywords)))
       (format "<div class=\"keywords\">Keywords: <code>%s</code></div>" keywords))
     (format "<div class=\"date\">Generated: %s</div>"
             (format-time-string "%Y-%m-%d %H:%M:%S"))
     (format (concat "<div class=\"creator\"> Generated with "
                     "<a href=\"https://www.gnu.org/software/emacs/\" target=\"_blank\" rel=\"noopener noreferrer\">Emacs %s</a>, "
                     "<a href=\"http://spacemacs.org\" target=\"_blank\" rel=\"noopener noreferrer\">Spacemacs %s</a>, "
                     "<a href=\"http://orgmode.org\" target=\"_blank\" rel=\"noopener noreferrer\">Org Mode %s</a>"
                     "</div>")
             emacs-version spacemacs-version org-version)
     "</footer>"
     (menu '("<a href=\"#preamble\">↑ Top ↑</a>"))
     "</div>"))

  (defun org-blog-sitemap-format-entry (entry _style project)
    "Return string for each ENTRY in PROJECT."
    (when (s-starts-with-p "posts/" entry)
      (format "@@html:<span class=\"archive-item\"><span class=\"archive-date\">@@ %s: @@html:</span>@@ [[file:%s][%s]] @@html:</span>@@"
              (format-time-string "%Y-%m-%d"
                                  (org-publish-find-date entry project))
              entry
              (org-publish-find-title entry project))))

  (defun org-blog-sitemap-function (title list)
    "Return sitemap using TITLE and LIST returned by `org-blog-sitemap-format-entry'."
    (concat "#+TITLE: " title "\n"
            "#+AUTHOR: " author-name "\n"
            "#+EMAIL: " author-email "\n"
            "\n#+begin_archive\n"
            (mapconcat (lambda (li)
                         (format "@@html:<li>@@ %s @@html:</li>@@" (car li)))
                       (seq-filter #'car (cdr list))
                       "\n")
            "\n#+end_archive\n"))

  (setq org-publish-project-alist
        `(("orgfiles"
           :base-directory ,base-dir
           :exclude ".*drafts/.*"
           :base-extension "org"

           :publishing-directory ,publish-dir

           :recursive t
           :preparation-function org-blog-prepare
           :publishing-function org-html-publish-to-html

           :with-toc nil
           :with-title nil
           :with-date t
           :section-numbers nil
           :html-doctype "html5"
           :html-html5-fancy t
           :html-head-include-default-style nil
           :html-head-include-scripts nil
           :htmlized-source t
           :html-head-extra ,org-blog-head
           :html-preamble org-blog-preamble
           :html-postamble org-blog-postamble

           :auto-sitemap t
           :sitemap-filename "archive.org"
           :sitemap-title "Blog Posts"
           :sitemap-style list
           :sitemap-sort-files anti-chronologically
           :sitemap-format-entry org-blog-sitemap-format-entry
           :sitemap-function org-blog-sitemap-function)

          ("assets"
           :base-directory ,assets-dir
           :base-extension ".*"
           :publishing-directory ,publish-assets-dir
           :publishing-function org-publish-attachment
           :recursive t)

          ("rss"
           :base-directory ,rss-dir
           :base-extension "org"
           :html-link-home ,domainname
           :html-link-use-abs-url t
           :rss-extension "xml"
           :publishing-directory ,publish-rss-dir
           :publishing-function (org-rss-publish-to-rss)
           :exclude ".*"
           :include ("archive.org")
           :section-numbers nil
           :table-of-contents nil)

          ("blog" :components ("orgfiles" "assets" "rss"))))

  ;; add target=_blank and rel="noopener noreferrer" to all links by default
  (defun my-org-export-add-target-blank-to-http-links (text backend info)
    "Add target=\"_blank\" to external links."
    (when (and
           (org-export-derived-backend-p backend 'html)
           (string-match "href=\"http[^\"]+" text)
           (not (string-match "target=\"" text))
           (not (string-match (concat "href=\"" domainname "[^\"]*") text)))
      (string-match "<a " text)
      (replace-match "<a target=\"_blank\" rel=\"noopener noreferrer\" " nil nil text)))

  (add-to-list 'org-export-filter-link-functions
               'my-org-export-add-target-blank-to-http-links)

I wrote this article to help people use vim: learn vim progressively

15 KiB Raw Blame History