Community Runes — Specification

Package system, namespacing, rune extension, ecosystem architecture

Overview

Community runes are published packages that add domain-specific content types to refrakt.md. They go through the full rendering pipeline — parsing, rune transform, identity transform, theming — and are treated identically to core runes by the system. The only difference is where the rune definition comes from.

Community runes exist because some content types are too domain-specific for the core library but too widely shared to be local rune declarations. A D&D 5e stat block is used by thousands of game masters. A screenplay scene heading is used by thousands of screenwriters. These deserve proper packages with transforms, theme integration, inspector fixtures, and documentation.

Rune Tiers

All tiers produce runes that are indistinguishable to the rendering pipeline. A {% stat-block %} from a community package goes through the same parse → rune transform → identity transform → render chain as a {% hint %} from the core.

The @refrakt-md/ namespace signals official packages maintained by the refrakt.md team. @refrakt-community/ signals third-party packages. Both go through the same pipeline. The distinction is trust and maintenance commitment, not technical capability.

New Project Defaults

New projects include official packages relevant to their use case. "Starting a landing page" pre-installs @refrakt-md/landing. "Starting a docs site" pre-installs @refrakt-md/docs. Users can remove packages they don't need or add community packages. Core runes are always available and cannot be removed.

Package Inventory

Core (~27 runes, built-in)

Runes that nearly every refrakt.md project uses regardless of domain. These are content-type primitives — tools for structuring and presenting information, not tied to any specific audience.

Prose & Formatting

Navigation & Structure

Data & Code

@refrakt-md/marketing (8 runes)

Marketing sites, product pages, landing pages. If you're building a website that needs to sell, convert, or present a business, you need these. If you're writing docs or a blog, you don't.

@refrakt-md/docs (3 runes)

Developer documentation. API references, code documentation, changelogs.

@refrakt-md/learning (8 runes)

Structured educational and instructional content. Courses, tutorials, training materials, how-to guides, recipes.

Audience: Online course creators, tutorial authors, technical educators, bootcamp instructors, corporate training teams, cooking course sites, documentation teams writing getting-started guides.

Implementation note: glossary (auto-linking terms across the site) and prerequisite (dependency graph between content) require build pipeline integration beyond standard rune transforms. These runes are simple to render individually but their full power — site-wide term linking and learning path visualisation — depends on cross-page awareness at build time.

Runes compose naturally within a lesson page: objective at the top declares what the student will learn, concept runes introduce new terminology, howto or recipe runes teach procedures, exercise runes provide practice, and a quiz at the end tests retention. A glossary page collects all concept definitions and auto-links terms wherever they appear across the site. prerequisite runes build a dependency graph between lessons that themes can render as a learning path.

@refrakt-md/storytelling (7 runes)

Writers, game masters, TTRPG players, worldbuilders. See the Storytelling Runes specification for full details.

@refrakt-md/places (3 runes)

Places, events, and journeys. Geographic and time-based real-world content.

Audience: Travel bloggers, city guide creators, event organisers, tourism sites, conference sites. Future candidates for this package: accommodation (hotel/Airbnb card with amenities), venue (restaurant or bar with hours and atmosphere).

@refrakt-md/business (5 runes)

Professional and organisational content. Company sites, agency portfolios, nonprofit pages, careers pages.

Audience: Company about pages, agency portfolios, nonprofit sites, startup pitch sites, careers pages, investor relations. Team page, company history, partner logos, job listings.

@refrakt-md/design (5 runes)

Design systems and component libraries. For teams documenting their visual language.

@refrakt-md/media (6 runes)

Time-based media content: music, podcasts, audiobooks, video, talks. Covers both metadata (describing media that lives on external platforms) and playback (embedding self-hosted media). embed in core handles third-party player widgets (YouTube, Spotify embeds). This package handles everything else.

Metadata runes — describe media with structured cards and schema.org output:

The type attribute on track, playlist, and album determines which schema.org type is generated and which attributes the AI suggests. A track with type="episode" generates PodcastEpisode schema and expects show, season, and episode number. The same rune with type="song" generates MusicRecording and expects artist and album.

Player runes — embed self-hosted media directly in the page:

The distinction: you reference a track (metadata card with links to where you listen), you play a video or audio (embedded player in the page).

Audience: Band and artist sites, podcast sites, audiobook publishers, video creators, conference talk archives, record label catalogues, film portfolios, sound design showcases, DJ mix archives.

Summary

Package Structure

A community rune package is a standard npm package with a defined structure:

@refrakt-community/dnd-5e/
  package.json
  index.ts              ← rune registration and exports
  runes/
    item.ts             ← rune transform for {% item %}
    item.schema.ts      ← attribute validation schema
    stat-block.ts       ← rune transform for {% stat-block %}
    stat-block.schema.ts
    spell.ts
    spell.schema.ts
    encounter.ts
    encounter.schema.ts
  theme/
    dnd-5e.config.ts    ← identity transform config for all runes
    dnd-5e.css          ← default visual styling
    assets/
      icons/            ← SVG icons (damage types, schools of magic, etc.)
  behaviors/
    initiative.ts       ← interactive behaviors (encounter tracker, dice roller)
  fixtures/
    item.md             ← inspector fixtures for each rune
    stat-block.md
    spell.md
    encounter.md
  prompt/                ← optional: for third-party chat products
    rune-descriptions.md ← AI prompt descriptions for third-party chat integration
  README.md