git.sr.ht: document {GET,PUT,DELETE} /api/repos/:name/readme, mention it in the FAQ

Ref: ~sircmpwn/git.sr.ht#205

1 files changed, 27 insertions, 0 deletions

diff --git a/git.sr.ht/index.md b/git.sr.ht/index.md
index 2a6382b..48a28ac 100644
--- a/git.sr.ht/index.md
+++ b/git.sr.ht/index.md
@@ -79,3 +79,30 @@ repository. To rename your default branch, use something like the following:
 
     git branch -m master main
     git push origin :master main:main
+
+## Setting a custom README
+
+By default, if found, a `README` plaintext or `README.md` markdown file
+will be rendered as the repository's README.
+
+However, you can use any HTML snippet by using [the API](api.md);
+for example, if you get your [personal access token](https://meta.sr.ht/oauth),
+you will be able to run:
+
+```sh
+curl -H "Authorization: Bearer your-token" \
+     -H "Content-Type: text/html"          \
+     -XPUT                                 \
+     --data @README.html                   \
+     "https://git.sr.ht/api/repos/your-fun-repo/readme"
+```
+
+To set your-fun-repo's README to the contents of `README.html`. Note that the
+README, when rendered on the web, is still subject to the normal HTML
+sanitization that is applied to Markdown.
+
+It may be desirable to configure a builds.sr.ht job to compile your README from
+another markup format and submit it on each git push; if so, you will need to
+review the [build secrets
+tutorial](https://man.sr.ht/tutorials/builds.sr.ht/using-build-secrets.md) to
+safely store your OAuth token.