Circumventing Sourcehut's missing Org support

Sourcehut currently has no support for rendering Org documents, mostly because there are no good parsers out there, but there is a way around this.

I looked around the internet and found a decent solution, written by Corwin Brust, that utilizes a pre- and post-commit hook to convert Org documents to their Markdown equivalent. I read through the source code and realized it could be shortened to a simple pre-commit hook. Here's what I came up with:

#!/bin/sh

emacs --batch --load "$HOME"/.config/emacs/lisp/+publish.el
git add README.md

You'll have to chmod +x the above file so that git can execute the script when the hook is triggered, the +publish.el file could contain something like:

(require 'ox-md)

(defvar +readme "README.org"
  "Filename of README file.")

(when (file-exists-p +readme)
  (find-file +readme)
  (let ((org-export-with-toc nil))
    (org-md-export-to-markdown)))

(message "Published documentation")

The next time you create a commit, README.org will be published to its Markdown equivalent and Sourcehut will finally pick it up and show it alongside the summary view.

Furthermore, you're not limited to just Markdown. If, for example, you're writing a manual for an Emacs Lisp package, you can make it so the document also gets exported to Texinfo.

You can do this by modifying the above examples to something along these lines:

#!/bin/sh

emacs --batch --load "$HOME"/.config/emacs/lisp/+publish.el
git add README.md MANUAL.md MANUAL.texi

We've staged all the documents we wish to publish; let's update the publishing script accordingly.

(require 'ox-md)
(require 'ox-texinfo)

(defvar +readme "README.org"
  "Filename of README file.")

(defvar +manual "MANUAL.org"
  "Filename of MANUAL file.")

(when (file-exists-p +manual)
  (find-file +manual)
  (org-texinfo-export-to-texinfo)
  (let ((org-export-with-toc nil))
    (org-md-export-to-markdown)))

(when (file-exists-p +readme)
  (find-file +readme)
  (let ((org-export-with-toc nil))
    (org-md-export-to-markdown)))

(message "Published documentation")

I hope this workaround is soon made obsolete by an improvement to the state and support of the current Org parsers as it's a little annoying having to keep two copies of everything, but for now, this is pretty much all we've got.