Alap

Version 3.2, Daniel Smith - April 2026

Turn any link into a curated menu of destinations.

A traditional link is a demand — one URL, chosen by the author. An Alap link is an invitation — a set of options, chosen by the reader.

Instead of cluttering your writing with many separate links:

"You can visit the Brooklyn Bridge, the Manhattan Bridge, the High Line, or this park, or this other place."

You can write naturally:

"There are several great landmarks within walking distance."

When the reader clicks "landmarks," they get a menu. Your sentence stays clean. The reader chooses what matters to them.

Get Started

| You are... | Start here | |------------|-----------| | A developer building with Alap | Getting Started — install, framework setup, configuration, storage | | A writer, editor, or designer using Alap | For Creators — concepts, expression language, editors, cookbooks |

The Expression Language

Tags, macros, and operators compose into a query language for your link library:

.nyc                        all items tagged "nyc"
.nyc + .bridge              AND — items with both tags
.nyc | .sf                  OR — items with either tag
.nyc - .tourist             WITHOUT — subtract matches
(.nyc + .bridge) | .sf      parentheses for grouping
@favorites                  expand a saved macro
golden, brooklyn            specific items by ID

Protocols gather data dynamically. Refiners filter and order the results:

:time:30d:                       items added in the last 30 days
:location:radius:40.7,-74.0:5mi: items within 5 miles of a point
:atproto:feed:with-alap:    live posts from a Bluesky feed
.coffee + :time:7d:         combine with tags and operators
*sort:label* *limit:5*      sort, limit, shuffle, paginate

One config, many menus. Update a URL once, every menu reflects it. Add a tag to an item, it appears in every expression that matches.

What's Included

• Full accessibility — ARIA roles, keyboard nav, focus management, screen reader support
• Event hooks — hover previews, context menus, custom actions on menu items
• Image menus — photos instead of text labels
• Viewport adjustment — menus flip to stay on-screen
• Regex search — /pattern/ syntax for content-aware filtering
• Security hardened — URL sanitization, ReDoS protection, config validation
• Storage layer — IndexedDB, REST API client, offline-resilient hybrid
• 10 server examples — Node, Bun, Python, Go, Rust, PHP, Java backends
• 8 visual editors — React, Vue, Svelte, Solid, Astro, Alpine builds
• Markdown, MDX & CMS support — remark, rehype, and MDX plugins for any content pipeline
• Next.js, Nuxt, Astro, Eleventy, Hugo, Qwik City & VitePress integrations — zero-config framework packages
• WordPress plugin — [alap] shortcode, SQLite containers, instant demo
• CDN / IIFE build — <script> tag usage for static sites and zero-build setups
• AT Protocol / Bluesky — :atproto: protocol for live feeds, profiles, and search
• htmx — zero-framework HTML-over-the-wire; web components auto-initialize after swaps

Development

This is a pnpm workspace with Turborepo for build orchestration.

pnpm install          # install all workspace packages

# Root library only
pnpm build            # ESM + CJS + IIFE + type declarations
pnpm test             # 992 tests across core, UI adapters, storage, plugins

# Entire workspace (via Turborepo)
pnpm build:all        # build root library, then all editors/integrations/plugins/examples in parallel
pnpm test:all         # run tests across all workspace packages
pnpm typecheck:all    # type-check everything

# Filtered builds
pnpm turbo run build --filter=alap-editor-react...   # one editor + its dependencies
pnpm turbo run build --filter=./integrations/*        # all integrations
pnpm turbo run test --filter=./plugins/*              # tests for plugins only

# Docker (Node server examples — pre-builds library tarball automatically)
pnpm docker:express   # Express + SQLite
pnpm docker:bun       # Bun + SQLite
pnpm docker:hono      # Hono + SQLite

# Docker (other languages — self-contained, build from repo root or servers/)
podman build -t alap-axum -f examples/servers/axum-sqlite/Dockerfile .
podman build -t alap-gin -f examples/servers/gin-sqlite/Dockerfile .
podman build -t alap-flask -f flask-sqlite/Dockerfile examples/servers/
podman build -t alap-django -f django-sqlite/Dockerfile examples/servers/
podman build -t alap-laravel examples/servers/laravel-sqlite/
podman build -t alap-java-spring -f examples/servers/java-spring/Dockerfile .
podman build -t alap-fastapi -f fastapi-postgres/Dockerfile examples/servers/
cd examples/servers/fastapi-postgres && podman compose up -d  # starts FastAPI + Postgres together

# List built server images
podman images | grep alap-

# Run a server (example: Axum on port 3000)
podman run -d -p 3000:3000 --name alap-axum alap-axum

# Stop a running server
podman stop alap-axum

# Remove a stopped container
podman rm alap-axum

Turborepo caches build outputs — a second run with no changes completes in under a second.

pnpm install will show warnings about pnpm.overrides in editors, plugins, and server packages. These are expected — each sub-package carries its own dependency overrides for standalone use outside the workspace. The root package.json overrides take precedence in workspace mode; the per-package copies are harmless.

Next Steps

| Where to go | What you'll find | |-------------|-----------------| | Cookbook | Language ports, editors, markdown, rich-text, accessibility, placement | | Examples | 29 demo sites + 10 server backends | | Framework Guides | 9 adapters + integrations for Eleventy, Next.js, Nuxt, Hugo, WordPress, htmx, and more | | API Reference | Every type, function, component, attribute, CSS hook, and event | | Full Documentation | Adapters, search, storage, testing, security | | FAQ | Common questions and answers | | alap.info | Project website |

Security

A note on scope. I'm not a security expert. Alap hasn't been through a third-party audit — it's an open source project from a single maintainer. Please do your own due diligence before deploying, especially when configuring protocols that fetch external data or talk to local services. I'm not responsible for how you deploy this.

For the full picture: SECURITY.md, the threat model, and the security reference.

License

Apache-2.0