🌿 garlic 🧄 garden 🌿

what is onionring.js?

it's quite likely you got to this page through a link on someone's webring widget. onionring.js is the script that makes that widget work - it's just a few javascript files that help you create and manage a webring, even (or especially!) if you don't know anything about coding (if you know your stuff, you can just skip to the download section)

onionring.js and the files that make it up are licensed under the cooperative non-violent license (CNPL) v7+, which means, roughly, that anyone is allowed to download, change and share the files as long as you give credit, disclaim what changes you've made, and don't use them to violent, coercive or discriminatory ends.

what's a webring?

imagine yourself and a bunch of friends or people you share an interest with, in a circle, all holding hands. everyone's left hand links them to the previous person in the circle, and everyone's right hand links them to the next person. now imagine that you're a website, and your hands are hyperlinks. that's a webring! and if you click 'next' on every site, you'll eventually get back to where you started.

back when search engines weren't very good, this was a useful way to connect your website with more users, and users with more websites that have similar content to stuff they already like. people still like to use them now because 1) we're all nostalgic for a simpler time, 2) they feel like a more honest and organic way to discover content on the internet, and 3) search engines are starting to be not very good again.

how do you make one?

it's as simple as everyone agreeing to link to each other in a circular fashion.

well, ok, there are some tricky parts. how do you decide which order people are in the ring? what happens when new people want to join or leave? what if you want to go to a random site, or see everyone in the list? suddenly it doesn't seem very simple at all! the onionring.js script is one solution to that. there are others, but we designed this one to be as simple and versatile as possible.

how do i use the script?

first thing's first: everyone who wants to be in the ring should at the very least have a site where they can directly edit the html. one person then needs to agree to be the manager of the ring.

the manager should:

  1. upload the script files somewhere - that's onionring-variables.js, onionring-widget.js, and onionring.css (and optionally onionring-index.js, see the specific section about that)
  2. edit the onionring-variables.js file so that
    • the sites list contains the full URL of every site in the ring (ie it should include the http:// bit)
    • the ringName equals the name of your webring - this will show up in the widget as "part of the ringName webring"
    • ringID is some uniquely identifiable value - this is so there's no conflict if a person is part of multiple rings which use this code
  3. edit the onionring.css file so that all instances of #webringid equal the same as the ringID you set. make sure it still has the # at the front, though!

everyone in the ring (including the manager) should:

put the following code on their webpage where they want the widget to appear:

<div id='webringid'>
<script type="text/javascript" src="scriptURL/onionring-variables.js"></script>
<script type="text/javascript" src="scriptURL/onionring-widget.js"></script>
...where 'scriptURL' is the full URL of the place where the manager is hosting the onionring-widget.js and onionring-variables.js files, and 'webringid' is the same as the ringID the manager decided on.

they might also want to include this:

<link rel="stylesheet" href="scriptURL/onionring.css">
in the <head></head> part of their page to apply some basic styling to the widget. again, 'scriptURL' should be the URL where the onionring.css file is hosted - it'll probably be the same as the one used in the widget source.

that's it! that's as much as you need to do to get it working.

how do i use the index?

the manager should create a page to be used as the index. it might be good to write a little description of what the ring's about - for example is there a theme? what kind of content can you expect to find? can anyone join, or is it just you and your friends?

then all you have to do is include the following:

<div id='index'>
<script type="text/javascript" src="scriptURL/onionring-variables.js"></script>
<script type="text/javascript" src="scriptURL/onionring-index.js"></script>

at the moment all this does is display a bulleted list of the URLs in the sites list. in future, we might make it possible to include stuff like icons, owner names and descriptions.

what if i want it to look different?

you can make it look like basically anything you want if you're willing to touch a little bit of code. onionring.js uses html to structure the widget and css to make it look pretty.

if you're the manager you can change both the onionring.css file and the html output of the onionring-widget.js script however you want. changes you make here will apply to everyone in the ring (except if they're overriding the css with their own). we've tried to include comments in the files explaining what they do, but you'll also want to know some basic stuff about html and css if you don't already.

if you're not the manager, you can override the default css by selecting #webringid (or whatever your manager has called it) wherever you do your css stuff. this might be in a separate css file or inside some <style></style> brackets. you can learn how to work with css here, and you can also download the default onionring.css file down below if you want to understand what specific elements to select.

where can i get the script?

you can also click here to down everything in a zip file.


1st feb 2024 - not a technical update, more like news - or something that's news to us, anyway. we discovered last night that this is, apparently, one of the most popular webring solutions out there. after posting it in 2020, we mostly forgot about it, and never heard about anyone using it. we didn't know about this whole indie web movement. but we're grateful that so many people have found a use for it, or even used it as a basis to create something more useful for themselves. we're humbled to have helped so many communities, and committed to keeping this page up so we can help many more, even if it looks quiet on here.

24th nov 2020 - widget code now checks if the url it's on begins with the one in the list, rather than matching it exactly. this should allow you to put it in multiple places on your site, if you want.

9th nov 2020 - added ability to give widget a unique id to avoid conflicts and instructions on how to do that. pulled some of the css styling out of inline style tags and into the css file. made the script installation instructions clearer. added more detail and beginner's resources to styling section