2 files changed, 59 insertions, 0 deletions
diff --git a/git.sr.ht/api.md b/git.sr.ht/api.md
index c2ebce6..f8c2233 100644
--- a/git.sr.ht/api.md
+++ b/git.sr.ht/api.md
@@ -197,6 +197,38 @@ Deletes a [repository resource](#repository-resource).
 
 **OAuth scope**: `info:write`
 
+### DELETE /api/repos/:name
+
+Deletes a [repository resource](#repository-resource).
+
+**OAuth scope**: `info:write`
+
+### GET /api/:username/repos/:name/readme
+### GET /api/repos/:name/readme
+
+Gets the repository README override, or 404 if none is set.
+
+The HTML returned from this endpoint is NOT sanitized.
+
+**OAuth scope**: `info:read`
+
+### PUT /api/repos/:name/readme
+
+Sets the repository README override.
+
+**OAuth scope**: `info:write`
+
+**Request body**
+
+`text/html` of new README to use for the repository, after sanitisiation.
+
+### DELETE /api/repos/:name/readme
+
+Unsets the repository README override, if any.
+The relevant files in the repository tip, if any, will be used; this is the default.
+
+**OAuth scope**: `info:write`
+
 ## Common data endpoints
 
 Endpoints for fetching git data from repos.
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.