27e9e59f8f68482e717f45e4536a20f572b6f6c9 — Thorben Günther 29 days ago 67c1822 master
git.sr.ht: Recommend hut(1) to set custom README
1 files changed, 8 insertions(+), 65 deletions(-)

M git.sr.ht/index.md
M git.sr.ht/index.md => git.sr.ht/index.md +8 -65
@@ 359,80 359,23 @@ By default, if found, a `README` plaintext or `README.md` markdown file
will be rendered as the repository's README.

However, you can use an arbitrary HTML snippet as your README instead by using
the [GraphQL API](https://man.sr.ht/graphql.md). First, [generate
a personal access token](https://meta.sr.ht/oauth2/personal-token). You'll then
need to fetch the repository ID:
the [GraphQL API](https://man.sr.ht/graphql.md).

# Replace the following with your personal access token:

# And this with your repository name:

curl --oauth2-bearer $bearer_token \
  -G --data-urlencode query='query { me { repository(name: "'$repo_name'") { id } } }' \

Your repo ID never changes, so it's safe to write it down in a script. You can
then use the following to set the README for your repository:

# And replace this with your repository ID:

# And the readme file:

jq -sR '{
    "query": "mutation UpdateRepo($id: Int!, $readme: String!) {
      updateRepository(id: $id, input: { readme: $readme }) { id }
    }", "variables": {
      "id": '$repo_id',
      "readme": .
    } }' < $readme \
  | curl --oauth2-bearer $bearer_token \
    -H "Content-Type: application/json" \
    -d@- https://git.sr.ht/query

This looks a bit complicated, so to explain what's happening here: we want to
execute the following GraphQL request:
[hut] can easily do this:

mutation UpdateRepo($id: Int!, $readme: String!) {
  updateRepository(id: $id, input: { readme: $readme }) { id }
hut git update --readme readme.html --repo https://git.sr.ht/~foo/bar

The [jq](https://stedolan.github.io/jq) command takes the input (your README
file) and incorporates it into a JSON string with the following format:
Or if you want to remove the custom README:

  "query": "the desired GraphQL query...",
  "variables": {
    "id": 1337,
    "readme": "your README HTML..."
hut git update --readme "" --repo https://git.sr.ht/~foo/bar

This is [the input](https://man.sr.ht/graphql.md#performing-graphql-queries) to
the git.sr.ht GraphQL endpoint at `git.sr.ht/graphql`, which is piped from jq
into [curl](https://curl.se) to send the request to git.sr.ht.

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][secrets] to safely store your OAuth token.
another markup format and submit it on each git push.
Check out the [example][readme example] to avoid some common pitfalls.

If you want to remove the custom README, set the `readme` to `null`.

mutation { updateRepository (id: <repo_id>, input: { readme: null }) { id } }

[secrets]: https://man.sr.ht/tutorials/builds.sr.ht/using-build-secrets.md
[readme example]: https://git.sr.ht/~nabijaczleweli/html-readme
[readme example]: https://git.xenrox.net/~xenrox/custom-readme
[hut]: https://sr.ht/~emersion/hut/