~taingram/org-readme

This file is a demonstration of how to use an Org mode file as your README on sourcehut. Currently sourcehut only provides native support for markdown files, and I believe Org is a more pleasant markup language.

Sourcehut gives us several options to specify README using alternate markup formats. The three main options are:

Display your Org README as plain text.
Export your README.org to README.md.
Export README.org to HTML set it using the custom README options.

1. Display README.org in plain text

Rename your Org README.org as README and it will be displayed as plain text on the Summary tab.
To allow programs to detect the file as Org you can
- create a symbolic link ln -s README README.org,
- or for Emacs set a file local variable -*- mode: org-mode -*- on the first line.

For most projects this should be sufficient, Org is extremely readable without any special rendering. For best readability avoid embedding links inside of text paragraphs.

2. Export README.org to README.md

To enable markdown in the export menu you will need to add it to the org-export-backends list from the customize menu or with:

(add-to-list 'org-export-backends 'md)

Now while visiting an Org file we can export it to markdown with C-c C-e m m. This can be done from the commandline with:

emacs README.org --batch --eval '(org-md-export-to-markdown)'

Commit the README.md to your repo and you'll get a nicely rendered markdown file on the Summary tab. This gives us the CSS, syntax highlighting, and headline linking sourcehut provides by default without needing to write markdown.

I recommend using this as a way to write-up a file in Org and then upload it once. Write the readme in Org, export it, commit the markdown file, then throw out the Org file. Trying to maintain two separate README formats seems like a hassle. Even if you automate the process it will likely confuse contributors.

3. Export README.org to HTML and apply a custom README

Sourcehut provides functionality for setting your Summary tab to any arbitrary HTML. You can do this easily with the hut command.

hut git update --readme readme.html --repo https://git.sr.ht/~foo/bar

So a simple process for this would be to occasionally export your README to HTML (C-c C-e h h) and then manually upload it with hut. That would work well for a project where the README is updated only occasionally, and keeps the git tree free of extra files.

emacs README.org -Q --batch --eval '(require 'ox-html) (org-html-export-to-html nil nil nil t)'

3.1. Automatically export README to HTML and apply it

This process can be triggered automatically using the sourcehut builds service builds.sr.ht.¹ The builds are automatically triggered after each commit. If you don't want them to run then push with git push -o skip-ci.

The build system looks for a .build.yml file, or any .yml files in the .builds/ folder, and runs the specified tasks after receiving new commits. This repository contains a .builds/org-readme.yml manifest that can be copied into any other project to render an Org README.

image: debian/testing
oauth: git.sr.ht/REPOSITORIES:RW git.sr.ht/PROFILE:RO
packages:
  - hut
  - emacs
sources:
  - https://git.sr.ht/~taingram/org-readme
environment:
  README: README.org
tasks:
  - export-readme: |
      cd org-readme
      emacs -Q --batch \
        --eval='(setq vc-handled-backends nil)' \
        --eval '(setq org-startup-folded nil)' \
        --eval '(setq org-element-cache-persistent nil)' \
        --eval "(require 'ox-html)" \
        --eval "(find-file \"$README\")" \
        --eval '(org-html-export-to-html nil nil nil t)'
      hut git update --readme $(basename "$README" .org).html

When using this manifest file ensure the following information has been updated:

sources: Your repository URL.
README: Your Org file to be exported if it is not named README.org.
cd org-readme: Your repository's directory name.

Copy the file to your .builds/ folder and it should work automatically. Note that sourchut will only run 4 build manifests max per project. If you have existing builds you can add this as a separate task.

For an example project with a large Org file see my emacs init repository.

License

To the extent possible under law, I, Thomas Ingram, waived all copyright and related or neighboring rights to this project.

Footnotes:

If you are concerned about wasting build server resources to render a readme please note this is the solution Drew DeVault has actively recommended.

refs

clone