Alap v3.2 — Rethinking the Humble Link

Built on What Already Works

Alap extends the idea of what we expect from a link. Dynamic menus via a simple attribute and a lightweight expression language. No proprietary formats, no lock-in, no framework required.

The project is open source (Apache 2.0) and published across five package registries (npm, and language parsers on crates.io, PyPI, Go Modules, and Packagist).

An Expression Language for Links

Tag-based query language. Use regular anchors with Alap attributes or the <alap-link> web component — your choice:

<!-- Standard anchor with Alap attributes -->
  <a class="alap" data-alap-linkitems=".coffee">coffee shops</a>

  <!-- Or as a web component -->
  <alap-link query=".coffee">coffee shops</alap-link>

  <!-- Intersection — NYC bridges only -->
  <alap-link query=".nyc + .bridge">NYC bridges</alap-link>

  <!-- Specific items by ID, plus a tag query -->
  <alap-link query="golden_gate, .coffee + .sf">the bridge, or coffee nearby</alap-link>

  <!-- Macro — a named set of favorites -->
  <alap-link query="@favorites">favorites</alap-link>

Tags, IDs, intersections, unions, subtraction — compose menus from a shared link library. Macros let you name and reuse common sets. The grammar is small enough to learn in minutes, powerful enough to express complex selections.

Protocols pull live data. v3.2 ships with :web:, :atproto:, :json:, :hn:, :obsidian:, :time:, and :location: built in:

<!-- Hacker News — top stories from the last 24 hours -->
  <alap-link query=":hn:top: + :time:1d: *limit:10*">HN today</alap-link>

  <!-- Obsidian vault — notes tagged #research, most recent first -->
  <alap-link query=":obsidian:core:research: *sort:modified* *limit:5*">Recent research notes</alap-link>

  <!-- Live search — Open Library JSON API -->
  <alap-link query=":web:books:decentralization:">Books: "decentralization"</alap-link>

  <!-- AT Protocol — recent posts from a Bluesky account -->
  <alap-link query=":atproto:feed:eff.org:limit=3:">EFF — recent posts</alap-link>

  <!-- Mix static tags, Hacker News, and Bluesky in one expression -->
  <alap-link query="(.orgs *limit:2*), (:hn:search:$ai_safety:), (:atproto:feed:eff.org:limit=3:)">
    AI safety: orgs + HN + EFF
  </alap-link>

Progressive Async — Menus That Open Instantly

A protocol fetch takes real time. In v3.1, the menu waited. In v3.2, it doesn't.

Every trigger now opens instantly with a loading placeholder and swaps in the resolved content in place — with a FLIP transition so the menu doesn't jump. In-flight duplicates are deduped, aborts cancel pending fetches cleanly, and timeouts apply per-request. The same pipeline runs under the menu, lens, and lightbox renderers, and all seven framework adapters honor it.

[data-alap-placeholder="loading|error|empty"] lets you style each state from CSS. No runtime branching, no framework-specific hooks — your existing stylesheet already controls it.

Beyond the Menu

The default dropdown is one shape. v3.2 ships two more, production-ready:

• Lens — a structured metadata card. Shows the item's image, description, tags (clickable — each launches its own query), and arbitrary meta fields. Good for places where the menu item wants a second look, not a navigation.
• Lightbox — fullscreen overlay for image-heavy sets. Zoom, pan, carousel navigation. The whole set resolves through the same expression language; you're just rendering it differently.

All three renderers compose through RendererCoordinator — open a lens while a menu is showing, the menu dismisses. Escape cascades through the stack. One expression, three possible shapes, one coordination layer.

Your Own Knowledge Base

:obsidian:core: turns an Obsidian vault into a live link source. Zero plugin required — it reads the filesystem directly.

// server.mjs
  import { AlapEngine } from 'alap';
  import { obsidianHandler } from 'alap/protocols/obsidian';

  // Data-only protocol config
  const config = {
    protocols: {
      obsidian: {
        vault: 'MyVault',
        vaultPath: '/absolute/path/to/vault',
      },
    },
  };

  // Handler passed at engine construction
  const engine = new AlapEngine(config, { handlers: { obsidian: obsidianHandler } });

Then in the page:

<alap-link query=":obsidian:core:rust: *limit:5*">Rust notes</alap-link>

Substring grep across frontmatter and body, $preset for named field narrows, inline #tag support in note bodies, alias map for Obsidian tag shapes that collide with Alap's grammar. Symlink rejection, path-traversal guard, per-file size cap, file-count cap — on by default.

:obsidian:rest: adds fuzzy search via the Local REST API plugin when Obsidian is running. Loopback-gated TLS, API-key redaction in logs, path-traversal guard on every vault GET.

Don't have a vault yet? vault_convert.py turns a markdown tree (including Hugo / Jekyll / MkDocs / Docusaurus sites) into one. feed_to_md.py turns an RSS or Atom archive into markdown ready for the converter. Trust-model-aware sanitization on every step.

Works Everywhere You Do

Framework Adapters

Idiomatic components, hooks, and state management — not a wrapper around a generic widget.

React, Vue, Svelte, Solid, and Qwik support three rendering modes: DOM, Web Component, and Popover API. Every adapter includes keyboard navigation, ARIA accessibility, click-outside dismissal, and the compass-based placement engine.

Integrations

Drop Alap into your static-site generator or documentation platform with zero-config setup.

Plugins

Content-level transforms for CMS pipelines, rich-text editors, and markdown toolchains.

Server-Side Parsing in Your Language

Idiomatic parsers in six languages — implementations that feel native to each ecosystem, not mechanical ports.

All six implement the same expression grammar — item IDs, tag queries, operators, macros, regex search, grouping, protocols, refiners — with full test suites.

Tested, Not Just Written

1,926 tests across 89 files — core parser, every framework adapter, integrations, plugins, protocols (:hn:, :obsidian:, :web:, :json:, :atproto:, :location:, :time:), renderers (menu, lens, lightbox, embed), progressive async pipeline, security (URL sanitization, SSRF guard, ReDoS protection, path traversal, XSS fixes, config validation, tiered trust model). Plus Python tests covering the markdown-to-vault and feed-to-markdown pipelines.

Proof-of-Concept Editors

Eight config editors in as many frameworks — React, React ShadCN, Vue, Svelte, Solid, Alpine, Astro, and a React Design reference — to prove the same editing experience works consistently across stacks.

Each editor supports JSON import/export and can call any of the 11 example servers (Express, Bun, Hono, Flask, Django, FastAPI, Laravel, Gin, Axum, Spring Boot, Sinatra) for server-side resolution. Same UI: build a link library, write test queries, preview resolved menus — all with drag-and-drop link import and client-side metadata extraction.

The point isn't that you need all of these editors. It's that any framework can drive the same config surface with the same results.

See It in Action

Live examples across every adapter and protocol — DOM, web components, React, Vue, Svelte, Solid, Qwik, Alpine, Astro, htmx, CMS content, markdown, Hacker News, Obsidian, the lightbox renderer, the lens renderer, and all-together (menu + lens + lightbox on one page sharing one config).

Browse the examples | Documentation | GitHub | npm

npm install alap

Author Note

I'm Daniel Smith, and I've been thinking about aspects of this for 30 years. I published an early version of this back in 2012, and rewrote it in 2022, with an eye towards Vue and React. Version 3 is a complete rewrite in TypeScript. I worked in tandem with Claude Code to get this going, and I assure you this is no vibe coding project :)