Skip to content

docs: improve README clarity — explain what the tool does and why #120

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
andrey-helldar merged 3 commits into from
Feb 24, 2026
Merged

docs: improve README clarity — explain what the tool does and why #120

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ba00a35
Initial plan
Copilot Feb 24, 2026
680f942
docs: improve README clarity with better overview and how-it-works se…
Copilot Feb 24, 2026
22ec274
docs: apply review suggestions to README overview section
Copilot Feb 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 30 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,36 @@

## Overview

GitHub Action that generates an always-fresh preview banner for your project and keeps it at the top of your
`README.md`. The action detects your package manager, builds a light/dark banner, replaces any previous preview block,
commits the change in a dedicated branch, and opens a pull request with optional assignees and labels.
[banners.beyondco.de](https://banners.beyondco.de) is a service that generates beautiful social preview banners for
GitHub projects. The image at the top of this README is an example of such a banner.

The problem is that each banner URL must be manually crafted — you have to fill in the project title, description,
package manager install command, icon, and other parameters by hand, then keep the URL up to date whenever any of
those details change.

**GitHub Preview Updater** is a GitHub Action that automates all of that. It reads your repository metadata
(name, description, package manager), builds the correct banner URL automatically, and keeps the
`<picture>` block in your `README.md` up to date — creating a pull request whenever the banner changes.

### What gets inserted into your README

After the first heading (for example, `# My Project`) the action inserts (or replaces) the following block:

```html
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://banners.beyondco.de/...&theme=dark">
<img src="https://banners.beyondco.de/...&theme=light" alt="{project_name}">
</picture>
```

Both a light-theme and a dark-theme variant of the banner are generated automatically.

### How it works

1. The action reads your `composer.json` / `package.json` to detect the package manager, package name, and description.
2. It builds the banner URL for [banners.beyondco.de](https://banners.beyondco.de) using the collected data.
3. It replaces the `<picture>` block in your `README.md` with the freshly generated URLs.
4. If the file changed, it commits the update to a new branch and opens a pull request.

## Quick start

Expand Down
Loading