shogun-onion

Essential documentation for integrating and running the “Shogun Onion” webring. This project is 100% static (HTML/CSS/JS) and can be hosted anywhere.

Repository structure

• index.html — example hub page
• theme-toggle.js — dark/light theme toggle
• ring/
  • onion.css — styles for the bottom webring widget
  • sitesData.js — your ring configuration (list of sites + options)
  • onionring-widget.js — “Prev | Random | Next | what is this?” widget logic
• ring-explorer/
  • index.html — Ring Explorer UI (discover/register rings)
  • ringData.js — example data for the Explorer

Quick widget integration (static include)

1. Add the container where you want the widget to appear:

<div id="shogun-ring"></div>

2. Include the required files (order matters):

<link rel="stylesheet" href="ring/onion.css">
<script src="theme-toggle.js"></script>
<script src="ring/sitesData.js"></script>
<script src="ring/onionring-widget.js"></script>

3. Configure ring/sitesData.js (minimal example):

const sitesData = [
  { id: 'site-a', name: 'Site A', description: 'Demo', url: 'https://example.com/a/',  tags: ['Demo'] },
  { id: 'site-b', name: 'Site B', description: 'Demo', url: 'https://example.com/b/',  tags: ['Demo'] }
];

var ringName  = 'Shogun Network';
var ringID    = 'shogun-ring';
var useIndex  = false;
var indexPage = '#';
var useRandom = true;

Note: the widget considers a page part of the ring if window.location.href.startsWith(site.url) is true. Use absolute URLs with a trailing slash that match your deployed origin (e.g. https://your-domain.com/).

Local development

Serve the folder with a simple static server and open the browser:

python -m http.server 3000
# then visit http://localhost:3000/shogun-onion/

Or:

npx live-server --port=3000

Using the npm package (shogun-onion) in other apps

You can also consume the widget from npm (e.g. inside a Vite/Next.js app):

npm i shogun-onion
# or: yarn add shogun-onion

<div id="shogun-ring"></div>
<script type="module">
  import { sitesData, mountOnionRing } from 'shogun-onion';
  import 'shogun-onion/onion.css';

  await mountingOnionRing({
    ringName: 'Shogun Network',
    ringID: 'shogun-ring',
    useIndex: false,
    useRandom: true,
    sitesData // customize as needed
  });
</script>

If you modify sitesData.js inside your app at runtime, restart your dev server so Vite picks up the new export.

Create your own ring and register it

1. Add your site’s public URL to ring/sitesData.js (or to your app’s sitesData if using npm). Make sure it exactly matches the domain + path you’ll deploy to, including trailing slash.
2. Run locally and open your site at the same origin. You should see the ring widget at the bottom. If you see “This site isn’t part of the Shogun Network…”, your current URL doesn’t match any site.url (fix the URL in sitesData or your server path).
3. Deploy your site (e.g. Vercel, Netlify, GitHub Pages). Update sitesData URLs to the public domain if needed.
4. Open the Ring Explorer (/ring-explorer/index.html in this repo, or the hosted instance) and click “Register Your Ring”. Provide the base URL you added to sitesData and your ring details.

Tip: On Vercel, use relative paths for local assets:

<!-- Good (works on Vercel) -->
<link rel="stylesheet" href="ring/onion.css">
<script src="ring/onionring-widget.js"></script>
<script src="ring/sitesData.js"></script>

<!-- Avoid absolute /favicon.ico 404 by inlining a blank icon -->
<link rel="icon" href="data:,">

Troubleshooting

• Widget appears but text is invisible: Ensure ring/onion.css is loaded. The CSS sets text color for the table inside the widget. On Vercel use the relative path ring/onion.css and hard‑reload the page.
• “This site isn’t part of the ring”: Add your site’s deployed URL (with trailing slash) to sitesData and redeploy. The widget matches by startsWith(site.url).
• 404 for CSS/JS on Vercel: Use relative paths (ring/onion.css, ring/onionring-widget.js, ring/sitesData.js) or include the npm package and import shogun-onion/onion.css. Add <link rel="icon" href="data:,"> to avoid the default /favicon.ico request.
• Using npm in Vite/Next: After editing sitesData, restart the dev server so the new ESM export is picked up.

License

This project is part of the Shogun Ecosystem. Licensed under CNPL v4+ (Cooperative Non‑Violent License). See the full text in the repository.