#+TITLE: Back to Org?
#+DATE: 2021-02-15
#+OPTIONS: num:nil
As I continue to experiment and refine my own writing setup I have
recently been trying out a quirky system not so different from the
original setup for this weblog.
** Ancient History
Funnily enough, the readme that I've been carrying around with this
blog from the beginning has this to say about the history of things:
#+BEGIN_QUOTE
It's history is getting only slightly convoluted:
- +originally written in Markdown using [[https://github.com/greghendershott/frog][Frog]]+
- +migrated to [[http://orgmode.org/][org mode]]+
- +migrated back to Markdown using [[https://github.com/NPrescott/static][my own static site generator]]+
- migrated to plain HTML using [[https://git.sr.ht/~nprescott/quiescent][my own static site generator]]
#+END_QUOTE
In particular, the migration to org-mode didn't last because I was
unhappy with how rigid the structure was, particularly around
publishing and the lack of things like RSS. Of course, with hindsight
and experience I can see how little I understood things.
While I've been pretty happy writing plain HTML for a while, I do
occasionally forget to escape a > or < sign. Rather than
re-integrate markdown or anything I set out to extend my tools while
keeping the parts that I like.
*** A New (Old) Alternative
I found a [[https://emacs.stackexchange.com/a/10772][concise explanation]] for exactly the sort of thing I
wanted to do and didn't have a name for. What I really needed, when I
wasn't happy with the exact HTML output from Org was to make a derived
back-end for export. In this way I can pare down to just the pieces I
want without having to write an entire exporter myself.
In my particular case what I want to do is export org-mode text into
partial HTML documents that can be directly consumed by my existing
static site generator. All this requires is a format like the
following:
#+BEGIN_EXAMPLE
A Title Goes in a Leading H1 tag
a date goes in a span tag
a leader paragraph follows
...
#+END_EXAMPLE
That is enough to process out my automatic index page, archive
page, and RSS feed.
#+BEGIN_SRC elisp
(defun weblog-post-template (contents info)
(concat
(format "%s
\n"
(org-export-data (or (plist-get info :title) "") info))
(format "%s\n"
(org-export-data (or (plist-get info :date) "") info))
contents))
(defun org-export-to-post
(&optional async subtreep visible-only body-only ext-plist)
(interactive)
(let ((outfile (org-export-output-file-name ".post" subtreep)))
(org-export-to-file 'post-html outfile
async subtreep visible-only body-only ext-plist)))
(org-export-define-derived-backend 'post-html 'html
:menu-entry '(?z "Export to weblog post" org-export-to-post)
:translate-alist '((template . weblog-post-template)))
#+END_SRC
That is sufficient to register my new export back-end so that when
invoking ~org-export-dispatch~ with
@@html:C-c C-e@@ the following prompt is
available:
#+ATTR_HTML: :alt demonstration of the Org mode export prompt with an entry for "weblog post back-end"
#+CAPTION: Org's dispatch menu means generating my post HTML is one keypress (z) away
[[./static/org-prompt.svg]]
** Motivation
Part of the motivation in getting back into Org mode is the kind of
interactivity that it lends itself to. Heck, even configuring this
new back-end was basically a breeze. While I don't mind writing
HTML I have found that I end up basically transcribing my own notes
at least twice. Org mode is more like a lab notebook while my
previous straight-HTML format was like the finished product. I'm
looking forward to keeping things easy so I can focus on projects
and substance rather than wearing myself out re-writing things.
*** DONE Turn off syntax highlighting
This one just bugs me, turns out it is easy enough to keep my
preferred plaintext code blocks:
#+BEGIN_EXAMPLE
(setq org-html-htmlize-output-type 'nil)
#+END_EXAMPLE
*** DONE Fix Atom feed links
While I was in here making sure I hadn't inadvertently broken a
bunch of links I finally got around to removing the hack that was
~~ inside the page template. Consequently, I've
half-jokingly included Org's automatic table of contents at the top
of the page because the hash-references should no longer be broken,
here or in the feed!
** Feed Reader Conformity Nightmares
While there are [[https://tools.ietf.org/html/rfc4287][specifications]] and [[https://www.w3.org/TR/xmlbase/][broad agreement]] on how feed
formats /should work/, in practice most readers only implement the
most common pieces. The piece giving me the most grief today has
been ~xml:base~ support. In an effort to fix the kludge-y bit of
HTML that makes so many of my absolute URLs work throughout the
atom feed I set about doing things right. In my case, that meant
replacing the ~~ from the HTML template and fixing
up countless dangling relative and quasi-relative URLs in old
posts.
I found the XML:base specification and was delighted to see it was
exactly the sort of thing I needed to make my relative URLs work
in the feed without changes to my posts. It wasn't difficult to
get the attribute added, in my case I already has an attribute
tracked on the post objects to suffice. No, the real problem lay
in trying to test it out. It seems that vanishly few feed readers
correctly implement XML:base.
I thought my implementation was to blame for how poorly things
were going with testing. At least until I found this
[[http://www.intertwingly.net/wiki/pie/XmlBaseConformanceTests][XmlBaseConformanceTests]] and information on testing from the [[https://pythonhosted.org/feedparser/resolving-relative-links.html][Python
~feedparser~ library]]. I was able to ingest my feed and verify that
my xml:base and relative URLs were all resolving correctly. I also
downloaded Thunderbird and tried my new feed there, where it
worked. I can't really account for why so many different readers
seem to struggle with it, but if it seems like images are broken
in the feed please verify your reader isn't broken!
** Thoughts
I'm not certain I will keep this setup but the best part has got to
be that it costs nothing to switch. I'll be committing both the
~.org~ and generated ~.post~ (HTML) file for now, partly because I
can't imagine /ever/ doing a big wholesale migration across formats
again. If I do decide that I don't like the way things are going I
can simply stop using Org and nothing changes. The site generator
stays the same and everything /keeps working/. While it might be
possible to integrate emacs and org into the site generation I see
that only as a pitfall to avoid. In case you've never bothered
checking out Org mode, I'll go ahead and [[./static/back-to-org.txt][drop a link]] to this post's
raw-text. It certainly is briefer than HTML can be albeit similarly
quirky.