Webring Kit

Webring Kit is a framework-agnostic OSS toolkit for creating and embedding GitHub-backed webrings.

The project centers on native Web Components so the same widget can be used from vanilla HTML, React, Next.js, SvelteKit, Jekyll, Ghost, Astro, Eleventy, and other environments.

Quick start

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@webring-kit/element@0.1.0/dist/webring-element.js">
</script>

<webring-nav
  src="https://cdn.jsdelivr.net/gh/example/webring@main/rings/example.json"
  site="https://alice.example.com"
  layout="nav"
  theme="inherit">
</webring-nav>

Packages

• @webring-kit/core: schema types, source adapters, validation, cache, navigation.
• @webring-kit/element: <webring-nav>, <webring-list>, and <webring-badge> custom elements.
• @webring-kit/react: typed React wrapper.
• @webring-kit/next: Next.js helpers.
• @webring-kit/cli: validation, site checks, and index generation.
• @webring-kit/schemas: JSON Schemas for ring manifests.

Design principles

1. Ring data is plain JSON.
2. Rendering is portable through standards-based custom elements.
3. Styling inherits from the host page by default.
4. Shadow DOM is opt-in for isolation.
5. No tracking, cookies, analytics, or arbitrary HTML from ring data.
6. Maintainers should be able to validate and review membership through GitHub PRs.

Local development

pnpm install
pnpm build
pnpm test
pnpm validate:example-ring

Repository layout

See docs/architecture.md and docs/implementation-plan.md.