> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payreque.st/llms.txt
> Use this file to discover all available pages before exploring further.

# README Badge

> Get a copy-paste badge that links to your PayRequest Page — perfect for a GitHub README, a website footer, or anywhere else that supports images and links.

# README Badge

Add a small, professional badge to your project's README, website, or bio that links straight to your PayRequest Page. It's a one-click copy from your dashboard — no design work, no image hosting, nothing to maintain.

<Info>
  The badge is available for every PayRequest Page that has a handle set (your `payrequest.me/your-handle` link). If you haven't chosen a handle yet, do that first from **PayRequest Page → Overview**.
</Info>

## Overview

<CardGroup cols={2}>
  <Card title="One-Click Copy" icon="copy">
    Grab a ready-made snippet from your dashboard — nothing to write or format yourself.
  </Card>

  <Card title="Works Anywhere Markdown Does" icon="code">
    GitHub, GitLab, npm packages, blogs, forums — anywhere that renders Markdown or plain images and links.
  </Card>

  <Card title="Always Current" icon="rotate">
    The badge reflects your page live — if you're running a donation goal, it shows the amount raised right now.
  </Card>

  <Card title="Matches Your Page Mode" icon="palette">
    The wording adapts automatically depending on whether your page is set to Products, Amounts, or Donation mode.
  </Card>
</CardGroup>

## How to Get Your Badge

<Steps>
  <Step title="Open PayRequest Page">
    Go to **PayRequest Page** from the main menu — you'll land on the **Overview** tab by default.
  </Step>

  <Step title="Find the README badge card">
    In the left-hand sidebar, look for the **README badge** card, just below the **Page Mode** card. This only appears once your page has a handle.
  </Step>

  <Step title="Copy the snippet">
    Click the copy icon in the field — it copies a ready-to-paste snippet that already includes your handle and links to your live PayRequest Page.
  </Step>

  <Step title="Paste it wherever you like">
    Drop it into your GitHub README, your website, or anywhere else — see below for specific examples.
  </Step>
</Steps>

## Adding It to GitHub

<Steps>
  <Step title="Open your repository's README.md">
    On GitHub, click the pencil (edit) icon on your `README.md` file, or edit it locally and push the change.
  </Step>

  <Step title="Paste the snippet">
    Paste the copied snippet near the top of the file, or under a **Support** / **Sponsor** heading further down — both are common conventions.
  </Step>

  <Step title="Commit the change">
    Commit directly to your default branch, or open a pull request if that's your project's convention.
  </Step>

  <Step title="Check it renders">
    Open the repository page on GitHub — your badge should appear as a small clickable image. Clicking it takes visitors straight to your PayRequest Page.
  </Step>
</Steps>

<Tip>
  A common pattern is to place it right after your project title and description, alongside other badges like build status or version — that's usually the first thing visitors see.
</Tip>

## Adding It Elsewhere

The snippet is standard Markdown, so it works anywhere Markdown is supported:

| Where                         | How                                                                                                                                                         |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **GitLab / Bitbucket**        | Same as GitHub — paste into `README.md`                                                                                                                     |
| **npm / PyPI package README** | Paste into the README file that ships with your package                                                                                                     |
| **Blog posts**                | Most blogging platforms (Ghost, Dev.to, Hashnode) accept the same Markdown snippet                                                                          |
| **Forum signatures**          | If the forum only accepts an image + link (not Markdown), use the plain image address shown next to the snippet and wrap it in your forum's own link format |
| **A plain website**           | Use the badge as a normal `<img>` tag pointing to the same image address, wrapped in a link to your PayRequest Page                                         |

<Tip>
  If a platform doesn't support Markdown, you can still use the badge — it's just a small image. Right-click the rendered badge on your own page (or ask a developer friend) to grab the direct image address, then use it with that platform's own image + link syntax.
</Tip>

## What the Badge Shows

The text on the badge updates automatically based on your [Page Mode](/shop-and-checkout/donation-mode):

| Page Mode                                     | Badge shows                                                            |
| --------------------------------------------- | ---------------------------------------------------------------------- |
| **Products & services** or **Amount buttons** | "Pay with PayRequest"                                                  |
| **Donation mode** (no goal set)               | "Support me · PayRequest"                                              |
| **Donation mode** (goal set)                  | "Support me · €X raised" — the live total for your current goal period |

<Info>
  You don't need to update the badge yourself when your donation total changes — anyone viewing your README or website always sees the current amount, refreshed every few minutes.
</Info>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Do I need a handle to use the badge?">
    Yes. Your handle is what makes your PayRequest Page URL (`payrequest.me/your-handle`) and it's also part of the badge image address. Set one from **PayRequest Page → Overview** if you haven't already.
  </Accordion>

  <Accordion title="Can I change the badge's color or text?">
    Not currently — the badge uses a consistent PayRequest style so it's instantly recognizable, and the wording is chosen automatically based on your Page Mode.
  </Accordion>

  <Accordion title="Does the badge slow down my README or website?">
    No. It's a tiny image, similar in size to any other status badge you might already be using.
  </Accordion>

  <Accordion title="What happens if I rename my handle later?">
    Update the badge snippet with your new handle — old links using the previous handle will stop matching your page, so re-copy the snippet from your dashboard after a handle change.
  </Accordion>

  <Accordion title="Does it work in GitHub's dark mode?">
    Yes — the badge has its own fixed background color, so it stays legible in both GitHub's light and dark themes.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Donation Mode" icon="heart" href="/shop-and-checkout/donation-mode">
    Turn your page into a fundraising goal with a live progress bar and donor feed — your badge shows the running total.
  </Card>

  <Card title="PayRequest Page Styling" icon="palette" href="/shop-and-checkout/sales-page-styling">
    Brand your page with an avatar, tagline, accent color, and social links.
  </Card>

  <Card title="Coffee Tips" icon="mug-hot" href="/shop-and-checkout/coffee-tips">
    A friendlier "Buy Me a Coffee"-style version of Donation Mode with a drinks menu and GIFs.
  </Card>

  <Card title="Custom Domains" icon="globe" href="/shop-and-checkout/custom-domains">
    Use your own domain for your PayRequest Page instead of payrequest.me.
  </Card>
</CardGroup>