yuring
Docs

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.

Sign in with Telegram — no password.
Add your site: name, url, description, tags. The favicon is fetched for you.
Put the widget on your site, or at least two links: prev and next.
Wait for approval — usually a couple of minutes.

Widget for your site

One line of code. Dark or light theme, three sizes.

<youring-ring site="your-slug" mode="pill"></youring-ring> <script src="https://youring.roxera.net/widget.js" async></script>

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:

<a href="https://youring.roxera.net/your-slug/prev">← prev</a> <a href="https://youring.roxera.net/your-slug/next">next →</a>

Badge

youring
<a href="https://youring.roxera.net/your-slug"><img src="https://youring.roxera.net/badge/your-slug.svg" width="320" height="64" alt="youring"></a>

Rules

  1. The site is yours: a personal site, blog, project, portfolio, wiki. Not a one-button "buy now" landing.
  2. A link back to the ring must be on the site. Without it the ring falls apart.
  3. 18+ is fine but must be marked. Such sites stay blurred by default.
  4. Spam, scams, malware, hate speech — out. Come back with a new site.
  5. 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.

+40

The site answers a request — 40 points. A 403 from Cloudflare counts as alive.

+30

A youring widget or ring links were found on the page — 30 points.

+15

Ring links point where they should — 15 points.

+15

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.

GET /api/v1/ring GET /api/v1/ring/{slug} GET /api/v1/ring/opml GET /api/v1/random GET /api/v1/search?q=... GET /api/v1/stats GET /api/v1/health GET /badge/{slug}.svg

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.

Add your site