sourcehut
/
sr.ht-docs
mirror of https://git.sr.ht/~sircmpwn/sr.ht-docs
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

git.sr.ht: Recommend hut(1) to set custom README

This commit is contained in:
Thorben Günther 2023-10-30 17:30:53 +01:00 committed by Drew DeVault
parent 67c1822bca
commit 27e9e59f8f
1 changed files with 8 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
git.sr.ht/index.md
View File

@ -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).
```sh
# 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 { me { repository(name: "'$repo_name'") { id } } }' \
https://git.sr.ht/query
```
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 -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/