#+Title: Using an Org-mode README on SourceHut
#+OPTIONS: toc:nil

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:

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

* Display README.org in plain text

1. Rename your Org README.org as README and it will be displayed as
   plain text on the Summary tab.
2. 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, [[https://git.sr.ht/~taingram/org-readme/blob/master/README.org][Org is extremely readable
without any special rendering]].  For best readability avoid embedding
links inside of text paragraphs.

* 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:

#+begin_src emacs-lisp
(add-to-list 'org-export-backends 'md)
#+end_src

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:

#+begin_src emacs-lisp
  emacs README.org --batch --eval '(org-md-export-to-markdown)'
#+end_src

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.

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

Sourcehut provides functionality for [[https://man.sr.ht/git.sr.ht/#setting-a-custom-readme][setting your Summary tab to any
arbitrary HTML]].  You can do this easily with the [[https://sr.ht/~xenrox/hut/][hut]] command.

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

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.

#+begin_src sh
  emacs README.org -Q --batch --eval '(require 'ox-html) (org-html-export-to-html nil nil nil t)'
#+end_src

** Automatically export README to HTML and apply it

This process can be triggered automatically using the sourcehut builds
service [[https://man.sr.ht/builds.sr.ht/][builds.sr.ht]].[fn:1] 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.

#+include: .builds/org-readme.yml src yaml

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 [[https://man.sr.ht/builds.sr.ht/#gitsrht][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 [[https://git.sr.ht/~taingram/emacs-init][emacs init repository]].

* License
:PROPERTIES:
:UNNUMBERED: t
:END:

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

@@html:
  <a rel="license"
     href="http://creativecommons.org/publicdomain/zero/1.0/">
    <img src="https://licensebuttons.net/p/zero/1.0/88x31.png" style="border-style: none;" alt="CC0" />
  </a>
@@

* See also
:PROPERTIES:
:UNNUMBERED: t
:END:

- [[https://breatheoutbreathe.in/blog/2024-12-10-sourcehut-org-mode-readme.html][Render README.org as HTML on Sourcehut]]

* Footnotes

[fn:1] If you are concerned about wasting build server resources to
render a readme please note this is the solution [[https://lists.sr.ht/~sircmpwn/sr.ht-discuss/%3C87cyib79ad.fsf@%3E][Drew DeVault has
actively recommended]].