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
4. Push to main – the GitHub Action auto-generates your README.md

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:

npx readme-aura init

Then preview locally:

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/ folder as --template and init will fetch its readme.source.md directly from GitHub and write it to your project:

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):

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

• 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 <img> instead of a block. Consecutive inline blocks are automatically joined on one line. Add align=center to center-align the whole group inside <p align="center">
• 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 <a> tag
inline	flag	–	Render as an inline <img> instead of a block paragraph. Consecutive inline blocks are automatically joined on one line
align	center	left	right

Example — centered row of social buttons:

```aura width=120 height=44 link="https://github.com/you" inline align=center
<SocialMediaButton ... />
` `` `
```aura width=138 height=44 link="https://x.com/you" inline align=center
<SocialMediaButton ... />
` `` `

Output in README.md:

<p align="center">
<a href="https://github.com/you"><img src="./assets/component-0.svg" width="120" height="44" /></a><a href="https://x.com/you"><img src="./assets/component-1.svg" width="138" height="44" /></a>
</p>

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 <style> 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.

Limitations: No JavaScript, no SMIL. GitHub strips scripts but supports CSS animations. Prefer transform and opacity for best compatibility.

Tech Stack

If You Use readme-aura

• Add the topic: Consider adding the readme-aura topic to your repository so others can discover it.

License

MIT