· Back to LIBRE.TOWN · Back to DEVELOPMENT ·

LibreRing logo


This is LibreRing, a simple-to-use webring script!

What is a webring?

Before search engines became ubiquitous and before people socialized largely on centralized social media, it was somewhat hard to build a community and find personal homepages of people who shared your interests. That is when webrings first became a thing: imagine a bunch of people all standing in a circle holding hands: each person has one other person to their left, and one to their right. This way, you would be able to "go through the ring" by following each player's links to their neighbors until you loop all the way back around. This, but digitally, is what webrings are: every member site has a link to the previous and the next site in the chain, so people with common interests can link up and support each other in a big ring.

In the web revival, webrings have experienced a renaissance, and plenty of communities and fandoms now organize using webrings. Unfortunately, most existing webring scripts either have technical issues, strange licensing terms or otherwise do not meet all expectations one might have. So, I set out to write my very own webring script from scratch to fix all of these issues, and this is the result.

Why LibreRing?

LibreRing is simple, contained in a single javascript file, it supports the XHTML standard, it uses the free LGPL license and is therefore completely free software and open-source, supports a random button and has both a text and a graphical version. What's not to love?

How do I set up a webring?

Setting up a webring is easy!

  1. Download the librering-template.js file by clicking right here.
  2. Rename the file to something of your own choice; preferably identifiable as your webring.
  3. Use your text editor's search and replace feature to replace all instances of WEBRINGNAME with a camel-case or lower-case version of your webring name. This is not visible to users, this is just for the code, so please do not use any spaces, special characters or other fancy features: if your webring is called "V3RY ¢00Ł WEBRınG", then please just use "veryCoolWebring" or "very_cool_webring" in order to not break the code.
  4. Replace the example URLs in the "member" array with your starting members, including your own site if you want to. Follow the directions in the next chapter to find out how to add someone to the webring.
  5. Replace the ring URL (the first of the six long URL definitions below that) with the URL of your webring. This will be the URL that the main badge or link leads to.
  6. Replace the example image URLs for the badges with links to your own graphics. It is important to use absolute locations here (e. g. "https://example.com/image.png", not relative links (e. g. "/image.png", because other sites will run the same code and they will not have local access to your server file system.
  7. (Optional) Change the error message that displays when the site has not been found in the webring with your own, custom error message.
  8. (Optional) Switch around, customize or otherwise modify the HTML that define what your webring display will eventually look like.
  9. (Optional) If you want a text-based instead of an image-based display, uncomment the else {} section at the very bottom as per instructions in the file, and comment the original else {} section above it.
  10. (Optional) To customize the style of the widget with CSS, you can use your site's CSS to style the div that has the same ID as your webring name, or use the style attribute to change around elements in the display individually.

When you have done all this, your webring is ready to go (although empty, and no site is yet in it).

How do I add someone to my webring?

Now, to add your own site or invite people to your new webring, follow the steps below every time someone wants to join:

  1. Add their full URL to the members array in the javascript file on your server, in the same way that the examples are laid out. Make sure you don't remove the commas at the end of every line but the last, otherwise the list breaks. This HAS TO BE the exact specific literal URL that they will put the display onto, without modification; otherwise it won't work.
  2. Ask them to add the following code to their website, of course replacing the placeholder WEBRINGNAME with the exact lower-case/camel-case webring name as defined when you created it earlier, and the other placeholder with wherever you host the javascript file of the webring itself:

<div id="WEBRINGNAME"></div>
<script type="text/javascript" src="YOUR .JS FILE URL HERE" />

Any questions? / Contact

If you want to contact me for any reason including support, bugs or license issues, please mail me at LibreTown@proton.me. I can also help you set a LibreRing up. :]

Badge: LGPLv3 license