I wanted 'd like to push my garden into Agora.
In this I am hindered by using org-mode. Agora, quite fairly, expects Markdown with wikilinks.
Chatted briefly with Flancian about org-roam and Agora in November 2020. It's in the Some Day section of the agora plan to support org-roam.
I figure in the interim, an org export backend could make sense. Something that basically takes my org files, and exports them to Markdown+wikilinks.
Currently a work in progress - check the log below, and the latest version here: https://gitlab.com/ngm/ox-agora
There is of course ox-md. And there is ox-blackfriday on which ox-hugo builds, and then there is ox-hugo itself. All these export to some form of Markdown.
Do not forget, there is also md-roam.
I don't think any of the oxen export to a wikilinks format. md-roam supports org-roam's notion of wikilinks, but I suspect this is slightly different from the standard notion of wikilinks.
As a first experiment:
md: publish.el @echo "Publishing for agora..." emacs --batch --load publish-agora.el --funcall commonplace/publish-for-agora
(require 'package) (package-initialize) (setq package-archives '(("melpa" . "https://melpa.org/packages/") ("org" . "http://orgmode.org/elpa/"))) (package-refresh-contents) (package-install 'htmlize) (package-install 'org-roam) (package-install 'ox-hugo) (package-install 's) (require 'ox-publish) (require 'ox-hugo) (require 'org-roam) (require 's) (defun commonplace/publish-for-agora () (let ((current-prefix-arg 4)) (call-interactively 'org-publish-all))) (setq org-publish-project-alist `(("commonplace" :components ("commonplace-notes")) ("commonplace-notes" :base-directory "/home/shared/commonplace" :base-extension "org" :publishing-directory "/tmp/agora" :publishing-function org-blackfriday-publish-to-blackfriday :recursive t :headline-levels 4 :with-toc nil :exclude "node_modules" )))
This outputs a folder of Markdown files. So far so good.
#+TITLEoption is not picked up
- the headlines or the org file start at #, but would need to be ##
- no wikilinks
I think probably the next step would be to create
ox-agora.el, which will be a publish backend, and override the bits in there that I need.
Nice! That works already. I just copied ox-blackfriday.el, and did a test override of the link transcode function.
OK! Now overriding the link override properly. It's OK when the link description is the name of the page being linked to. Not working yet with external links - need to do a check on the link type. Just stomps over most other link types at the moment.
Also need to prepend the title to the start of the file.
Alrighty, got the title coming through now OK by using
Have published the WIP export backend to https://gitlab.com/ngm/ox-agora.
And the WIP outfile files to https://gitlab.com/ngm/commonplace-agora.
Due to the way my filenames used to be named, there will also be a problem with some of the filenames at the moment. I wonder if I can add some kind of slugify method to the export. Alternatively, I'll just finish off moving all of my files to the new naming convention, which I want to do anyway.
Fixed (a bit) the external link clobbering. In
org-agora-link, I now check the type of the link, and only turn internal
file: links into wikilinks. Every else I use the raw URL of the link.
Will definitely need to refine this further. e.g. image links. And thinking about it, I'm probably also losing descriptions of the links.
As far as I can tell, output filename name boils down to
And the only way to amend that is with an EXPORTFILENAME property in the file itself. I couldn't see a way to let the backend determine the filename.
I wonder if I could do something like inserting the EXPORTFILENAME property to each file via an
org-export-before-processing-hook. I would put that not in ox-agora, but in my publish-agora.el file, as it's not something you should force on every user of ox-agora.
I suppose the problem with that, is that files referencing that file won't know about it's changed name, will they? So links would be broken? Well no, not in this case, as other files are using wikilinks based on the title.
Well, kind of pleased with myself. I couldn't get the
org-export-before-processing-hook approach to work. I could inject
#+EXPORT_FILE_NAME in to the buffer with it, but for whatever it wasn't subsequently being picked up or acknowledged.
So instead, I used
advice-add to modify the returned value of
(defun commonplace/slugify-export-output-file-name (output-file) (let* ((title (get-title (buffer-file-name (buffer-base-buffer)))) (directory (file-name-directory output-file)) (slug (commonplace/slugify-title title))) (concat directory slug ".md"))) (advice-add 'org-export-output-file-name :filter-return #'commonplace/slugify-export-output-file-name)
I basically get the title from the active buffer and slugify it, and concat it to the publish directory (gotten from the
output-file that is returned by
org-export-output-file-name). To be honest, it feels like a brutal hack, but I'm just pleased to have gotten it working. And I learned a bunch in the process. I hadn't used
advice-add before, for example.
I have joined an Agora! https://anagora.org/@neil
A couple of notes:
- I need to fix up my slugify method a bit. I knew this already, but I see it more now that some of the slugs I generate don't match the slugs that Agora expects.
- I think mainly punctuation is the issue. I convert question marks, commas, apostrophes, etc, into dashes, but they would be better just removed.
- It would be nice to autogenerate the agora markdown as part of my gitlab pipeline. I'm doing it manually for now. However, that's fine - manual until it hurts, and until I iron out a few wrinkles, I think.
Pushing to a repo from within a gitlab pipeline doesn't seem completely straightforward:
- How do I push to a repo from within a gitlab CI pipeline? - Stack Overflow
Git push from inside a gitlab-runner - GitLab CI/CD - GitLab Forum
Shame, but I don't think I'll spend too much time on it right now.
2 Elsewhere in the garden
Notes that link to this note (AKA backlinks).