Docs
Every Mark image is a URL. Put it in an <img> or Markdown image and it renders, with no install, no account and no token. Build one visually in the studio, or use the reference below.
Quick start
- Pick a URL below or build one in the studio.
- Paste it into your README as
. - Commit. GitHub renders it.
Banner: /api/v1/mark/hero
| Param | Values | Default |
|---|---|---|
text, desc | Title and subtitle. Use -nl- for a new line. | — |
type | Style: waving aurora mesh spotlight grid minimal terminal transparent | waving |
theme | dark light ocean sunset forest grape mono paper | dark |
color | One colour, or gradient stops like 0:0F172A,50:5B8CFF,100:FF8A3D (used when no theme is set; a dark first stop becomes the background). gradient picks a theme from the text. | — |
layout | default (centered) left | default |
animation | ambient (the light drifts) fade rise type (play once) none | ambient |
font | sans mono | sans |
width, height | Pixels, up to 1600 × 900. Type scales with the canvas (1280×640 makes a social preview). | 880, 220 |
transparent draws text only, in GitHub's text colours for the viewer's light or dark scheme. Older names (plasma, constellation, tokyonight, glitch, plate, …) still render: each maps to the closest style, theme, motion or layout above.
Badge: /badge/{label}-{message}-{color} and /static/v1
Uses shields.io static-badge syntax: -- is a dash, __ is an underscore, _ is a space, and {message}-{color} alone drops the label.
| Param | Values | Default |
|---|---|---|
text, desc | Title and subtitle. Use -nl- for a new line. | — |
type | Style: waving aurora mesh spotlight grid minimal terminal transparent | waving |
theme | dark light ocean sunset forest grape mono paper | dark |
color | One colour, or gradient stops like 0:0F172A,50:5B8CFF,100:FF8A3D (used when no theme is set; a dark first stop becomes the background). gradient picks a theme from the text. | — |
layout | default (centered) left | default |
animation | ambient (the light drifts) fade rise type (play once) none | ambient |
font | sans mono | sans |
width, height | Pixels, up to 1600 × 900. Type scales with the canvas (1280×640 makes a social preview). | 880, 220 |
Score: /api/v1/mark/score
label, value, max (default 100), style, logo, color (overrides the automatic grade), theme.
A progress ring and automatic color grading (red → bright green) from value and max.
Typing text: /typing
The same parameters as readme-typing-svg: lines (separated by ;), font, weight, size, color, background, center, vCenter, multiline, width, height, duration, pause, repeat, random, letterSpacing, separator, plus caret (default true; caret=false drops the blinking caret). Under prefers-reduced-motion the image shows the fully typed first line instead of moving.
Tech icons: /icons
i (or icons): comma-separated skill-icons ids or Simple Icons slugs. theme is dark or light. perline is 1–50 (default 15). The native row is /api/v1/mark/strip?icons=….
3,400+ Simple Icons brands and every skill-icons id.
GitHub cards
github-readme-stats parameters: username, theme, show_icons, hide, hide_title, hide_rank, hide_border, border_radius, title_color, text_color, icon_color, bg_color, border_color, custom_title, card_width, layout (normal compact donut donut-vertical pie), langs_count, exclude_repo. The native routes are /api/v1/card/{stats|langs|streak|repo|stars}. Trophies (/trophy, or /?username=) take github-profile-trophy's theme, column, row, margin-w, margin-h, no-bg, no-frame, title and rank.
Live cards are cached on the server (about 4 hours) and at the edge. They are served stale while they refresh, and stale when GitHub is unavailable.
Live badges
| Source | Paths |
|---|---|
| GitHub | /github/{stars,forks,license,last-commit}/{owner}/{repo}, /github/v/release/{owner}/{repo}, /github/actions/workflow/status/{owner}/{repo}/{file} (?branch=, ?event=) |
| npm | /npm/{v,dm,dw,dt,l}/{package} (scoped too) |
| pub.dev | /pub/{v,likes,points,dm}/{package} |
| Packagist | /packagist/{v,dm,dd,dt}/{vendor}/{package} |
| Bundlephobia | /bundlephobia/{min,minzip}/{package} |
| Chrome Web Store | /chrome-web-store/{v,users,rating,stars,rating-count}/{id} |
Star history: /svg
A star-history.com URL works with only the host changed. GitHub shares star dates only with the people who can manage a repository, so the chart draws a curve for repositories Mark's server can read; for any other repository it shows today's total.
Profile card and deploy badge
/api/v1/mark/profile?text=Name&desc=Tagline, with theme, color, type (an art background), width and height.
/api/v1/mark/deploy?service=name renders a "deployed on Sylphx" badge.
Switch by changing the host
Mark reads the URL formats you already use. Keep the path and query, change the host:
| You have | Change it to |
|---|---|
img.shields.io/badge/build-passing-brightgreen | mark.sylphx.com/badge/build-passing-brightgreen |
img.shields.io/github/stars/owner/repo | mark.sylphx.com/github/stars/owner/repo |
img.shields.io/npm/v/package | mark.sylphx.com/npm/v/package |
capsule-render.vercel.app/api?type=waving&text=Hi | mark.sylphx.com/api?type=waving&text=Hi |
skillicons.dev/icons?i=rust,ts | mark.sylphx.com/icons?i=rust,ts |
readme-typing-svg.demolab.com?lines=Hello;World | mark.sylphx.com/?lines=Hello;World |
github-readme-stats.vercel.app/api?username=you | mark.sylphx.com/api?username=you |
github-readme-stats.vercel.app/api/top-langs?username=you | mark.sylphx.com/api/top-langs?username=you |
github-readme-stats.vercel.app/api/pin?username=you&repo=r | mark.sylphx.com/api/pin?username=you&repo=r |
streak-stats.demolab.com?user=you | mark.sylphx.com/?user=you |
github-profile-trophy.vercel.app/?username=you | mark.sylphx.com/?username=you |
api.star-history.com/svg?repos=owner/repo | mark.sylphx.com/svg?repos=owner/repo |
Speed and reliability
Append .svg to any image path and it is served from the edge cache. Static images are immutable and cache for a year; live cards refresh about every four hours, are served stale while they refresh, and stay up when the upstream service is down. Every response has a strong ETag and answers If-None-Match with 304. Unknown parameters fall back to defaults, so a Mark URL never shows a broken image.
For tools and agents
GET /api (with no image query) returns the JSON endpoint index; GET /api/v1/catalog returns every form, style, theme, icon id and limit; GET /health returns the deployed revision.
/api/v1/mark/api/v1/mark/{form}/badge/{label}-{message}-{color}/icons?i={ids}/typing?lines={a};{b}/?lines={a};{b}/api?type={art}&text={text}/static/v1/api/v1/card/{stats|langs|streak|repo|stars}?username=/api?username=/api/top-langs?username=/api/pin?username=&repo=/streak?user=/trophy?username=/github/{stars|forks|license|last-commit}/{owner}/{repo}/github/v/release/{owner}/{repo}/npm/{v|dm|dw|dt|l}/{package}/github/actions/workflow/status/{owner}/{repo}/{file}/pub/{v|likes|points|dm}/{package}/packagist/{v|dm|dd|dt}/{vendor}/{package}/bundlephobia/{min|minzip}/{package}/chrome-web-store/{v|users|rating|stars|rating-count}/{id}/svg?repos={owner}/{repo}/api/v1/catalog/health
Fair use
Free for every README and site. Automated bulk traffic is not; see the acceptable use policy.