https://github.com/collectioneur/readme-aura
Render React/JSX components as animated SVGs directly inside GitHub READMEs
https://github.com/collectioneur/readme-aura
awesome-readme github-portfolio github-profile-readme jsx-renderer portfolio profile-readme readme-aura readme-generator readme-template remarkjs satori
Last synced: about 1 month ago
JSON representation
Render React/JSX components as animated SVGs directly inside GitHub READMEs
- Host: GitHub
- URL: https://github.com/collectioneur/readme-aura
- Owner: collectioneur
- License: mit
- Created: 2026-03-07T17:22:58.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-06T10:33:19.000Z (2 months ago)
- Last Synced: 2026-04-06T12:25:09.107Z (2 months ago)
- Topics: awesome-readme, github-portfolio, github-profile-readme, jsx-renderer, portfolio, profile-readme, readme-aura, readme-generator, readme-template, remarkjs, satori
- Language: TypeScript
- Homepage: https://collectioneur.github.io/readme-aura/
- Size: 2.8 MB
- Stars: 40
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
[](https://www.npmjs.com/package/readme-aura)
Write custom **React/JSX components** directly inside your Markdown, and readme-aura will render them into beautiful SVGs that work on GitHub.
GitHub strips all JS and CSS from README files. This tool lets you bypass that limitation by compiling your designs into static SVG images at build time.
## How It Works
1. Run `npx readme-aura init` in your repo – creates workflow, source template, and audits `.gitignore`
2. Edit `readme.source.md` – add JSX components inside ` ```aura ` code blocks
3. Preview locally with `npx readme-aura build` – JSX gets rendered to SVG via [Vercel Satori](https://github.com/vercel/satori)
4. Push to `main` – the GitHub Action auto-generates your `README.md`
[](https://www.npmjs.com/package/readme-aura)
## Quick Start
Run one command in your repo – it creates the GitHub Actions workflow, a starter `readme.source.md`, and ensures `.gitignore` won't block generated files:
```bash
npx readme-aura init
```
Then preview locally:
```bash
npx readme-aura build
```
That's it. Push to `main` and the workflow will auto-generate your `README.md` on every push.
> `init` auto-detects profile repos (`username/username`) and picks the right template.
### Commands
| Command | Description |
|---------|-------------|
| `npx readme-aura init` | Scaffold workflow, source template, audit `.gitignore` |
| `npx readme-aura build` | Render ` ```aura ` blocks to SVG and generate `README.md` |
### Build Options
| Option | Default | Description |
|--------|---------|-------------|
| `-s, --source` | `readme.source.md` | Source markdown file |
| `-o, --output` | `README.md` | Output markdown file |
| `-a, --assets` | `.github/assets` | Directory for generated SVGs |
| `-f, --fonts-dir` | – | Custom fonts directory |
| `-g, --github-user` | auto-detect | GitHub username for stats |
| `-t, --github-token` | `$GITHUB_TOKEN` | Token for GitHub API |
### Init Options
| Option | Default | Description |
|--------|---------|-------------|
| `--template` | auto-detect | `profile`, `project`, or any example name (e.g. `DarkOrbs`) |
| `--force` | `false` | Overwrite existing files |
### Example Templates
Pass any example name from the [`examples/`](https://github.com/collectioneur/readme-aura/tree/main/examples) folder as `--template` and `init` will fetch its `readme.source.md` directly from GitHub and write it to your project:
```bash
npx readme-aura init --template DarkOrbs
npx readme-aura init --template PurpleGlow
npx readme-aura init --template LightOrbs
npx readme-aura init --template SocialMediaButton
```
No extra downloads, no local files needed — the template is pulled on the fly and placed in `readme.source.md`, ready to build. Run `npx readme-aura build` right after and you get a working README.
## What `init` Creates
The `init` command sets up everything you need:
**`.github/workflows/readme-aura.yml`** – GitHub Action that rebuilds your README on every push to `main` and on a daily schedule (to keep GitHub stats fresh):
```yaml
name: Generate README
on:
push:
branches: [main]
paths: ['readme.source.md']
schedule:
- cron: '0 6 * * *'
workflow_dispatch:
permissions:
contents: write
jobs:
generate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Generate README
uses: collectioneur/readme-aura@main
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
```
**`readme.source.md`** – Starter template with example ` ```aura ` blocks, customized for your repo type.
**`.gitignore` audit** – Ensures `.github/assets/`, `.github/workflows/`, `README.md`, and `readme.source.md` are not ignored.
## Features
[](https://www.npmjs.com/package/readme-aura)
* **Write React/JSX** – Use familiar `style={{ }}` syntax with flexbox, gradients, shadows
* **Powered by Satori** – Vercel's engine converts JSX to SVG without a browser
* **Custom Fonts** – Inter bundled by default, bring your own via `--fonts-dir`
* **Meta Syntax** – Control dimensions: ` ```aura width=800 height=400 `
* **Clickable Images** – Add a link: ` ```aura link="https://example.com" ` – clicking the image opens the URL
* **Inline Blocks** – Add `inline` to render as `![]()
` instead of a block. Consecutive inline blocks are automatically joined on one line. Add `align=center` to center-align the whole group inside `
`
* **GitHub-Compatible** – Output is pure Markdown + SVG, works everywhere
### Block Parameters
All parameters are written directly on the opening fence line of an ` ```aura ` block:
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `width` | number | `800` | Width of the rendered SVG in pixels |
| `height` | number | `400` | Height of the rendered SVG in pixels |
| `link` | string | – | URL – wraps the image in a clickable `` tag |
| `inline` | flag | – | Render as an inline `![]()
` instead of a block paragraph. Consecutive inline blocks are automatically joined on one line |
| `align` | `center` | `left` | `right` | – | Wrap a group of consecutive inline blocks in ``. Only meaningful when `inline` is set |
**Example — centered row of social buttons:**
````markdown
```aura width=120 height=44 link="https://github.com/you" inline align=center
` `` `
```aura width=138 height=44 link="https://x.com/you" inline align=center
` `` `
````
Output in README.md:
```html
```
> The `align` value is read from the first block in the group that declares it. Blocks without `align` still join the same group — only the wrapper is controlled by the flag.
## Components
readme-aura ships with ready-to-use components you can drop into any ` ```aura ` block - no imports needed. They are automatically available in the JSX context.
### SocialMediaButton
Code
Result
<SocialMediaButton
icon="***image URI***"
text="readme-aura"
backgroundColor="#111111"
width={150}
height={44}
gradientStops={[
{ offset: '0%', color: '#ffffff' },
{ offset: '10%', color: '#111111' },
{ offset: '50%', color: '#eeeeee' },
{ offset: '60%', color: '#1af4ff' },
{ offset: '80%', color: '#111111' },
{ offset: '100%', color: '#555555' },
]}
iconSize="30"
/>
| Prop | Default | Description |
|------|---------|-------------|
| `icon` | — | Icon image path or URL |
| `text` | — | Button label |
| `backgroundColor` | `#111111` | Fill color |
| `textColor` | `#f5f5f5` | Label color |
| `fontSize` | `13` | Label font size |
| `width` / `height` | `150` / `40` | Button dimensions |
| `iconSize` | `18` | Icon dimensions |
| `borderColor` | `#AAAAAA` | Outer border color |
| `gradientStops` | holographic | Animated gradient colors |
| `gradientStrokeWidth` | `2` | Gradient border thickness |
## Animations
You can add **CSS-based SVG animations** using the `` injection mechanism. Satori renders a static frame at build time; the browser animates the SVG when it is displayed (e.g. on GitHub).
**How it works:** Add a `<style>` block in your JSX. Define `@keyframes` and apply them to elements by `#id` or `.class`. The renderer extracts and injects the CSS into the final SVG.
**Animatable properties:** `transform` (translate, scale, rotate), `opacity`, `fill`, and `stroke-dasharray`/`stroke-dashoffset`. Layout properties (`width`, `height`, `margin`) are unreliable.
**Targeting:** Use `id` on SVG elements (`<ellipse id="glow">`, `<g id="group">`) and reference them in CSS: `#glow { animation: pulse 2s infinite; }`. Raw SVG elements preserve `id`; Satori-rendered HTML may not always preserve `className`.
[](https://www.npmjs.com/package/readme-aura)
**Limitations:** No JavaScript, no SMIL. GitHub strips scripts but supports CSS animations. Prefer `transform` and `opacity` for best compatibility.
## Tech Stack
[](https://www.npmjs.com/package/readme-aura)
## If You Use readme-aura
* **Add the topic:** Consider adding the [readme-aura](https://github.com/topics/readme-aura) topic to your repository so others can discover it.
## License
MIT