JAAMD

Just Another Astro Markdown — markdown plugins, client-side enhancements and styles as a single Astro integration.

Table of Contents

• Installation
• Requirements
• Setup
• Integration Options
• Markdown Syntax
  • Alerts
  • Code tabs
  • Table of contents
  • Spoilers
• MarkdownContent Component
• Client-side Enhancements
• Markup and classes
• Theming
  • Customizing variables
  • Font sizes
  • Dark mode
  • Theme presets
  • Dual-theme Shiki
• Manual / Advanced Usage

Installation

npm install @jaamd/jaamd
# or
npx astro add @jaamd/jaamd

Requirements

JAAMD is published as source, with no compiled dist/ and no emitted .d.ts. It works out of the box in any Astro project, but is not consumable from plain Node, a CommonJS build, or a TypeScript project using "moduleResolution": "node16".

Upgrading from @lancher-dev/jaamd

The package is now @jaamd/jaamd. Replace the dependency and every import from @lancher-dev/jaamd; the API is unchanged.

Upgrading from 0.10

• theme no longer overrides markdown.shikiConfig. Unset, your Shiki configuration stays; "github-light" replaces only Astro’s own default.
• @astrojs/markdown-remark is an optional peer dependency. Install it when you use unified(), which you import from it anyway.
• Code-tab ids are jaamd-tabs-<hash>, unique across every document on a page, instead of jaamd-tabs-<n>.
• Lightbox images are wrapped in <button class="jaamd-lightbox-trigger">, so they open from the keyboard. img.jaamd-lightbox-enabled is gone. See Image lightbox for browser support.
• With a manual unified() setup, register Astro’s rehypeHeadingIds before rehypeHeadingLinks, which now reads the ids instead of computing them. See Manual / Advanced Usage.
• Blockquote, alert, h2 and hr borders are drawn without a CSS reset.
• Heading anchors are always visible below 600px, as intended.

Upgrading from 0.9

• jaamd no longer switches the markdown processor. With no configuration you are on Sätteri.
• Set markdown.processor: unified() to stay on unified.
• markdown.remarkPlugins and markdown.rehypePlugins still work: Astro moves to unified, jaamd adds its remark plugins.
• Astro ^7.3.0 is required.
• Heading anchors are plain links: a click navigates, nothing is copied.
• Table wrappers and heading anchors are in the built HTML. Turn them off with plugins: { tables: false, headingLinks: false }.
• The lightbox is a <dialog class="jaamd-lightbox">. .jaamd-lightbox__backdrop, .jaamd-lightbox__content and .jaamd-lightbox--hidden are gone: style ::backdrop and [open].
• <details> animates in CSS. .jaamd-details-wrapper and .jaamd-details-inner are gone.

Setup

Add the integration to your Astro config:

import jaamd from '@jaamd/jaamd'
// astro.config.mjs
import { defineConfig } from 'astro/config'

export default defineConfig({
    integrations: [jaamd()],
})

Wrap your markdown content with the MarkdownContent component in your layout:

---
// src/layouts/BlogPost.astro
import MarkdownContent from '@jaamd/jaamd/components'
---

<MarkdownContent>
    <slot />
</MarkdownContent>

The integration registers its plugins on the configured markdown processor and injects the stylesheet automatically. No other configuration is required.

The processor is extended, never replaced: Sätteri gets mdast plugins and the directive syntax, unified() gets the remark plugins. Any other processor is left alone, with a warning.

---
import '@jaamd/jaamd/default.css'
import '@jaamd/jaamd/styles.css'
---

Integration Options

jaamd({
    selector: '.jaamd-content', // CSS selector for the JS enhancements
    theme: 'github-light', // Shiki theme name (or { light, dark }); see below
    noDefault: false, // skip injecting @jaamd/jaamd/default variable fallbacks
    plugins: {
        codeTabs: true, // :::code-tabs directive blocks
        toc: true, // :::toc directive blocks
        alerts: true, // > [!NOTE] / [!WARNING] blockquote alerts
        directive: true, // `:::` syntax (prerequisite for codeTabs and toc)
        tables: true, // scroll container around tables
        headingLinks: true, // anchor link on every heading
    },
})

theme

The Shiki theme for code blocks, or { light, dark } for dual-theme mode. Unset, markdown.shikiConfig is left as configured; "github-light" replaces only Astro’s own default ("github-dark" with no themes).

selector

Controls which element the client-side JS enhancements target at runtime. It does not affect the CSS file, which always uses .jaamd-content.

• With <MarkdownContent>, leave it at the default.
• With a custom wrapper (e.g. <div data-md>), set selector to match it and provide your own CSS.

noDefault

Set to true when you supply a complete --jaamd-* variable set of your own. It has no effect on <MarkdownContent>, which imports the defaults directly; with a custom wrapper, control them by importing @jaamd/jaamd/default or not.

Markdown Syntax

Alerts

GitHub-style blockquote alerts, in five variants:

> [!NOTE]
> Useful information the reader should know.

> [!TIP]
> Helpful advice.

> [!IMPORTANT]
> Key information required to succeed.

> [!WARNING]
> Urgent information needing immediate attention.

> [!CAUTION]
> Advises about risks or negative outcomes.

Code tabs

Group several code blocks into a tabbed panel. The text after the language is used as the tab label; it falls back to the language, then to Tab N.

:::code-tabs
```bash npm
npm install
```

```bash pnpm
pnpm install
```
:::

Table of contents

A :::toc block wraps the list you write in a navigation landmark. Nothing is generated: entries, order, wording and depth are whatever the markdown says. The text in brackets is an optional title.

:::toc[On this page]
- [Installation](#installation)
- [Setup](#setup)
    - [Integration options](#integration-options)
:::

It renders as:

<nav class="jaamd-toc" aria-label="On this page">
    <p class="jaamd-toc-title">On this page</p>
    <ul>
        …your list…
    </ul>
</nav>

The title is a <p>: out of getHeadings(), no anchor icon. A - list loses its bullets, 1. keeps the numbers. Entries are plain anchors and navigate with JavaScript disabled; with it, the entry whose section is on screen is marked aria-current="location".

Writing the anchors

Heading ids come from Astro, slugged with github-slugger:

The client-side fallback follows the same rules, so ids match for markdown that never went through Astro’s pipeline (set:html, HTML from a CMS).

With a sticky header, raise --jaamd-scroll-margin-top (default 80px).

Spoilers

Any element with the spoiler class is hidden until activated:

<span class="spoiler">The butler did it.</span>

MarkdownContent Component

MarkdownContent is a polymorphic component. It renders as <div> by default and accepts any valid HTML tag via the as prop.

import MarkdownContent from '@jaamd/jaamd/components'

Props

The jaamd-content class is always present on the wrapper element. It is the selector used by the JS enhancements and must not be removed.

---
import MarkdownContent from '@jaamd/jaamd/components'
---

<!-- Default: renders as <div class="jaamd-content"> -->
<MarkdownContent>
    <slot />
</MarkdownContent>

<!-- Custom tag: renders as <article class="jaamd-content"> -->
<MarkdownContent as="article">
    <slot />
</MarkdownContent>

<!-- Extra classes: renders as <article class="jaamd-content prose mx-auto"> -->
<MarkdownContent as="article" class="prose mx-auto">
    <slot />
</MarkdownContent>

Client-side Enhancements

A dependency-free ES module enhances the rendered markdown. Events are delegated on document; per-element setup re-runs on every astro:page-load, so it keeps working across View Transitions.

Table wrappers and heading anchors come from the build. The module adds them only to markup that skipped the processor (set:html, HTML from a CMS).

Keyboard

<details> animates in CSS, no script: height where the browser supports interpolate-size, a fade elsewhere.

Under prefers-reduced-motion: reduce JAAMD’s CSS transitions are disabled.

With scripting disabled, tables still scroll, heading anchors work and every code tab panel is shown.

Image lightbox

Opening and closing are the browser’s own: the image button and the ✕ button are invoker commands on the <dialog>, and closedby="any" closes it on a click outside the image.

Older browsers show the image as a plain image.

Excluding images from the lightbox

Linked images are skipped automatically, so badges keep navigating:

[![build](https://img.shields.io/badge/build-passing-green)](https://github.com/you/repo)

Opt a standalone image out with data-no-lightbox:

<img src="/diagram.svg" alt="Architecture diagram" data-no-lightbox />

Markup and classes

What JAAMD emits, for styling it or writing a custom wrapper. Build markup is in the HTML from the markdown processor; client markup is added at runtime by the enhancement script.

Theming

All styles are driven by CSS custom properties prefixed with --jaamd-*. The default set (@jaamd/jaamd/default) is injected automatically.

Customizing variables

Override any variable on :root in your own stylesheet:

:root {
    --jaamd-color-fg: #334155;
    --jaamd-color-fg-bright: #0f172a;
    --jaamd-color-primary: #6366f1;
    --jaamd-color-primary-light: #818cf8;
    --jaamd-font-mono: ui-monospace, monospace;
    --jaamd-font-size: 1rem;
}

Defaults live in @layer jaamd.defaults, so an unlayered :root block always wins regardless of import order.

See src/styles/variables.css for all 60 variables and their default values.

Font sizes

--jaamd-font-size is the one knob for the whole document. Every other size is derived from it, so moving it moves the entire scale in proportion:

:root {
    --jaamd-font-size: 1rem; /* headings, code, tables… all follow */
}

To break a single element out of that scale, set its own token. Each is read with the derived value as its fallback, so an unset token changes nothing; they are opt-in, one at a time:

:root {
    --jaamd-font-size: 1rem; /* the baseline */
    --jaamd-font-size-h1: 2.5rem; /* but h1 is fixed, not proportional */
    --jaamd-font-size-code-block: 0.8rem; /* and code blocks are tighter */
}

A block that owns a token governs what is inside it: paragraphs in a blockquote follow -blockquote, not -p. Alert bodies have no token of their own and follow -p; only their title is separate. The copy button, code-tab labels and heading-link icons stay tied to --jaamd-font-size: they are JAAMD’s chrome, not your document’s typography.

Dark mode

The default set includes dark-mode overrides activated by the dark class on <html>. Toggle the class and all JAAMD elements adapt.

Theme presets

Eight presets restyle the --jaamd-* palette to match popular editor colour schemes. A dual preset carries a light and a dark palette and follows html.dark; the others are one palette that applies in both modes.

As a standalone theme, replacing the default light theme:

jaamd({ theme: 'dracula' })

@import '@jaamd/jaamd/default.css';
@import '@jaamd/jaamd/themes/dracula.css';
@import '@jaamd/jaamd/styles.css';

A single-palette preset can also be scoped to html.dark via the /dark variant, to use it as the dark half of your own light theme. Dual presets already cover both modes and have no /dark:

@import '@jaamd/jaamd/themes/dracula/dark.css';

import '@jaamd/jaamd/themes/dracula/dark'

Each theme declares itself, so a picker can be built from data:

import { themes } from '@jaamd/jaamd/themes'
// [{ slug: "dracula", name: "Dracula", mode: "dark", shiki: "dracula" }, …]

Each preset is generated from a palette.js of fourteen colours, so every theme declares the same token set. The .css files are build output: to customise a preset, copy its directory and edit the palette. To add one, see CONTRIBUTING.md.

Dual-theme Shiki

Pass an object to theme to highlight code with two colour schemes, switched by the dark class:

jaamd({
    theme: { light: 'github-light', dark: 'github-dark' },
})

Add an inline script in <head> to prevent a flash of the wrong theme:

<script is:inline>
    ;(function () {
        var t = localStorage.getItem('theme')
        if (t === 'dark' || (!t && matchMedia('(prefers-color-scheme: dark)').matches))
            document.documentElement.classList.add('dark')
    })()
</script>

Manual / Advanced Usage

To bypass the integration, register the plugins yourself on the processor you use. On Sätteri, Astro’s default:

// astro.config.mjs
import { satteri } from '@astrojs/markdown-satteri'
import {
    satteriAlert,
    satteriCodeTabs,
    satteriToc,
    satteriDirectiveFallback,
    satteriTableWrapper,
    satteriHeadingLinks,
} from '@jaamd/jaamd'

export default defineConfig({
    markdown: {
        processor: satteri({
            features: { directive: true },
            mdastPlugins: [satteriAlert, satteriCodeTabs, satteriToc, satteriDirectiveFallback],
            hastPlugins: [satteriTableWrapper, satteriHeadingLinks],
        }),
    },
})

satteriDirectiveFallback keeps directives no plugin handles, which Sätteri drops: blocks as a plain <div>, an inline :name as typed. Put it last.

On unified, Astro’s rehypeHeadingIds goes before rehypeHeadingLinks, which links the ids it finds:

// astro.config.mjs
import { rehypeHeadingIds, unified } from '@astrojs/markdown-remark'
import {
    remarkAlert,
    remarkCodeTabs,
    remarkDirective,
    remarkToc,
    rehypeTableWrapper,
    rehypeHeadingLinks,
} from '@jaamd/jaamd'

export default defineConfig({
    markdown: {
        processor: unified({
            remarkPlugins: [remarkAlert, remarkDirective, remarkCodeTabs, remarkToc],
            rehypePlugins: [rehypeTableWrapper, rehypeHeadingIds, rehypeHeadingLinks],
        }),
    },
})

---
import '@jaamd/jaamd/default' // variable fallbacks; omit if you provide your own
import '@jaamd/jaamd/styles'
---

<div class="jaamd-content">
    <slot />
</div>
<script>
    import { initMarkdownEnhancements } from '@jaamd/jaamd/client'
    function run() {
        initMarkdownEnhancements('.jaamd-content')
    }
    run()
    document.addEventListener('astro:page-load', run)
</script>

The CSS files can also be imported from plain .css:

@import '@jaamd/jaamd/default.css';
@import '@jaamd/jaamd/styles.css';