Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/vedang/ox-neuron

A Neuron Zettel Markdown back-end for Org Export Engine
https://github.com/vedang/ox-neuron

Last synced: 22 days ago
JSON representation

A Neuron Zettel Markdown back-end for Org Export Engine

Awesome Lists containing this project

README 

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

:PROPERTIES:

:CREATED:  [2022-01-02 Sun 11:19]

:ID:       36090166-5193-4416-9e23-dac2936e468c

:END:



~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

:PROPERTIES:

:CREATED:  [2022-01-02 Sun 11:19]

:ID:       ee4d1c87-0cd0-4813-bf9b-504d4ef62067

:END:



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?

:PROPERTIES:

:CREATED:  [2022-01-02 Sun 11:19]

:ID:       467d86a4-460e-42ed-9d1c-345ef5788b5c

:END:



~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:

#+begin_example

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

#+end_example



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

:PROPERTIES:

:CREATED:  [2022-08-25 Thu 22:29]

:ID:       0A1883FB-FC11-4180-AFEB-876F28403F89

:END:



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 [[https://obsidian.md/][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?

:PROPERTIES:

:CREATED:  [2023-05-24 Wed 13:57]

:ID:       4083A3DD-9445-467A-9B06-3F4ACFC4E6DC

:END:



The general structure of an exported post looks like this:



#+begin_example

  

  


    


      


        


        


      


    



    


      


    



    


      


    


  


#+end_example



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