Documentation
How to put a site in the ring, how to embed the widget, how points and clicks work — and what you can do with the open API.
Quick start
From zero to a site in the ring — four steps and a couple of minutes.
Widget for your site
One line of code. Dark or light theme, three sizes.
Three modes
pill— pill — a compact pill: site name, brand dot and prev/next arrows.card— card — a 280px card with a preview, description and links.minimal— minimal — just the name and arrows, nothing else.
Attributes
site— site — the short link of the site. Without it the widget finds the site by the page domain.mode— mode — pill (default), card or minimal.theme— theme — auto (default), dark or light.kind— kind — browse just this sub-ring by category (personal site, blog, tool...).
Dark and light themes are handled automatically: auto follows the system.
No JS? Then just two links:
Badge
Rules
- The site is yours: a personal site, blog, project, portfolio, wiki. Not a one-button "buy now" landing.
- A link back to the ring must be on the site. Without it the ring falls apart.
- 18+ is fine but must be marked. Such sites stay blurred by default.
- Spam, scams, malware, hate speech — out. Come back with a new site.
- Changing the site url requires an admin request.
Please tell us: a short report helps keep the ring clean. Report abuse →
Points
Every site has a score from 0 to 100. It is not a vote — it is the health of the card: the fuller the site and the livelier its link to the ring, the higher the score.
The site answers a request — 40 points. A 403 from Cloudflare counts as alive.
A youring widget or ring links were found on the page — 30 points.
Ring links point where they should — 15 points.
The profile is complete: name, description, tags, icon — 15 points.
Grades: S ≥ 95 · A ≥ 80 · B ≥ 60 · C ≥ 40 · D ≥ 20 · F < 20.
Points are shown in the dashboard for each of your sites and set the place on the leaderboard. Leaders →
Clicks
A click is a visit to a site through the ring. It is counted once per entry and summed per site.
- A visit through the short link /your-slug and through /your-slug/next, /prev, /random.
- A click on the planet, the card or the widget button in the ring.
- Repeated back-to-back clicks from one device do not inflate the counter.
The ring as a system
A living ring is more than prev/next. Here is what else youring can do.
- A link back is required to rank — If a site does not link back to the ring (the widget or prev/next links), it stays visible and browsable as usual — but it does not make it into the points top. That keeps the top honest about real reciprocity. /lead →
- One subscription for every blog — The /feed page and the OPML bundle /api/v1/ring/opml gather every member feed: add one file to your RSS reader and read the whole ring. /feed →
- Constellation map — On /map every star is a site: faint lines are the ring order, bright ones are real links members make to each other. Sites with no link back get a red dot. /map →
- Sub-rings by category — On /kinds the ring is split by category, and each sub-ring can be browsed on its own: add ?kind= to the prev/next links or the widget to page through just your sub-ring. /kinds →
API and docs
Open JSON API: ring, neighbours, random site, stats, health. Live widget generator inside the docs.
FAQ
Is it free?
Yes. The ring runs on its own server, with no ads and no paid tiers.
Where do I put the widget?
Anywhere links to neighbours fit: the footer, a “friends” block, a sidebar. You can keep the script async.
What if I have no JavaScript?
Two plain links, prev and next, are enough — they are the ring. The widget is just handier.
Can I have several sites?
Yes, as many as you like. Each has its own slug, widget and points.
How do I change the address?
Only through an admin request from the dashboard: the address is reviewed by hand so the ring is not broken.
How do I leave the ring?
Instantly, with a button in the dashboard. To return, apply again.
Found spam or a bad site?
Please tell us: a short report helps keep the ring clean.
Useful links
Want to add your site?
Put your site in the ring — and hop through others in one click.