{"id":47611874,"url":"https://github.com/collectioneur/readme-aura","last_synced_at":"2026-05-10T09:15:30.005Z","repository":{"id":342913439,"uuid":"1175415821","full_name":"collectioneur/readme-aura","owner":"collectioneur","description":"Render React/JSX components as animated SVGs directly inside GitHub READMEs","archived":false,"fork":false,"pushed_at":"2026-04-06T10:33:19.000Z","size":2934,"stargazers_count":40,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-06T12:25:09.107Z","etag":null,"topics":["awesome-readme","github-portfolio","github-profile-readme","jsx-renderer","portfolio","profile-readme","readme-aura","readme-generator","readme-template","remarkjs","satori"],"latest_commit_sha":null,"homepage":"https://collectioneur.github.io/readme-aura/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/collectioneur.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-07T17:22:58.000Z","updated_at":"2026-04-06T10:33:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/collectioneur/readme-aura","commit_stats":null,"previous_names":["collectioneur/readme-aura"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/collectioneur/readme-aura","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/collectioneur%2Freadme-aura","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/collectioneur%2Freadme-aura/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/collectioneur%2Freadme-aura/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/collectioneur%2Freadme-aura/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/collectioneur","download_url":"https://codeload.github.com/collectioneur/readme-aura/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/collectioneur%2Freadme-aura/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32042293,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T00:18:06.643Z","status":"online","status_checked_at":"2026-04-20T02:00:06.527Z","response_time":94,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["awesome-readme","github-portfolio","github-profile-readme","jsx-renderer","portfolio","profile-readme","readme-aura","readme-generator","readme-template","remarkjs","satori"],"created_at":"2026-04-01T20:31:44.808Z","updated_at":"2026-05-10T09:15:29.999Z","avatar_url":"https://github.com/collectioneur.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![readme-aura-component-0](./.github/assets/readme-aura-component-0-e38e8467.svg \"Generated by readme-aura\")](https://www.npmjs.com/package/readme-aura)\n\nWrite custom **React/JSX components** directly inside your Markdown, and readme-aura will render them into beautiful SVGs that work on GitHub.\n\nGitHub 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.\n\n## How It Works\n\n1. Run `npx readme-aura init` in your repo – creates workflow, source template, and audits `.gitignore`\n2. Edit `readme.source.md` – add JSX components inside ` ```aura ` code blocks\n3. Preview locally with `npx readme-aura build` – JSX gets rendered to SVG via [Vercel Satori](https://github.com/vercel/satori)\n4. Push to `main` – the GitHub Action auto-generates your `README.md`\n\n[![readme-aura-component-1](./.github/assets/readme-aura-component-1-2cc164cb.svg \"Generated by readme-aura\")](https://www.npmjs.com/package/readme-aura)\n\n## Quick Start\n\nRun one command in your repo – it creates the GitHub Actions workflow, a starter `readme.source.md`, and ensures `.gitignore` won't block generated files:\n\n```bash\nnpx readme-aura init\n```\n\nThen preview locally:\n\n```bash\nnpx readme-aura build\n```\n\nThat's it. Push to `main` and the workflow will auto-generate your `README.md` on every push.\n\n\u003e `init` auto-detects profile repos (`username/username`) and picks the right template.\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `npx readme-aura init` | Scaffold workflow, source template, audit `.gitignore` |\n| `npx readme-aura build` | Render ` ```aura ` blocks to SVG and generate `README.md` |\n\n### Build Options\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `-s, --source` | `readme.source.md` | Source markdown file |\n| `-o, --output` | `README.md` | Output markdown file |\n| `-a, --assets` | `.github/assets` | Directory for generated SVGs |\n| `-f, --fonts-dir` | – | Custom fonts directory |\n| `-g, --github-user` | auto-detect | GitHub username for stats |\n| `-t, --github-token` | `$GITHUB_TOKEN` | Token for GitHub API |\n\n### Init Options\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `--template` | auto-detect | `profile`, `project`, or any example name (e.g. `DarkOrbs`) |\n| `--force` | `false` | Overwrite existing files |\n\n### Example Templates\n\nPass 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:\n\n```bash\nnpx readme-aura init --template DarkOrbs\nnpx readme-aura init --template PurpleGlow\nnpx readme-aura init --template LightOrbs\nnpx readme-aura init --template SocialMediaButton\n```\n\nNo 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.\n\n## What `init` Creates\n\nThe `init` command sets up everything you need:\n\n**`.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):\n\n```yaml\nname: Generate README\non:\n  push:\n    branches: [main]\n    paths: ['readme.source.md']\n  schedule:\n    - cron: '0 6 * * *'\n  workflow_dispatch:\n\npermissions:\n  contents: write\n\njobs:\n  generate:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      - name: Generate README\n        uses: collectioneur/readme-aura@main\n        with:\n          github_token: ${{ secrets.GITHUB_TOKEN }}\n```\n\n**`readme.source.md`** – Starter template with example ` ```aura ` blocks, customized for your repo type.\n\n**`.gitignore` audit** – Ensures `.github/assets/`, `.github/workflows/`, `README.md`, and `readme.source.md` are not ignored.\n\n## Features\n\n[![readme-aura-component-2](./.github/assets/readme-aura-component-2-1b11d685.svg \"Generated by readme-aura\")](https://www.npmjs.com/package/readme-aura)\n\n* **Write React/JSX** – Use familiar `style={{ }}` syntax with flexbox, gradients, shadows\n* **Powered by Satori** – Vercel's engine converts JSX to SVG without a browser\n* **Custom Fonts** – Inter bundled by default, bring your own via `--fonts-dir`\n* **Meta Syntax** – Control dimensions: ` ```aura width=800 height=400 `\n* **Clickable Images** – Add a link: ` ```aura link=\"https://example.com\" ` – clicking the image opens the URL\n* **Inline Blocks** – Add `inline` to render as `\u003cimg\u003e` instead of a block. Consecutive inline blocks are automatically joined on one line. Add `align=center` to center-align the whole group inside `\u003cp align=\"center\"\u003e`\n* **GitHub-Compatible** – Output is pure Markdown + SVG, works everywhere\n\n### Block Parameters\n\nAll parameters are written directly on the opening fence line of an ` ```aura ` block:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `width` | number | `800` | Width of the rendered SVG in pixels |\n| `height` | number | `400` | Height of the rendered SVG in pixels |\n| `link` | string | – | URL – wraps the image in a clickable `\u003ca\u003e` tag |\n| `inline` | flag | – | Render as an inline `\u003cimg\u003e` instead of a block paragraph. Consecutive inline blocks are automatically joined on one line |\n| `align` | `center` | `left` | `right` | – | Wrap a group of consecutive inline blocks in `\u003cp align=\"...\"\u003e`. Only meaningful when `inline` is set |\n\n**Example — centered row of social buttons:**\n\n````markdown\n```aura width=120 height=44 link=\"https://github.com/you\" inline align=center\n\u003cSocialMediaButton ... /\u003e\n` `` `\n```aura width=138 height=44 link=\"https://x.com/you\" inline align=center\n\u003cSocialMediaButton ... /\u003e\n` `` `\n````\n\nOutput in README.md:\n\n```html\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://github.com/you\"\u003e\u003cimg src=\"./assets/component-0.svg\" width=\"120\" height=\"44\" /\u003e\u003c/a\u003e\u003ca href=\"https://x.com/you\"\u003e\u003cimg src=\"./assets/component-1.svg\" width=\"138\" height=\"44\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n```\n\n\u003e 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.\n\n## Components\n\nreadme-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.\n\n### SocialMediaButton\n\n\u003ctable style=\"width: 100%; table-layout: fixed; border-collapse: collapse;\"\u003e\n  \u003ccolgroup\u003e\n    \u003ccol style=\"width: 38%;\" /\u003e\n    \u003ccol style=\"width: 62%;\" /\u003e\n  \u003c/colgroup\u003e\n  \u003cthead\u003e\n    \u003ctr\u003e\n      \u003cth style=\"text-align: left;\"\u003eCode\u003c/th\u003e\n      \u003cth style=\"text-align: left;\"\u003eResult\u003c/th\u003e\n    \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd style=\"vertical-align: top; padding-right: 12px;\"\u003e\n        \u003cpre style=\"font-size: 9px; line-height: 1.3; margin: 0; white-space: pre-wrap; overflow-wrap: anywhere; word-break: break-word;\"\u003e\u003ccode\u003e\u0026lt;SocialMediaButton\n  icon=\"***image URI***\"\n  text=\"readme-aura\"\n  backgroundColor=\"#111111\"\n  width={150}\n  height={44}\n  gradientStops={[\n    { offset: '0%', color: '#ffffff' },\n    { offset: '10%', color: '#111111' },\n    { offset: '50%', color: '#eeeeee' },\n    { offset: '60%', color: '#1af4ff' },\n    { offset: '80%', color: '#111111' },\n    { offset: '100%', color: '#555555' },\n  ]}\n  iconSize=\"30\"\n/\u0026gt;\u003c/code\u003e\u003c/pre\u003e\n      \u003c/td\u003e\n      \u003ctd style=\"vertical-align: middle; text-align: center;\"\u003e\n        \u003ca href=\"https://collectioneur.github.io/readme-aura/\"\u003e\u003cimg src=\"assets/readme-aura-button.svg\" alt=\"SocialMediaButton\" width=\"150\" /\u003e\u003c/a\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n| Prop | Default | Description |\n|------|---------|-------------|\n| `icon` | — | Icon image path or URL |\n| `text` | — | Button label |\n| `backgroundColor` | `#111111` | Fill color |\n| `textColor` | `#f5f5f5` | Label color |\n| `fontSize` | `13` | Label font size |\n| `width` / `height` | `150` / `40` | Button dimensions |\n| `iconSize` | `18` | Icon dimensions |\n| `borderColor` | `#AAAAAA` | Outer border color |\n| `gradientStops` | holographic | Animated gradient colors |\n| `gradientStrokeWidth` | `2` | Gradient border thickness |\n\n## Animations\n\nYou can add **CSS-based SVG animations** using the `\u003cstyle\u003e` injection mechanism. Satori renders a static frame at build time; the browser animates the SVG when it is displayed (e.g. on GitHub).\n\n**How it works:** Add a `\u003cstyle\u003e` 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.\n\n**Animatable properties:** `transform` (translate, scale, rotate), `opacity`, `fill`, and `stroke-dasharray`/`stroke-dashoffset`. Layout properties (`width`, `height`, `margin`) are unreliable.\n\n**Targeting:** Use `id` on SVG elements (`\u003cellipse id=\"glow\"\u003e`, `\u003cg id=\"group\"\u003e`) and reference them in CSS: `#glow { animation: pulse 2s infinite; }`. Raw SVG elements preserve `id`; Satori-rendered HTML may not always preserve `className`.\n\n[![readme-aura-component-3](./.github/assets/readme-aura-component-3-65da8580.svg \"Generated by readme-aura\")](https://www.npmjs.com/package/readme-aura)\n\n**Limitations:** No JavaScript, no SMIL. GitHub strips scripts but supports CSS animations. Prefer `transform` and `opacity` for best compatibility.\n\n## Tech Stack\n\n[![readme-aura-component-4](./.github/assets/readme-aura-component-4-bba5e99b.svg \"Generated by readme-aura\")](https://www.npmjs.com/package/readme-aura)\n\n## If You Use readme-aura\n\n* **Add the topic:** Consider adding the [readme-aura](https://github.com/topics/readme-aura) topic to your repository so others can discover it.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcollectioneur%2Freadme-aura","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcollectioneur%2Freadme-aura","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcollectioneur%2Freadme-aura/lists"}