Render README.org as HTML on Sourcehut
Out of the box, Sourcehut only renders README, README.md, and
README.markdown. The maintainers have denied multiple requests to
render Org mode README files by default.1
Workarounds to render README.org
One proposed workaround is to export README.org to README.md (in a
git hook), and then commit README.md, which will be rendered as HTML
on git.sr.ht. Another option is to set a custom README.
Here's how we render the README for hyperdrive.el on git.sr.ht by setting a custom README:
Makefile + build script
The Elisp for exporting README.org to HTML goes in a Makefile, which
simplifies the packaging process, since there's no extra .el file
for linters and compilers to complain about. Credit for the idea to
use a Makefile goes to Jonas Bernoulli.
Add a file called Makefile at the root of your project
(hyperdrive.el Makefile):
EMACS := emacs
EMACSQ := $(EMACS) -Q
BATCH := $(EMACSQ) --batch \
--eval '(setq vc-handled-backends nil)' \
--eval '(setq org-startup-folded nil)' \
--eval '(setq org-element-cache-persistent nil)' \
--eval '(setq gc-cons-threshold (* 50 1000 1000))'
README.html: README.org
$(BATCH) --find-file $< --eval "(require 'ox-html)" \
--eval '(org-html-export-to-html nil nil nil t)'
The build script installs hut and emacs, clones your repo, exports
README.html, and sets the custom README. Add a file called
readme.yml in the .builds/ subdirectory of your project
(hyperdrive.el .builds/readme.yml):
image: archlinux
oauth: git.sr.ht/REPOSITORIES:RW git.sr.ht/PROFILE:RO
packages:
- hut
- emacs-nox
sources:
- https://git.sr.ht/~ushin/hyperdrive.el
tasks:
- update-readme: |
cd hyperdrive.el
make README.html
hut git update --readme README.html
I hope this helps you. Feel free to contact me with suggestions, corrections, or questions!
Acknowledgements
Thank you to Thorben Günther, for this example git repo which shows how to set a custom README.