Generative art and procedural generation (or procgen) can be as simple or as complex as you want. Generative art is created with the help of an autonomous system, while procedural generation uses algorithms–and often randomness–to produce content.

The results can be predictable or chaotic. What makes a creation “procedural”? There are two criteria, it usually meets at least one of two criteria: the use of algorithm, and the use of randomness.

Random Walks

The random walk, also known as the drunkard’s walk, may be the simplest form of procedural randomness. It can be generated in any number of dimensions, but in this post I will demonstrating it within a 2D surface.

Imagine you find yourself in the middle of a grid of paths. There are sidewalks going east and west, and others going north and south. They are all evenly spaced apart. You are at a crossroads within this grid. You can go in one of four directions.

In a random walk, you would choose a direction at random to walk, and walk in that direction until the next crossroads. And then you would again choose a direction at random, and walk in that direction until you reached the next crossroads – and so on. Each new step is chosen independently of the previous steps.

In my own version, I decided to place a pixel on the canvas at 10% opacity. The position of the next pixel (again at 10% opacity) placed was randomly selected from four possibilities – either directly above, below, left, or right of the one before it. I repeated this process step by step.

What this pattern ends up generating resembles a topographic map. Areas that have been retread multiple times appear darker, while other unexplored areas remain completely white. Over time, more and more of the canvas is filled with color, but the longer it goes, the longer it takes to fill.

The pattern can be adjusted in clever ways to generate a variety of effects. By limiting the direction in one dimension – for example, allowing travel up, down, on forward, but not backward – you can generate a lightning effect like this one. And if you connect the last step to the first with a straight line, you can create geometric shapes resembling buildings.¹

Cellular Automata (Conway’s Game of Life)

A cellular automaton is a visual iterating pattern that uses a grid (of any dimension) consisting of cells. A cell has a certain state, such as on or off, or alive or dead. With each iteration, each cell’s state updates according to the state of its neighbors.

The most famous cellular automaton is John Conway’s “Game of Life”. In this pattern, each cell in a 2D grid has an initial state of “alive” or “dead”. The cells’ states are updated in each iteration according to these rules:

1. An “alive” cell with fewer than two “alive” neighbors (neighbors can border a cell horizontally, vertically, or diagonally) will become “dead” (the “underpopulation” rule).
2. An “alive” cell with 2-3 “alive” neighbors will stay alive.
3. An “alive” cell with more than 3 “alive” neigbhors will become dead (the “overpopulation” rule)
4. A dead cell with exactly 3 “alive” neighbors will become “alive” (the “reproduction” rule).

The initial pattern (or seed) can be set manually or, as I’ve done below, set randomly.

To me, the most interesting thing about this pattern isn’t the illustrations it produces, but how it creates a timelapse that can tell a story of epic scale. Notice how every now and then you’ll have a space of four cells, two on top and two on bottom, that have been stable and alive for several generations, only to be undone by a much larger encroaching pattern venturing from several grid spaces away.

Eventually, most seeds in the Game of Life will settle in to an infinite holding pattern or loop, but some go on forever.

The algorithm itself is simple to implement, and there are options to play around with when it comes to visual customization. You can stack each generation on top of its predecessors to create a 3D structure. You can play around with color or go with an isometric design.²

Recursive Backtracker Maze Generation

Now, it’s time to put randomness and algorithmic patterns together. There are several generative patterns that make use of both.

As an example, I made this spinning hexagon grid by changing the range of the random values determining the speed at which a particular hexagon spins and grows. The closer a hexagon is to the center of the grid, the higher its potential speed.

The spinning hexagon grid can be described as a “noise-like”³ generative pattern.

Another pattern type that uses “algorithmic randomness” is maze generation – which is exactly what the name suggests. There are several maze generation algorithms out there. The one I went with below is the recursive backtracker method (or the randomized depth-first search method). This method, which implements that random walk pattern shown earlier, creates a grid and tracks the state of each cell as “visited” and “unvisited”.

Here’s how it works:

1. Start with a grid of cells, like in our cellular automaton generation. To start, each cell has four walls (north, east, south, and west). All cells are “unvisited”.
2. Pick a random starting cell and mark it as “visited”.
3. While there are still “unvisited” cells:
   1. From the current cell, if there are any unvisited neighbors:
      1. Randomly choose an unvisited neighbor.
      2. Remove the wall between the current cell and the neighbor.
      3. Mark the neighbor as the current cell, mark it as visited, and add the previous cell to an array called a “stack” to track the movement.
   2. If the current cell has no unvisited neighbors:
      1. Remove the last cell visited from the stack, and go back to that cell, and repeat the process again.
   3. If the “stack” is empty, all cells have been visited and the loop can be exited. The process is complete.

And this is the result:

Once the maze is complete, you can choose any two points on the grid as your “entrance” and “exit”. There will be exactly one path between them.

As always, there are several adjustments one can make to a maze generation. Instead of using squares as cells, you could use hexagons. You may try to creative a visualization of your path.⁴

Some other neat patterns

• Sierpinski Triangle
• Tree branching
• Mandelbrot set
• Golden ratio
• Kaleidoscope
• Bauhaus

Recommended Reading

• On Generative Algorithms inconvergent (Anders Hoff)
• Generative Artistry Ruth John and Tim Holman
• Visualizing Algorithms Mike Bostock

Footnotes

So now I’m going again, this time using Jekyll. Jekyll was an easy choice. I’m familiar with the platform (my knowledge database, megan-zk, is written with Jekyll), it’s got a wide user base and extensive documentation, and it’s flexible enough that it can be custommized to just about any purpose.

Mostly, though: Jekyll is easy and quick. My experience with maintaining my blog using org-mode taught me the importance of choosing a platform that allowed me to focus on the important things.

So, was the org blogging experiment a failure?

Short answer: No.

Long answer: No. My org-mode blog, Meg in Progress, was a learning experiment. That was what I had intended for it to be, and to that end, it was successful.

And look, there’s nothing wrong with using org-mode as a blogging engine. Plenty of people have made it work for them. And clearly, once I had gotten it up and running, it was working for me – at least for the four posts I published to Meg in Progress between August 2020 and March 2021.

When I decided to get back to blogging earlier this month, I wanted to use org again. The first thing I did was attempt to revamp the site as a whole, and I quickly ran into issues.

To start, org’s HTML export options are highly configurable, but I found it to be incredibly troublesome to manipulate the top-level HTML files so that my custom elements would be inserted exactly how and where I needed to be on the page.

I wanted to add a footer element to the site. This footer would appear at the bottom of each page on the site. I used the HTML export option org-html-postamble to achieve this.

The problem was that I wanted the footer to be inside the main <div id=content> which included the actual post (or page) content.

This is how I wanted it to look:

<div id="content">
  <div class="header_containter">
    <div class="header">Meg in Progress</div>
    <div class="nav">
      <a class="navlink">about</a>
      <a class="navlink">archives</a>
      <a class="navlink">tags</a>
      <a class="navlink">home</a>
    </div>
  </div>
  <div class="post_header">
    <div class="post_title">An example title</div>
    <div class="post_date">XX/XX/XXXX</div>
    <div class="post_tags">
      <a class="taglink">tag</a>
      <a class="taglink">another</a>
    </div>
  </div>
  <div class="post_content">
    ...post...
  </div>
  <div class="footnotes">
    ...footnote section...
  </div>
  <div class="footer">
    Custom footer / org postamble element
  </div>
</div>

Notice how the content container isn’t closed until after the footer is inserted, but the footer is not contained in any other element.

At first, instead of the postamble, I used a custom include block to export the footer. But when I included the footer at the end of each page and post exported, it ended up like this:

<div id="content">
... post content here...
  <div class="footnotes">
  ... some footnotes ...
    <div class="footer">
      footer here
    </div>
  </div>
</div>

The footer was being inside the last element/section of each post, rather than on its own within the top-level container.

I thought using the postamble export option would fix this. Instead, this was the result:

<div id="content">
  ... post content here ....
</div>
<div class="postamble">
  footer here
</div>

This time, the footer ended up outside the content container, which wasn’t what I wanted at all. The idea was that all the content that would appear on each page would within a parent container, in which I could use CSS display: flex to easily align and justify the elements within that box.

I understand that I could tinker with the export options via trial and error to figure out how to make it work. I could remove the parent container altogether, and apply display: flex to the <body> element. I could use the org-html-preamble option to create my custom header, rather than an import statement, so both the footer and the header would be positioned outside the container. My issue was not that org-mode didn’t allow me to do what I wanted.

The issue was that the time and effort it took to get it right subtracted from the time I had available to actually write. Creating substantive content is the entire purpose of keeping a blog in the first place.

Another issue was that it was backwards enforcement of any the textual format of certain template elements. I used ya-snippets to create templates, and once a snippet was created, the content of that snippet was not dynamic.

Just take a look at how the first three posts I wrote for Meg in Progress appear on the index page:

What the Latest Impreachment Trial Says about the Current State of US Politics

02/27/21 Sat
On the weekend before Last, the US Senate concluded the second impeachment trial of former president Donald Trump, who had been impeached for inciting the insurrection at the US Capitol on January 6.. Read more…
politics

Blogging with Org Mode: An Update

Saturday, August 22, 2020
In my last post, I went over how I set up this blog solely in org-mode. And since that post has been published, I’ve made a few more changes to the configuration and so, in an effort to provide the most up to date information, I figured I’d write a little addendum. Read more…
dev

How I built a simply static blog with org-mode || 08/11/20 Tue

dev There’s always something new to discover with emacs and org-mode, and building a blog was my way of wading into deeper waters - no longer content to just get my feet wet. Read more…

As you can see, it’s a mess of inconsistency. Changes made to the snippet don’t update the snippets that have already been applied. If I want to make a formatting change that will apply across all entries, including past entries, I would have to manually go back and change each post. Perhaps in time I could have figured out a solution, which brings me back to the previous point: it’s time I’m saving by moving to Jekyll.

More blogging, less troubleshooting

As a developer, I’m all too familiar with the process of constantly adapting and fixing your code when it breaks or throws out results you didn’t expect. I know that, with a blog created with a static site generator, some technical fine-tuning will always be necessary.

As a blogging platform, Jekyll makes life a lot easier by offering several tools for the technical process:

• Templates and includes allow you complete control over the HTML. Everything on each page and post is laid out exactly like I set it up. I can update styles without getting unexpected results.
• YAML frontmatter and data files used alongside the Liquid templating language keep pages and posts formatted consistently across the site.
• Extensive documentation and a huge userbase means that there are numerous resources available for any updates I want to make or any technical issues I may be having.
• A stockpile of available themes and plugins can help to instantly implement new features to a site.
• It is incredibly simple and fast to get up and running, even without a theme, and you can easily integrate your own CSS and javascript files.
• Painless deployment to the back-end platform of your choice. This blog uses Netlify which builds the site each time I push a new commit to this blog’s Github repository.

This is not to say that Jekyll offers every single thing I wanted right out of the box. While its builds the site from source, convering markdown (.md) files to HTML, Jekyll doesn’t create new pages from scratch. This means that I have to create monthly archive pages and tag pages myself whenever I create the first post in a particular month or use a tag for the first time. What I don’t need to do, though, is update those pages each time I make a new post. Archive lists are created programmatically through the liquid templates. Every post with the tag “jekyll” will show up in the tag page for jekyll, provided the page exists. Every post from June 2025 will show up in the corresponding June 2025 archive page – again, provided the page exists. The markdown source for these tag and archive pages is completely empty except for two lines of YAML frontmatter:

---
title: 
layout: 
---

The layout is the file in the source _layouts folder that serves as the HTML template for the page, and the title is used to pull all posts with that tag or from that month.

There is a plugin for a simpler implementation of tags. I could also write a script in Python that would generate pages for me. I may do this in the future. However, it’s hardly any trouble to manually add a new page with the required frontmatter whenever I need to–and that way I don’t have to worry about any additional scripts or plugins breaking. It keeps things light-weight.

What next?

I plan to keep contributing to this blog, and making changes as I go along. I don’t really have any major plans for the blog itself for the time being. I had considered adding a comment system, but I don’t have the readership for that right now.

I see this site as a way to share information about various projects I’m working on and the things I’m learning. I want to focus primarily on publishing good, substantive content worth reading.

Comments

I wanted to add a comments section to entries. I really didn’t want to put much effort into this…just a simple box to respond to posts. It turned out that utterances provided me with something that was easy to set up and visually appealing. The only issue is that in order to comment, you have to be signed in to github. Since my site is hosted on github pages, though, this seems like an okay compromise.

I chose utterances because each comment section will be self-hosted on this site’s repo, it was simple to set up, and while people have to log in to leave comments, I preferred that to allowing “guest” comments. Since internet comment sections have a reputation for being toxic hell-scapes, I wanted to ensure commenters have a stake in what they say. As much as I am an advocate for free speech, I don’t want to provide a platform where people are enabled to evade responsibility for what they say.

Facebook comments was out because I am not going to force people to use their real names to comment. Disqus would be the obvious choice, or any number of third-party systems. I wasn’t inclined to go down that road, mostly because of privacy issues. I don’t want data gathered from user comments on my site to be sold by a third party to advertisers. If I expect commenters on my posts to take responsibility for their words, I have a responsibility to ensure an open discussion forum doesn’t turn into a for-profit opportunity for anonymous corporations.

It was incredibly easy to set up. All it involved was to install the utterances app on my blog repo, then paste a code snippet to my post template. If you’ll recall, I am using YASnippet as a templating tool for my blog posts. That said, I didn’t add the code directly into my post snippet. Instead I added a new directory, ~/org/src/ where I created an utterances.html file with the code in question. Then I simply included the file in my snippet to be exported as html:

#+INCLUDE: "../src/utterances.html" export html

Templating Update

Another change I made I started to touch on in my last post, and that has to do with my yasnippet “snippets”. I mentioned that including actual code within my ya-snippet file created an issue if I were to make changes to my blog template after the fact. Because of this, I decided to completely revamp my post snippet so that the build of each post is made mostly from external files. Here’s an example of what I’m talking about:

#+BEGIN_SRC html
#+SETUPFILE: ../org-templates/level-1.org
#+INCLUDE: "./src/header.html" export html

#+TITLE: ${1:Title}
#+CATEGORY: ${2:Category}
#+DATE: `(current-time-string)`
#+FILENAME: ${3:filename}

=* $1=

#+INCLUDE: "../../content/$3.org"

#+INCLUDE: "../src/utterances.html" export html
#+END_SRC

Notice that, in addition to the SETUPFILE, I have added three different INCLUDE files to export as blocks.

• header.html :: previously this was part of an export block included directly in the snippet. The code hasn’t changed; it’s just housed elsewhere.
• /content/ directory :: this was the solution to my date problem that I mentioned in my previous entry. Basically, posts should be dated according to when they were published, not when I started writing them. One solution would be to use the org exporter’s {{{DATE}}} macro, which assigns a date when the file is exported, but I wanted to ensure the date wouldn’t change if I needed to republish a file for any reason. So, I decided the best thing to do would be to house the actual blog content in a separate file, to be included in the post file, so the date would only be calculated when the snippet was inserted into the post. The idea is to only create a post for export when it is ready to be published.
• utterances.html :: I explained this above.

To conclude

As I said in my the previous post, this blog is, and will continue to be, a work in progress. Still, I probably won’t go over every single change or update I make to the configuration and templating system in the future. Instead, I’ll focus on figuring out what kind of content to put on here. I’m barely a programmer or developer – I would call myself a creative, and the purpose of this blog is to share some of my story and my process with the world. Stay tuned!

And then there’s org-mode¹, and all of its customization options and packages², and after playing around a bit I asked myself: is there anything I can’t do from here? I began using org-mode as a simple orgnization system and going through example setups and tutorial, noticing that many of the blogs and sites I was getting information from were themselves /written in org-mode/. And since I learn things best by doing projects I get really passionate about, I decided to give it a go and create my own static site blog with org-mode, which I would host on Github pages.

That’s how I became obsessed.

What follows is an abridged step-by-step summary of my process in creating a very basic framework for a static³ site blogging framework, which I am using for this blog.

Starting points and goals

I use Spacemacs, which is not a separate piece of software; rather, it is a specific emacs configuration for organizing and using emacs (to put it in the most simple terms). I also have access to all the built-in functionality of org-mode, and, if necessary, whatever package extensions I would need to get started. I realized that, given the right packages, there was very little that couldn’t be done.

Yet, installing packages left and right carried the risk of overreliance on external packages, and a lack of confidence in my own ability to find creative resolutions outside of fancy extensions. So I made a few flexible ground rules for myself with this in mind:

• I would use, as much as possible, the built-in functionality of org-mode, including org-publish and the org exporters, and would not use an external static site generator package⁴.
• I would build a framework that took advantage of org-mode functions while also allowing myself to /not/ use methods that existed if they didn’t suit my needs.
• I would not be restricted to solely using org-mode. I had to remind myself that there could be built-in or external emacs packages that weren’t specific to org, but could be easily integrated into my workflow.
• It didn’t have to be perfect or do every little thing I’d like to be “live”; this was a project that could be continuously in development, with features/functionality added as I learned more.

I’m going to reiterate here, I’m a complete newbie. I know very little emacs-lisp, I’ve only been playing around in emacs for a little over a month, and this build is based on what I’ve mastered so far. There are certainly aspects that could have been made a lot easier by using already-established solutions for a lot of my issues, but what fun would that be? I wanted this to be a fun, discovery process where I could figure things out, largely by my own tinkering and experimentation. So, please, if you are an emacs and org-mode master, be kind.

Initial file framework

The best resource I found at the beginning of this endeavor was an org-publish tutorial on Worg, a subsection of the official org-mode website maintained by the community of org-users that is an invaluable tool in learning all that you can do with org-mode.

Using this tutorial as a guide, I created two folders within my main project folder: ~/org/ and ~/public_html/. The idea is that my input would be under the ~/org/ directory, and whatever was in that directory would be exported to html and published in the ~/public_html/ directory.

After that, I left the ~/public_html/ folder alone, as any files and subdirectories should be created during the publishing process. Any changes I would make to the final html version of the files would be done in the org version.

Additionally, since anything in the ~/org/ directory would be exported (unless I specifically configured a certain file or headline not to be exported), it wasn’t restricted to simply org files. Simply put, any file at all that I wanted to eventually wind up in ~/public_html/ would be placed within ~/org/.

First, I created index.org within ~/org/ and then I created several folders (subdirectories) that would eventually carry files of their own. This was my initial file organization for this blog:

| ~/org/
  |- index.org
  |- css/
    |- style.css
  |- img/
  |- posts/
| ~/public_html/

With this setup, index.org would become index.html under the ~/public_html/ directory. Additionally, ~/org/css/style.css would be exported to ~/public_html/css/style.css so I could apply a consistent style to exported HTML files. The img/ directory would carry images and other attachments, while all posts would go into the posts/ folder for export.

Note, that if, in editing an org file within the ~/org/ directory, if I were to link to another org file within ~/org/, the exporter would then transform that link into a link to the corresponding file in ~/public_html/. Likewise, by applying /css/style.css to index.org, the ~/public_html/index.html file resulting from the export would be loaded with a stylesheet in ~/public_html/css/style.css.

The export.el file

Once I got some basic files set up under this framework, I needed to perform an initial export test to ensure that this would work as planned. Instead of creating my project configuration under my main emacs config file, I decided to use a separate file, ~/export.el, which I placed in my root (even with, and not under, ~/public_html/ and ~/org/).

The first line is (require 'ox-publish) which I use to ensure that emacs loads the ox-publish library when publication is triggered. After that I set the variable org-publish-project-alist to define my project scope.

First, I provide a list of components (“blog-posts”, “blog-pages”, and “blog-static”), and then I compile those components (and all of their settings) into the “blog” project. So it goes like this:

    (setq org-publish-project-alist
       '(("blog-posts"
          :base-directory "org/posts/"
          :base-extension "org"
          :publishing-directory "public_html/posts/"
          :recursive t
          :publishing-function org-html-publish-to-html
          :org-html-preamble nil
         )
         ("blog-pages"
          :base-directory "org/"
          :base-extension "org"
          :publishing-directory "public_html/"
          :recursive t
          :publishing-function org-html-publish-to-html
          :org-html-preamble nil
         )
         ("blog-static"
          :base-directory "org/"
          :base-extension "css\\|js\\|png\\|jpg\\|gif\\|pdf\\|mp3\\|ogg\\|swf"
          :publishing-directory "public_html/"
          :recursive t
          :publishing-function org-publish-attachment
         )
         ("blog"
          :components ("blog-posts" "blog-pages" "blog-static"))
    )

Now, I have several other options set up in export.el but have narrowed down what I felt were the most important for me to get this page set up how I want it. Let’s take a closer look at the three components and the settings I gave them above.

Components

• blog-posts: these are all the posts that will be published to the blog. I’ve given them a separate component because the configuration for these files could potentially differentiate from what’s in “blog-pages”, and I think it’s better to keep each part of the site separate as much as possible.
• blog-pages: so here we’re going with every org file within the ~/org/ directory⁵.
• blog-static: for all files included in the ~/org/ directory that aren’t org files, and should keep their native extension upon export.
• blog: this gives us all these separate components, and puts them together into one project.

Options

• base-directory: this is the directory where the files are coming from - in this case ~/org/
• publishing-directory: the directory where the files are going to be published to - ~/public_html/
• base-extension: tells the exporter to export files with this(these) extensions. For pages and posts, the files exported will end in .org, but for the static files, the base extension has multiple possibilities.
• publishing-function: this tells the back-end how to publish these files. I need to publish everything that’s an org file as an html file, so I set blog-posts and blog-pages with org-html-publish-to-html. Meanwhile, anything in the ~/org/ directory that doesn’t end in .org (blog-static) should just be copies into the desination folder using org-publish-attachment.
• recursive: tells the exporter whether to include files from subdirectories recursively, or just from the parent directory. This has two possible options: nil, meaning just use the parent directory, or non-nil (typically t is used), which means to also include subdirectories.
• org-html-preamble: this was important for me to set as nil to ensure that the exporter did not include a preamble, something that is included at the top of each file. While the preamble can be customized to suit your needs, I preferred not to mess with it and used a templating method instead (which I will go into later).

Now that I had my export.el file configured the way I wanted it and some dummy posts and pages set up to see how it looked, I could go ahead and publish. To do so, I placed my cursor after the ending parenthesis on the first line of the file ((require 'ox-publish)), and pressed C-x C-e⁶. Then I navigated to the end of the file, after the last ending parenthesis on the last line, and pressed C-x C-e again. This will evaluate the emacs-lisp code in the file. After that, all I had to do to execute was to press M-x org-publish-project which would list all the components in the minibuffer. I could then navigate down to select “blog” and press the return key. Afterward, I could find the resulting exported files and folders in the ~/public_html/ directory.

Adding style and usability

So now that I knew how to export an entire static website via org-mode, the question was: how do I get it to look how I want it to and behave how I need it to? I had a list of problems I needed to solve to brainstorm ways to fix them:

• Custom CSS stylesheet
• A tagging/category system for posts
• A custom header with custom links
• An index page that would contain my most recent posts
• A sitemap or archives page that would contain past entries

So let’s talk about the solutions I’ve implemented so far.

Export templates

While I already selected certain export options within export.el, I could also set options within specific files using properties dictating how the files would be exported⁷. That meant I could create export templates that could then be associated with whatever files I wanted.

I created a new folder on the same level as ~/org/ and ~/public_html/ called ~/org-templates/ and added two files: level-0.org and level-1.org. This was the level-0 file:

    #+options: html-link-use-abs-url:nil html-postamble:nil html-preamble:nil
    #+options: html-scripts:t html-style:nil html5-fancy:t tex:t
    #+options: tags:t title:nil toc:nil num:0 date:t
    #+html_doctype: html5
    #+html_container: div
    #+html_head: <link rel="stylesheet" type="text/css" href="css/style.css" />
    #+creator: Megan Renae

The level-1.org is exactly the same except the stylesheet link goes back a directory, becoming "../css/style.css".

Here are the important bits:

• No, I don’t want the exporter to insert org’s own postambe and preamble
• No, I don’t want to use the default stylesheet
• Yes, export posts with tags (in the end, I didn’t need this at all, as I decided not to use tags, but the option remains)
• No, don’t export the #+TITLE property with the file (I add the title myself through headlines)
• Use the HTML5 doctype
• Use div as the primary container for content
• Insert my custom CSS stylesheet into the head of the document
• No, don’t insert a table of contents with each file
• No, don’t number sections on the file
• Yes, please export with the date

I added the path to the template file at the top of each page with the #+SETUPFILE property:

    #+SETUPFILE: ~/org-templates/level-1.org

YASnippet

Org-mode allows creation of special blocks that are written between lines that start with #+BEGIN_XXXXX and end with #+END_XXXXX. In particular, to include HTML code within an org-file, you can use the lines #+BEGIN_EXPORT html and #+END_EXPORT.

I created a snippet to use for blog posts, and after adding the #+SETUPFILE, I wrote a very simple code to ensure my blog header was added to each new post. My blog post snippet, then, begins like this:

    #+SETUPFILE: ~/org-templates/level-1.org
    
    #+BEGIN_EXPORT html
    /code for my HTML header/
    #+END_EXPORT

I could create custom fields so each post had defined properties

Essentially, when beginning a new post, I was filling out a form, with each field providing more specific information about the post. There were five properties I felt were important to include:

• #+TITLE :: The title of the post, which was mirrored⁸ in the first-level headline of the content of the post.
• #+CATEGORY :: The category of the post, which would then be mirrored in a custom link created at the bottom of the entry that would lead back to the category’s (though I used the word “tag”) index page, which would have a list of all entries under that tag.
• #+DATE :: Automatically updated with the date the template was first inserted into the file. This isn’t ideal, and I realize this would be better to instead be the date of publication. Hey, I never said this was perfect.
• #+FILENAME :: This is just the name of the file without the =.org= extension, and it’s mirrors are used to create backlinks that will appear in the index page and the category page.
• #+EXCERPT :: Generally, just the first paragraph of an entry. This is used to create the “preview” text that will appear in the index page.

Here’s what this part looks like in practice:

#+TITLE: ${1:title}
#+CATEGORY: ${2:category}
#+DATE: `(format-time-string "%F")`
#+FILENAME: ${3:filename} 
#+EXCERPT: ${4:excerpt}

=* $1=
**`(format-time-string "%A, %B %d, %Y")`**

$4
$0
=/Tagged: [[../tags/$2.org][$2]]/=

The fields are formatted as ${X:placeholder}, with X being the number of the field, and “placeholder” being the text to be updated. Mirrors are given with $X. This also involves custom timestamps, and the values for the symbols used can be found in the GNU Emacs manual.

I could create backlinks with headline entries that I could refile to a tag index and to a custom sitemap

Notice that in the previous block I included a link at the end of the entry to a tag index which would then display all entries with the same category. Well, this is where that magic happens.

Now, org-publish does come with its own sitemap and index features, which have served plenty well on plenty of org-based websites. And I still may implement one or both of these features on this blog in the future. That said, I chose to use backlinking to create a poor-man’s indexing process.

The key here is the org-refile⁹ function, and that requires the pages that I’m using to be refiling targets to be included in the org-refile-targets variable, which I ended up defining in my personal configuration file. For purposes of this site, the setup is something like this:

(setq org-refile-targets '(org-agenda-files . (:maxlevel . 9)))
(setq org-reverse-note-order t)

I’ve turned on org-reverse-note-order so that newer entries would appear at the top of the indices. I can add any file to org-agenda-files by visiting it and pressing C-c [. With this configuration any headline within an agenda file (up to the 9th level) is a refile target. This leads me to the last section of my blog post snippet:

=* [[../posts/$3.org][$1]]=
`(format-time-string "%D %a")` ;; this is the refile headline in the tag indexing

=* [[./posts/$3.org][$1]]= || `(format-time-string "%D %a")`
/[[./tags/$2.org][$2]]/
$4
[[./posts/$3.org][Read more...]] :: this is refiled to the sitemap

This creates more mirrors from the fields that were defined earlier in the snippet. Now I just need to run the command org-refile, select the correct target, and these headlines will be placed in their correct place.

One problem, though… where is that?

Refining the structure

Let’s go back to the very beginning, when I created an index.org file, the first file of my org-publish project. It’s time to finalize that page by giving it our sitemap. To do this, I create a new file under ~/org/, sitemap.org, which I add as an agenda file. This is the file that I will end up using to create the list of posts in anti-chronological order that will appear in my index.org page.

To start, sitemap.org will have a single first-level headline, “Latest Posts”. Then I will refile the headline created with my blog post snippet to the sitemap file, and it will show up as the first entry. Now I go back to index.org so I can include the latest posts from sitemap.org on my blog’s front page. To do this, I can use the #+INCLUDE property, like this:

=#+INCLUDE: "~/org/sitemap.org"=

That’s a good start, but since the sitemap is going to house ALL files from the blog’s history, I don’t want to include the entire sitemap in my index page. Luckily, there’s a way to limit what lines will be included.

Let’s look back at the entry we’ve refiled to sitemap.org:

=* [[./posts/post.org][Post Title[]]= || XXXX-XX-XX XXX
/[[./tags/tag.org][category]]/
POST EXCERPT
[[./posts/post.org][Read more...]]

Since Emacs doesn’t automatically create new lines, I know that each entry in sitemap.org will be exactly 4 lines. The actual sitemap will begin on line 2, after the “Latest Posts” headline. Say I want to include the last five posts in my index page; all I need to do is calculate how many lines that would be.

In this case, 5 posts would be 20 lines. Since we’re starting on line 2, we know the last line we’ll need to use is line 21. However, when we include line numbers in the #+INCLUDE line, the last line given is excluded, so we’ll need to add one more to ensure the last post doesn’t get cut off early.

This is what we end up with:

#+INCLUDE: "~/org/sitemap.org" :lines "2-22"

Now, there’s one more thing: individual pages for each category or tag. I’ve already laid the groundwork with out snippet and the post, at the very end, contains a link to the category page under a new subdirectory I’ve created: ~/org/tags/. I can click that link when I’m done writing my post, and it will take me to a new buffer containing the category/tag index page. If it’s a new category, and therefore no page has been created yet, it will create a new buffer with a completely blank file and all I need to do is insert a headline (* TAG: CategoryName), press C-x C-s, and just like that the file is created. By pressing C-c [, the new file is added as an agenda file. Then, I can refile the corresponding headline to add a new entry to the tag page.

Final touches

Now that I have built the framework I need for this to work correctly, there are only a couple of things left before going live. The obvious one is to create an About page, which is self-explanatory, along with an Archives page for past entries (for which I use the same re-filing method I explained above with tags), and a Caategories Page to link to all of the individual category indices.

No, this isn’t exactly finished. I’ll be continuously working on this blog, whether that means to add something else, or to change things around, just to keep it in sync with my org learning curve, as well as my changing tastes and needs. I’d still like to implement an Archives page. I know that using ya-snippet in the way that I have can provide some difficulties when it comes to retroactive changes, so I’m trying to isolate individual elements in separate files to make implementing changes easier. I’m also using Magit for version control.

In short, this is a work in progress - just like me.

Footnotes