Out of the box, Sourcehut only renders README, README.md, and README.markdown.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.

Footnotes

1

Requests for Org-mode README rendering support on git.sr.ht: Mar 2020 Feb 2021 Oct 2021 Jan 2022 June 2022 May 2024 Dec 2024