ox-neuron: A Neuron Zettel Markdown back-end for Org Export Engine

ox-neuron implements a Markdown back-end for Org exporter. The exported Markdown is compatible with the Neuron Zettelkasten note-taking static site generator (https://neuron.zettel.page/). This exporter also handles org-brain (https://github.com/Kungsgeten/org-brain) and org-roam (https://github.com/org-roam/org-roam) relationships in notes. Thus, you can use ox-neuron to generate beautiful websites for your second brain.

This code builds on top of the ox-hugo exporter for the Hugo static site generator (https://ox-hugo.scripter.co) and uses a lot of it’s code as-is.

Status of the work

This is a fully working but first-cut version of the exporter. I am able to generate full static sites from my Org Mode notes, but I know the edge-cases that are not handled. The Issues Tab captures all the pending work and edge-cases, so if you have a doubt, please read through it once.

How to export your Org Mode notes?

ox-neuron treats any Org Mode heading with the :ID property as a valid heading for exporting to Neuron. Before starting an export operation, you need to define the variable org-neuron-base-dir to the file-path where you want to create the Neuron notes. ( Example: (setq org-neuron-base-dir "/home/vedang/my_neuron_notes/") ). You also need to ensure that this path already exists. To create your Neuron static site, you need to create a neuron.dhall file at this path, with the following contents:

{ plugins = [ "neuronignore", "links", "uptree", "feed", "dirtree" ]}

You are now ready to export your Org Mode notes to Neuron.

The ox-neuron backend provides two ways to export data in an org-file:

• Everything under the heading at point. (C-c C-e N N)
  • If the point is in a valid Neuron heading, export the content to a Neuron file. The filename derives from the heading :ID. For every valid subheading under this heading, export the content to new Neuron files.
• Everything in the file. (C-c C-e N n)
  • Export every valid Neuron heading in the file.

On the nature of the generated filenames

By default, ox-neuron uses the :ID: property to create the name of the exported file. This is because org-mode links are :ID: based by default, so it makes it easy to refer to all the content by it’s unique IDs. However, this might not always be desirable, since it makes it difficult to read the filename and use an external tool such as Obsidian to visualize the output. To support this use-case, you can (setq org-neuron-export-human-readable-filenames t) for human-readable filenames. When this variable is set to true, ox-neuron behaves in the following way:

1. Use :EXPORT_FILE_NAME: property if it is defined. (highest priority)
2. Use :EXPORT_HUGO_SLUG: property if it is defined. (second priority)
3. Construct a unique name for the entry, using a combination of the :ID: and the title of the entry.

NOTE: The reason that org-neuron-export-human-readable-filenames is unset by default is because you will need to export the content /*twice*/ in order to maintain the correct cross-links across the various posts. This is because ox-neuron has to replace the id-links generated by org-mode with the human readable ones and it needs two passes to ensure that it has seen all the links.

What does the structure of the exported markdown look like?

The general structure of an exported post looks like this:

<yaml-metadata>
<div class="ox-neuron-main">
  <div class="ox-neuron-toc">
    <div class="ox-neuron-toc-contents">
      <div class="ox-neuron-toc-heading"></div>
      <div class="ox-neuron-toc-items"></div>
    </div>
  </div>

  <div class="ox-neuron-article">
    <div class="ox-neuron-article-contents"></div>
  </div>

  <div class="ox-neuron-footnotes">
    <div class="ox-neuron-footnotes-contents"></div>
  </div>
</div>

Note that the div statements are inserted in the right places in the generated markdown content, and this is fine for most static generators that use markdown as the format for writing content