~sircmpwn/sr.ht-docs

3fbfacabfffa430639f1d017b5bfd1210387dc1f — Drew DeVault 6 months ago 4ddacc3
Update git.sr.ht custom README to API 2.0
1 files changed, 40 insertions(+), 17 deletions(-)

M git.sr.ht/index.md
M git.sr.ht/index.md => git.sr.ht/index.md +40 -17
@@ 108,26 108,49 @@ repository. To rename your default branch, use something like the following:
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:
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:

```sh
curl -H "Authorization: Bearer your-token" \
     -H "Content-Type: text/html"          \
     -XPUT                                 \
     --data-binary @README.html            \
     "https://git.sr.ht/api/repos/your-fun-repo/readme"
# Replace the following with your personal access token:
bearer_token=xrAV8VvqzChACiu+kR7kDdoPl0RcpkQJNplJCHeQ6Tw169H8C4WXIM9m

# And this with your repository name:
repo_name=example

curl --oauth2-bearer $bearer_token \
  -G --data-urlencode query='query { repositoryByName(name: "'$repo_name'") { id } }' \
  https://git.sr.ht/query
```

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

```sh
# And replace this with your repository ID:
repo_id=1337

# And the readme file:
readme=README.html

jq -R '{
    "query": "mutation UpdateRepo($id: Int!, $readme: String!) {
      updateRepository(id: 60, 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
```

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. Check out the
[example](https://git.sr.ht/~nabijaczleweli/html-readme) to avoid some common
pitfalls.
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.
Check out the [example][readme example] to avoid some common pitfalls.

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