Stylish Readme

Style your README with beautiful, dynamic SVG widgets

Dynamic SVG widgets for GitHub profiles, README files, portfolio pages, and documentation.

No API keys. No client-side JavaScript. No complicated setup.

Important

⭐ Fork • Build • Contribute

Before opening your first contribution:

• ⭐ Star this repository
• 🍴 Fork the repository
• 🚀 Start building
• 💡 Submit your improvements

Every contribution, big or small, is appreciated.

Overview

Stylish Readme renders widgets as standalone SVG images. Since GitHub supports SVG rendering natively inside Markdown image tags, widgets update automatically whenever your profile or README is viewed.

Profile Cards Developer identity

Now Playing Music status

Live Time Real-time clocks

Streaks Activity tracking

Features

• Dynamic SVG widgets
• Works directly inside GitHub README files
• Lightweight and fast
• No API keys required
• Fully customizable through URL parameters
• Multiple built-in themes
• Serverless-first architecture
• Easy self-hosting

Widget Documentation & Examples

Copy any snippet below into your README and customize the query parameters to match your profile.

1. Developer Profile Card

Combines your avatar, role, bio, skills, and handle into a clean profile header.

Theme: Paper | Sharp edges (radius=0)

![Profile Card](https://readmeme.eu.cc/api/profile.svg?avatar=https%3A%2F%2Fgithub.com%2Fcu-sanjay.png&name=Sanjay&role=Full-Stack+Developer&bio=Building+cool+things+with+code+n+coffee.&skills=HTML%2CJS%2CREACT%2CNODE%2CPYTHON%2CGIT%2CSQL&handle=cu-sanjay&theme=paper&radius=0)

Theme: Paper | Soft edges (radius=12)

![Profile Card](https://readmeme.eu.cc/api/profile.svg?avatar=https%3A%2F%2Fgithub.com%2Fcu-sanjay.png&name=Sanjay&role=Full-Stack+Developer&bio=Building+cool+things+with+code+n+coffee.&skills=HTML%2CJS%2CREACT%2CNODE%2CPYTHON%2CGIT%2CSQL&handle=cu-sanjay&theme=paper&radius=12)

2. Now Playing Status

Theme: Terminal | YouTube Music

![Now Playing](https://readmeme.eu.cc/api/music.svg?theme=terminal&musicSong=Smells+Like+Teen+Spirit&musicArtist=Nirvana&musicListen=Now+Playing&musicPlatform=ytmusic)

Theme: Ink | SoundCloud

![Now Playing](https://readmeme.eu.cc/api/music.svg?theme=ink&musicSong=Tera+Intezaar&musicArtist=Rahat+Fateh+Ali+Khan&musicListen=On+Repeat&musicPlatform=soundcloud)

3. Live Local Time

Theme: Classic

![Local Time](https://readmeme.eu.cc/api/time.svg?theme=classic&timezone=Asia/Kolkata&timeFormat=24h&showSeconds=1&showDate=1&showDay=1&label=Local+Time)

Theme: Retro

![Local Time](https://readmeme.eu.cc/api/time.svg?theme=retro&timezone=America/New_York&timeFormat=12h&showSeconds=0&showDate=0&showDay=0&label=NYC)

4. Coding Streaks

![Coding Streak](https://readmeme.eu.cc/api/streak.svg?theme=crimson&startDate=2023-01-01&unit=days&customLabel=LeetCode+Grind&platform=leetcode)

5. Daily Quotes

![Daily Quote](https://readmeme.eu.cc/api/quote.svg?theme=ocean&quoteCategory=programming&label=Daily+Wisdom)

6. Location & Timezone

![Country Flag](https://readmeme.eu.cc/api/flag.svg?theme=forest&country=JP&label=Based+In)

![Timezone Banner](https://readmeme.eu.cc/api/timezone.svg?theme=ink&timezone=Europe/London&timeFormat=24h)

Parameter Reference

Global Parameters

Parameter	Description
theme	classic, paper, terminal, retro, ocean, crimson, forest, ink
label	Custom widget label
radius	Corner roundness (0 = sharp, 12 = soft)

Profile Card

• avatar
• name
• role
• bio
• skills
• handle

Music Status

• musicSong
• musicArtist
• musicPlatform
• musicListen

Time & Date

• timezone
• timeFormat
• showSeconds
• showDate
• showDay

Streaks

• startDate
• unit
• platform

Local Development

Clone the repository:

git clone https://github.com/cu-sanjay/stylish-readme.git
cd stylish-readme

Install dependencies:

npm install

Start the development server:

npm start

Open:

http://localhost:5000

The local widget workshop and preview environment will be available there.

Important

Serverless-First Architecture

Stylish Readme is intentionally designed as a lightweight, serverless-native project.

• Do not introduce persistent backend servers.
• Do not add server.js, Express servers, custom runtimes, or long-running processes.
• New features should be implemented using stateless logic compatible with edge and serverless deployments.
• Maintain fast cold starts and minimal infrastructure requirements.

Pull requests that introduce persistent server dependencies may not be accepted.

Contributing

Contributions are welcome.

Before opening a pull request:

1. Keep changes focused and minimal.
2. Follow the existing code style.
3. Test your widget locally.
4. Avoid breaking existing URL parameters.
5. Respect the serverless-first architecture.

For full contribution guidelines, see:

CONTRIBUTING.md