Hello, Org

Introduction

I've recently fallen in love with org-mode, specifically when I use it with org-roam. I find the whole workflow of creating, tagging, and - later on - searching for information on my computer to be very elegant. On top of that, now that I have the time, I want to begin writing blog posts to better work out my thoughts. With both of these things in mind, I am again turning to the universal tool for human prospering: org-mode. This time, I want to see how it can help me turn a simple org file into a blog post on my website. My requirements are:

Org files must get published to HTML files in a particular format with a preset stylesheet
Code blocks with code highlighting
Images must be supported
Posts must be timestamped with the creation date next to the title
Generate a high-level "directory" page with all of the posts by order of creation
Posts should be able to have tags that will be used to filter content

And that's pretty much it for now. Without further ado, let's jump into getting this up and running.

(Note: I will be heavily inspired by this post from System Crafters. I highly recommend that you read his post first before you follow my post, as he provides more details about the org-publish-project-alist command than I am willing to go into in this post.)

Basic HTML File

As a pilot, we are going to use this org file that I am currently writing (hello.org) as our guinea pig. The goal is to have this org file be our very first blog post.

Emacs ships with org export goodies out of the box via the ox-publish.el package (which you can find here). In our case, we will want to use this package to write a script that exports all the ./_posts/*.org files and outputs them to a corresponding ./posts/*.html. Leaning heavily on the System Crafters information, we can create a file called publish.el and write the following inside of it:

(require 'ox-publish)

(setq org-publish-project-alist
      (list
       (list "matthewkosarek.xyz"
             :recursive t
             :base-directory "./_posts"
             :publishing-directory "./posts"
             :publishing-function: 'org-html-publish-to-html)))

(org-publish-all t)
(message "Build Complete")

Next, in the same way that System Crafters made a shell script to execute this lisp, snippet, we can create a file called publish.sh and write the following inside of it:

#!/bin/sh
emacs -Q --script publish.el

We then do a chmod +x publish.sh to make it an executable and run it with ./publish.sh. If everything went according to plan, we should see a new file at posts/hello.html.

Disabling features that we don't want

The next thing will be to remove some of the generated items that I didn't ask for, namely the table of contents, author, section numbers, creation time stamp, and the validation link.

(require 'ox-publish)

(setq org-publish-project-alist
      (list
       (list "matthewkosarek.xyz"
             :recursive t
             :base-directory "./_posts"
             :publishing-directory "./posts"
             :publishing-function: 'org-html-publish-to-html
             :with-toc nil        ; Disable table of contents
             :with-author nil     ; Disable author
             :section-numbers nil ; Disable section numbers
             :time-stamp-file)))  ; Disable timestamp

(setq org-html-validation-link nil) ; Disable the validation link at the bottom

(org-publish-all t)
(message "Build Complete")

Styling & Code Highlighting

Next thing on our list is custom styling. This can be achieved by first installing the htmlize package from melpa / elpa. The EmacsWiki describes this as "a package for exporting the contents of an Emacs buffer to HTML while respecting display properties such as colors, fonts, underlining, invisibility, etc" (reference). If used "out-of-the-box", the buffer will be exported to HTML with all of the styles inlined (e.g. if you underline something in your org file, you will generate a <span style="text-decoration: underline">...</span>). However, we are more interested in styling everything by ourselves: we don't want htmlize making assumptions about what underlining means to us! Luckily, htmlize gives us the option to export with class names instead of inline styles so that we can specify each style for ourselves.

(require 'ox-publish)

;; First, we need to setup our publish.el file to hook up to melpa/elpa so that we can ensure
;; htmlize is installed before we begin publishing.
(require 'package)
(setq package-user-dir (expand-file-name "./.packages"))
(setq package-archives '(("melpa" . "https://melpa.org/packages/")
                         ("elpa" . "https://elpa.gnu.org/packages/")))

;; Initialize the package system
(package-initialize)
(unless package-archive-contents
  (package-refresh-contents))

;; Install dependencies
(package-install 'htmlize)

(setq org-publish-project-alist
      (list
       (list "matthewkosarek.xyz"
             :recursive t
             :base-directory "./_posts"
             :publishing-directory "./posts"
             :publishing-function: 'org-html-publish-to-html
             :with-toc nil
             :with-author nil
             :section-numbers nil
             :time-stamp-file nil)))

(setq org-html-htmlize-output-type 'css)       ;; Output classnames in the HTML instead of inline CSS
(setq org-html-htmlize-font-prefix "org-")     ;; Prefix all class names with "org-"

(setq org-html-validation-link nil
      org-html-head-include-scripts nil        ;; Removes any scripts that were included by default
      org-html-head-include-default-style nil) ;; Removes any styles that were included by default

(org-publish-all t)

(message "Build Complete")

If you run publish.sh and open the HTML page now, you will see that zero styling has been applied to the page. However, if you inspect an element in your browser that you suspect should have styling (like our underlined element from before), you will see that it has a class name instead of inline styles.

Now that our generated elements have class names, we can define the style for each relevant class name. In my case, I want to include both the index.css file that my entire website defines (you can find that here) so that there are some standard styles across the site. These standard styles include the font that should be used, the spacing around the body tag, the link styles, and other generic goodies. On top of that, we will want a custom stylesheet specifically for "post" files. In my case, I have defined the following in posts/post.css:

pre {
    background-color: #FEFEFE;
    border: 1px solid #D5D5D5;
    border-radius: 2px;
    padding: 1rem;
}

code {
    font-family: "Consolas" sans-serif;
    color: #D0372D;
}

.underline {
    text-decoration: underline;
}

/* Taken from: https://emacs.stackexchange.com/questions/7629/the-syntax-highlight-and-indentation-of-source-code-block-in-exported-html-file */
pre span.org-builtin                     {color:#006FE0;font-weight:bold;}
pre span.org-string                      {color:#008000;}
pre span.org-keyword                     {color:#0000FF;}
pre span.org-variable-name               {color:#BA36A5;}
pre span.org-function-name               {color:#006699;}
pre span.org-type                        {color:#6434A3;}
pre span.org-preprocessor                {color:#808080;font-weight:bold;}
pre span.org-constant                    {color:#D0372D;}
pre span.org-comment-delimiter           {color:#8D8D84;}
pre span.org-comment                     {color:#8D8D84;font-style:italic}
1pre span.org-outshine-level-1           {color:#8D8D84;font-style:italic}
pre span.org-outshine-level-2            {color:#8D8D84;font-style:italic}
pre span.org-outshine-level-3            {color:#8D8D84;font-style:italic}
pre span.org-outshine-level-4            {color:#8D8D84;font-style:italic}
pre span.org-outshine-level-5            {color:#8D8D84;font-style:italic}
pre span.org-outshine-level-6            {color:#8D8D84;font-style:italic}
pre span.org-outshine-level-7            {color:#8D8D84;font-style:italic}
pre span.org-outshine-level-8            {color:#8D8D84;font-style:italic}
pre span.org-outshine-level-9            {color:#8D8D84;font-style:italic}
pre span.org-rainbow-delimiters-depth-1  {color:#707183;}
pre span.org-rainbow-delimiters-depth-2  {color:#7388d6;}
pre span.org-rainbow-delimiters-depth-3  {color:#909183;}
pre span.org-rainbow-delimiters-depth-4  {color:#709870;}
pre span.org-rainbow-delimiters-depth-5  {color:#907373;}
pre span.org-rainbow-delimiters-depth-6  {color:#6276ba;}
pre span.org-rainbow-delimiters-depth-7  {color:#858580;}
pre span.org-rainbow-delimiters-depth-8  {color:#80a880;}
pre span.org-rainbow-delimiters-depth-9  {color:#887070;}
pre span.org-sh-quoted-exec              {color:#FF1493;}
pre span.org-css-selector                {color:#0000FF;}
pre span.org-css-property                {color:#00AA00;}

That CSS file should get you going with some decent code highlighting and styles, but I don't pretend that it is complete.

Finally, we need to tell org mode to include our two CSS files when the page is loaded. To do this, we can use the HTML <link> entity. We will set the org-html-head variable to insert two link entities at the top of the page.

(require 'ox-publish)

(require 'package)
(setq package-user-dir (expand-file-name "./.packages"))
(setq package-archives '(("melpa" . "https://melpa.org/packages/")
                         ("elpa" . "https://elpa.gnu.org/packages/")))

;; Initialize the package system
(package-initialize)
(unless package-archive-contents
  (package-refresh-contents))

;; Install dependencies
(package-install 'htmlize)

(setq org-publish-project-alist
      (list
       (list "matthewkosarek.xyz"
             :recursive t
             :base-directory "./_posts"
             :publishing-directory "./posts"
             :publishing-function: 'org-html-publish-to-html
             :with-toc nil
             :with-author nil
             :section-numbers nil
             :time-stamp-file nil)))

(setq org-html-htmlize-output-type 'css)
(setq org-html-htmlize-font-prefix "org-")

(setq org-html-validation-link nil
      org-html-head-include-scripts nil      
      org-html-head-include-default-style nil
      org-html-head "
  <link rel=\"stylesheet\" href=\"/index.css\" />
  <link rel=\"stylesheet\" href=\"/posts/post.css\" />
  <link rel=\"shortcut icon\" href=\"/favicon/favicon.ico\" type=\"image/x-icon\">
  ")                                                   ;; Include index.css and posts/post.css when the page loads
                                                       ;; Note that I also set the "favicon" too, but this is optional

(org-publish-all t)

(message "Build Complete")

If we run the publish again, we can see that we have full styling on our code snippets and everything else on our website.

Images

Our first two criteria have been met! Next on the list is solving images. As an example, let's use this squirrel image that I found online with an open source license. The ideal situation would be:

The squirrel image lives closely to this org document (hello.org)
We can reference the image file in our org file, and see it in our HTML page as an image

Unfortunately, it doesn't look to be that easy. Let's examine the ideal situation. Let's say we provide a relative path to an image in our org file like so:

[[./assets/squirrel.jpg]]

If we click this link in our org buffer, the relative path will work right away. However, when we export the org file to HTML, the following tag will be generated:

<img src="./assets/squirrel.jpg" alt="squirrel.jpg">

The browser cannot resolve this absolute path, which results in the alternate "squirrel.jpg" text being shown next to a broken image.

So what's the fix here? Well, we have two options, but I am going to go with the easiest. For more information, check out this stackoverflow post. The route I chose puts the onus of making a proper link on the writer of the blog post. The fix simply modifies the src attribute of the generated HTML to have an absolute path to the image, while also allowing the org file to retain a link to the image that it understands.

#+ATTR_HTML: :src /_posts/assets/squirrel.jpg
[[./assets/squirrel.jpg]]

That's all there is to it! There are simpler ways as well, but that should do it:

Figure 1: A Cute Squirrel

Creation Date

Let's add the creation date below the title next. To start, we will modify the publish command to remove the title (:with-title nil) and, in its place, show a preamble bit of HTML that contains a formatted div with the title and the "last modified" span.z

(setq org-publish-project-alist
      (list
       (list "matthewkosarek.xyz"
             :recursive t
             :base-directory "./_posts"
             :publishing-directory "./posts"
             :publishing-function: 'org-html-publish-to-html
             :with-toc nil
             :with-author nil
             :section-numbers nil
             :time-stamp-file nil
             :with-title nil
             :html-preamble-format '(("en" "
  <div class=\"org-article-title\">
    <h1>%t</h1>
    <span>Last modified: %d</span>
  </div>
"))

The html-preamble-format variable takes an association list (alist) as a parameter. Each entry in the alist should have the export language (in this case english or "en") as the first value and the format for that language as the second value.

The "%t" in the HTML string will be filled in with the title of your post. This is set by the #+TITLE: MY_TITLE attribute of your org file. In this case, that is "Hello, Org". The "%d" is used to insert the date of your post. This is set by the #+DATE: <ORG_TIMESTAMP> in your org file. You can insert a timestamp into the buffer by writing M-x org-time-stamp, or by typing one out yourself. (Hint: You can do an M-x describe-variable and type "org-html-preamble-format" to get more info on what "%X" values you can include in this format).

On top of this, we can modify our posts/post.css file to make the title a bit more pleasing to the eyes.

.org-article-title > h1 {
    margin-bottom: 0;
}

.org-article-title > span {
    color: #707183;
}

If you want to see the full list of which values can be included in the html-preamble-format, you can do an M-x describe-variable on the org-html-preamble-format variable.

Note that the downside of this is that the created date will change whenever you next save the buffer. This isn't a huge deal for my purposes, but you may need to come up with a more sophisticated mechanism for the exact "creation" date for your use case.

Generating the Directory

For every org file in my _posts folder, I would like to create a link to the generated HTML file at the /posts.html page of my website. You can think of this as the "directory" of all posts. My criteria is:

Posts should appear in order from newest to oldest
Posts should be searchable by tags (covered in the next section)
Posts should be searchable by title

The "out-of-the-box" mechanism for accomplishing this is the sitemap. You can think of a sitemap as a directory of sorts. While sitemaps can grow to be infinitely deep (i.e. sitemaps referencing other sitemaps), we will keep our sitemap as a flat list containing the available posts in chronological order.

To start, we can enable source maps for our publish like so:

(setq org-publish-project-alist
      (list
       (list "matthewkosarek.xyz"
             :recursive t
             :base-directory "./_posts"
             :publishing-directory "./posts"
             :publishing-function: 'org-html-publish-to-html
             :with-toc nil
             :with-author nil
             :section-numbers nil
             :time-stamp-file nil
             :with-title nil
             :html-preamble-format '(("en" "
  <div class=\"org-article-title\">
    <h1>%t</h1>
    <span>Last modified: %d</span>
  </div>
"))
             :auto-sitemap t                           ; Enable the sitemap
             :sitemap-sort-files "chronologically"     ; Sort files chronologically
             :sitemap-format-entry (lambda (entry style project) (get-org-file-title entry style project))
             )))

If we generate again, we will find two files generated:

_posts/sitemap.org: The org file containing the generated sitemap
posts/sitemap.html: The HTML file that was generated based on the previous sitemap.org file

If you open the sitemap.html file in your browser, you will see a bulleted listed containing a link to "Hello, Org". Clicking on it will bring you to this blog post.

From here, you may customize it however you like. The following are my customizations.

Sitemap Title

I changed the title to "Matthew's Blog Posts".

(defun get-org-file-title(entry style project)
  (setq  timestamp (org-timestamp-format (car (org-publish-find-property entry :date project)) "%B %d, %Y"))
  (format "%s created on %s" (org-publish-sitemap-default-entry entry style project) timestamp)
  )

(setq org-publish-project-alist
      (list
       (list "matthewkosarek.xyz"
             ...
             :sitemap-title "Matthew's Blog Posts"  ; Change the title
             )))

Format blog entries in the list

I like to include the creation date on the blog posts. To do this, we can use org-publish-find-property to find the date property of the org file. Afterward, we can format a string that includes our formatted timestamp and the org-publish-sitemap-default-entry, which is just a link with the title of the post.

(defun get-org-file-title(entry style project)
  (setq  timestamp (org-timestamp-format (car (org-publish-find-property entry :date project)) "%B %d, %Y"))
  (format "%s created on %s" (org-publish-sitemap-default-entry entry style project) timestamp)
  )

(setq org-publish-project-alist
      (list
       (list "matthewkosarek.xyz"
             ...
             :sitemap-format-entry (lambda (entry style project) (get-org-file-title entry style project))
             )))

Tags & Filtering

I use Org-roam for all of my note-taking and, in the next blog post, I plan to demonstrate how I will hook up my Org-roam note-taking workflow to my blogging. In the meantime, just know that we can add tags to the top of our org files like this:

#+filetags: :tag_1:tag_2:

This would tag this org buffer with "tag₁" and "tag₂".

Our criteria for the tag filtering system is:

A post can contain many tags
Users can filter my one or many tags (i.e. "home" and "technology" but not "lifestyle")
By default, users see all posts with all tags
Searching happens on the client

Let's modify the get-org-file-title function that we wrote in the previous section to parse and include these tags:

(defun get-org-file-title(entry style project)
  (setq timestamp (org-timestamp-format (car (org-publish-find-property entry :date project)) "%B %d, %Y"))
  (setq tag-list (org-publish-find-property entry :filetags project))
  (setq tag-list-str (mapconcat 'identity tag-list ","))
  (setq result (format "%s created on %s\n#+begin_sitemap_tag\n%s\n#+end_sitemap_tag\n" (org-publish-sitemap-default-entry entry style project) timestamp tag-list-str))
  )

We extract the "filetags" from the org file, concatenate them into a comma-delimited string, and format them into the title string. We place the contents inside of a begin_sitemap_tag and end_sitemap_tag block. In HTML, this creates an enclosing div element with the class name "sitemap_tag". That means we can target the .sitemap_tag element in CSS. In our case, we want to hide all of that data entirely so we can put the following in posts/post.css:

.sitemap_tag {
    display: none;
}

If you rerun the publish.sh script now, you will see the tags only if you inspect the element, but they will not appear visually.

Next thing is to write a small snippet of JavaScript that our page will load. This snippet is responsible for:

Creating a list of the used tags
Creating enable/disable buttons for each tag
Hiding/showing a post depending on the state of its tags

We create a new file called posts/post.js and put the following inside:

function main() {

  // Gather the used set oof tags
  const tagSet = new Set();
  const postList = [];
  const tagContainers = document.getElementsByClassName('sitemap_tag');
  for (let index = 0; index < tagContainers.length; index++) {
    const container = tagContainers[index];
    const pContainer = container.children[0];
    if (!pContainer) {
      continue;
    }

    const tagList = pContainer.textContent.split(',');
    tagList.forEach(tag => tagSet.add(tag));
    postList.push({
      container: container.parentElement,
      tagList: tagList,
      enabled: tagList.length
    });
  }

  // Create the tag container
  const contentContainer = document.getElementById('content');
  const tagContainer = document.createElement('div');
  tagContainer.id = 'tag-filter-container';
  contentContainer.before(tagContainer);

  let numEnabled = tagSet.size;
  for (const tag of tagSet) {
    const tagElement = document.createElement('div');
    tagElement.className = "tag-filter-item";
    const tagElementLabel = document.createElement('span');
    tagElementLabel.innerHTML = tag;
    const tagElementButton = document.createElement('button');
    tagElement.append(tagElementLabel, tagElementButton);
    tagContainer.append(tagElement);


    // Whenever a tag is clicked, execute the filtering behavior
    tagElementButton.onclick = function() {
      // Handle enable/disable
      tagElement.remove();

      if (tagElement.classList.contains('disabled')) {
        tagElement.classList.remove('disabled');
        if (numEnabled === 0) {
          tagContainer.prepend(tagElement);
        }
        else {
          tagContainer.children[numEnabled - 1].after(tagElement);
        }
        numEnabled++;

        // Filter
        postList.forEach(post => {
          if (post.tagList.includes(tag)) {
            post.enabled++;

            if (post.enabled) {
              post.container.style.display = 'list-item';
            }
          }
        });
      }
      else {
        tagElement.classList.add('disabled');
        tagContainer.append(tagElement);
        numEnabled--;

        // Filter
        postList.forEach(post => {
          if (post.tagList.includes(tag)) {
            post.enabled--;
            if (!post.enabled) {
              post.container.style.display = 'none';
            }
          }
        });
      }

      // Filter
    };
  }
}

window.onload = main;

Finally, we can modify the org-html-head to include <script src='/posts/post.js'></script> so that this script is loaded on every blog post page.