user: Document README badges

Signed-off-by: Gergely Nagy <me@gergo.csillger.hu>

docs/user/index.md

@@ -28,6 +28,7 @@ involved in running it on their machines.
   - [Tags and Releases](https://docs.codeberg.org/git/using-tags/)
   - [Branch and tag protection](./protection/)
   - [Git blame](./blame/)
+  - [README badges](./readme-badges/)
 - Advanced Usage
   - [Issue and Pull Request Templates](./issue-pull-request-templates/)
   - [Actions](./actions/)

docs/user/readme-badges.md

@@ -0,0 +1,20 @@
+---
+title: README badges
+license: 'CC-BY-SA-4.0'
+---
+
+If the [badges service](../../admin/config-cheat-sheet/#badges-badges) is enabled, Forgejo makes it possible to add badges - transparently generated by a service like `shields.io` - to your READMEs and other documentation. These badges let you display useful information about your repository within documentation that might also be displayed elsewhere, outside of the forge itself (such as on container information pages, library documentation sites, and so on). Information such as the latest release, stars, pull request and issue information, or [Actions workflow](../actions/) statuses.
+
+The badges are returned in SVG format, and are available under the `https://forgejo.example.com/{username}/{repository}/badges` path. Forgejo currently supports generating the following badges:
+
+- `/release.svg`: The latest release made in the repository.
+- `/stars.svg`: The number of stars the repository has.
+- `/issues.svg`: The total number of issues in the repository, open and closed combined.
+- `/issues/open.svg`: The number of open issues.
+- `/issues/closed.svg`: The number of closed issues.
+- `/pulls.svg`: The number of pull requests against the repository, open and closed combined.
+- `/pulls/open.svg`: The number of open pull requests.
+- `/pulls/closed.svg`: The number of closed pull requests.
+- `/workflows/{workflow_file}/badge.svg`: The status of the `{workflow_file}` workflow. Additional restrictions can be given for this badge by using the `branch` and/or `event` query parameters. The `branch` query parameter will display the status of the workflow from the given branch (defaulting to the repository's main branch if not explicitly specified), while the `event` parameter will only display results if a run was triggered by the specified event.
+
+All query parameters not known to Forgejo will be passed along to the badge generator service as-is. If using the default - `shields.io`-based - generator, this means that query parameters such as `style` and `color` will be respected.