~sircmpwn/sr.ht-docs

6ea6e6451243e7cc62727d88bccf2b461d153f0f — наб 25 days ago 78d5bc0
git.sr.ht: document {GET,PUT,DELETE} /api/repos/:name/readme, mention it in the FAQ

Ref: ~sircmpwn/git.sr.ht#205
2 files changed, 59 insertions(+), 0 deletions(-)

M git.sr.ht/api.md
M git.sr.ht/index.md
M git.sr.ht/api.md => git.sr.ht/api.md +32 -0
@@ 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.

M git.sr.ht/index.md => git.sr.ht/index.md +27 -0
@@ 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.