Alap

Appearance

vitepress-alap ​

VitePress integration for Alap — use <alap-link> web components directly in your markdown documentation.

Install ​

Available in the Alap monorepo at integrations/vitepress-alap/.

Install from the monorepo
bash
git clone https://github.com/DanielSmith/alap.git
cd alap
pnpm install
pnpm build
cd integrations/vitepress-alap
pnpm build

Then add it to your project as a local dependency in your package.json:

json
"vitepress-alap": "file:../path-to-alap/integrations/vitepress-alap"

Setup ​

Option A: IIFE + public config (simplest) ​

Copy alap.iife.js into docs/public/. Create a config script in docs/public/docs-config.js. Add both to VitePress head, and add the plugin:

js
// docs/.vitepress/config.mjs
import { defineConfig } from 'vitepress';
import { alapPlugin } from 'vitepress-alap';

export default defineConfig({
  head: [
    ['script', { src: '/alap.iife.js' }],
    ['script', { src: '/docs-config.js' }],
  ],
  vite: {
    plugins: [alapPlugin()],
  },
});

The plugin registers <alap-link> as a custom element so Vue's template compiler passes it through. The IIFE and config scripts handle registration.

Option B: Bundled config (auto-inject) ​

js
// docs/.vitepress/config.mjs
import { defineConfig } from 'vitepress';
import { alapPlugin } from 'vitepress-alap';

export default defineConfig({
  vite: {
    plugins: [
      alapPlugin({ config: './alap-config.ts' }),
    ],
  },
});

The plugin injects the web component registration and config loading automatically. No <script> tags in head needed.

Usage ​

Use <alap-link> anywhere in your markdown:

md
Check out these <alap-link query=".coffee">cafes</alap-link>.

The <alap-link query=".nyc + .bridge">NYC bridges</alap-link> are worth visiting.

Browse the <alap-link query="@favorites">favorites</alap-link>.

The links render as clickable text. On click, a menu appears with the matching items from your config.

Options ​

OptionTypeDefaultDescription
configstring—Path to config file (auto-injected). Omit to use IIFE + public scripts.
configNamestring—Named config for multi-config setups
validatebooleantrueValidate config at build time (warns, doesn't fail)

What the plugin does ​

  1. Registers <alap-link> as a custom element in Vue's template compiler — without this, Vue treats it as an unknown component and drops it
  2. Optionally injects the Alap setup script (web component registration + config loading)

That's it. The web component handles everything else — menus, keyboard nav, ARIA, positioning, dismiss behavior.

Known issues ​

  • Option B (bundled config) does not work yet — transformIndexHtml injection is not firing in VitePress dev mode. Use Option A (IIFE + public scripts) for now. Fix planned for next beta.

See also ​