@jaamd/astro 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luca Pattocchio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+<h1 align="center">JAAMD</h1>
+<p align="center">
+  <b>Just Another Astro Markdown</b> — markdown plugins, client-side enhancements and styles as a single Astro integration.
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+---
+
+Alerts, code tabs, a table of contents and spoilers in your markdown; heading
+anchors, scrollable tables, copy buttons and an image lightbox on the page; a
+stylesheet driven by CSS variables, with eight theme presets.
+
+## Installation
+
+```bash
+npx astro add @jaamd/astro
+```
+
+Or install it and register it yourself:
+
+```ts
+// astro.config.mjs
+import jaamd from '@jaamd/astro'
+import { defineConfig } from 'astro/config'
+
+export default defineConfig({
+    integrations: [jaamd()],
+})
+```
+
+Then wrap your markdown in the component, in your layout:
+
+```astro
+---
+import MarkdownContent from '@jaamd/astro/components'
+---
+
+<MarkdownContent>
+    <slot />
+</MarkdownContent>
+```
+
+Requires Astro `^7.3.0` and Node `>=22.12.0`.
+
+## Documentation
+
+The documentation ships with the package, in
+[`docs/`](https://github.com/jaamd/jaamd/tree/main/packages/astro/docs): once
+installed, at `node_modules/@jaamd/astro/docs/`. Point an agent's `AGENTS.md`
+there. It is also published at [docs.jaamd.org](https://docs.jaamd.org).
+
+| Page                                                          | What                                                          |
+| ------------------------------------------------------------- | ------------------------------------------------------------- |
+| [Installation](./docs/01-getting-started/01-installation.md)  | Requirements and setup                                        |
+| [Options](./docs/01-getting-started/02-options.md)            | `theme`, `selector`, `defaultVariables`, `features`, `labels` |
+| [Markdown syntax](./docs/02-markdown.md)                      | Alerts, code tabs, table of contents, spoilers                |
+| [MarkdownContent](./docs/03-usage/01-markdown-content.md)     | The wrapper component                                         |
+| [Client script](./docs/03-usage/02-client.md)                 | Enhancements, keyboard, lightbox                              |
+| [Variables](./docs/04-styling/01-variables.md)                | CSS variables, font sizes, dark mode                          |
+| [Themes](./docs/04-styling/02-themes.md)                      | Presets and dual-theme Shiki                                  |
+| [Markup and classes](./docs/04-styling/03-markup.md)          | The emitted HTML                                              |
+| [Manual setup](./docs/05-advanced/01-manual-setup.md)         | Registering the plugins yourself                              |
+| [Frontmatter fields](./docs/05-advanced/02-frontmatter.md)    | `frontmatterFields(z)`                                        |
+| [Other frameworks](./docs/05-advanced/03-other-frameworks.md) | `@jaamd/core`                                                 |
+| [Upgrading](./docs/06-upgrading.md)                           | Changes between versions                                      |

package/dist/default.css

@@ -0,0 +1 @@
+@import '@jaamd/core/default.css';

package/dist/shiki-dual.css

@@ -0,0 +1 @@
+@import '@jaamd/core/shiki-dual.css';

package/dist/styles.css

@@ -0,0 +1 @@
+@import '@jaamd/core/styles.css';

package/dist/themes/catppuccin/index.css

@@ -0,0 +1 @@
+@import '@jaamd/core/themes/catppuccin.css';

package/dist/themes/dracula/dark.css

@@ -0,0 +1 @@
+@import '@jaamd/core/themes/dracula/dark.css';

package/dist/themes/dracula/index.css

@@ -0,0 +1 @@
+@import '@jaamd/core/themes/dracula.css';

package/dist/themes/gruvbox/index.css

@@ -0,0 +1 @@
+@import '@jaamd/core/themes/gruvbox.css';

package/dist/themes/nord/dark.css

@@ -0,0 +1 @@
+@import '@jaamd/core/themes/nord/dark.css';

package/dist/themes/nord/index.css

@@ -0,0 +1 @@
+@import '@jaamd/core/themes/nord.css';

package/dist/themes/one-dark/dark.css

@@ -0,0 +1 @@
+@import '@jaamd/core/themes/one-dark/dark.css';

package/dist/themes/one-dark/index.css

@@ -0,0 +1 @@
+@import '@jaamd/core/themes/one-dark.css';

package/dist/themes/rose-pine/index.css

@@ -0,0 +1 @@
+@import '@jaamd/core/themes/rose-pine.css';

package/dist/themes/rose-pine-moon/index.css

@@ -0,0 +1 @@
+@import '@jaamd/core/themes/rose-pine-moon.css';

package/dist/themes/tokyo-night/dark.css

@@ -0,0 +1 @@
+@import '@jaamd/core/themes/tokyo-night/dark.css';

package/dist/themes/tokyo-night/index.css

@@ -0,0 +1 @@
+@import '@jaamd/core/themes/tokyo-night.css';

package/docs/00-overview.md

@@ -0,0 +1,33 @@
+---
+description: JAAMD refines the Markdown you already write, as one Astro integration.
+---
+
+# Overview
+
+**Just Another Astro Markdown**: Markdown plugins, client-side enhancements and
+styles as a single Astro integration. Your pages, layouts and routes stay
+yours; JAAMD only changes how Markdown looks and behaves.
+
+- **In the Markdown you write:** [alerts](./02-markdown.md#alerts),
+  [code tabs](./02-markdown.md#code-tabs), a
+  [table of contents](./02-markdown.md#table-of-contents) and
+  [spoilers](./02-markdown.md#spoilers).
+- **In the built HTML:** heading anchors and scrollable tables.
+- **In the browser:** copy buttons, an image lightbox and keyboard support,
+  from a [client script](./03-usage/02-client.md).
+- **In the stylesheet:** [CSS variables](./04-styling/01-variables.md) and
+  [eight theme presets](./04-styling/02-themes.md).
+
+## Packages
+
+| Package        | What it is                                                                       |
+| -------------- | -------------------------------------------------------------------------------- |
+| `@jaamd/astro` | The Astro integration and the `<MarkdownContent>` component. Install this one.   |
+| `@jaamd/core`  | The plugins, the client script and the styles, with no framework around them.    |
+| `@jaamd/jaad`  | A [documentation site generator](../../jaad/docs/00-overview.md) built on JAAMD. |
+
+`@jaamd/astro` brings `@jaamd/core` with it: an Astro project never installs
+core itself. To use JAAMD with another framework, see
+[Other frameworks](./05-advanced/03-other-frameworks.md).
+
+Start with [Installation](./01-getting-started/01-installation.md).

package/docs/01-getting-started/01-installation.md

@@ -0,0 +1,109 @@
+---
+description: Install the @jaamd/astro integration and wrap your Markdown with it.
+---
+
+# Installation
+
+Let Astro add the integration and register it for you:
+
+:::code-tabs
+
+```bash npm
+npx astro add @jaamd/astro
+```
+
+```bash pnpm
+pnpm astro add @jaamd/astro
+```
+
+```bash yarn
+yarn astro add @jaamd/astro
+```
+
+```bash bun
+bunx astro add @jaamd/astro
+```
+
+:::
+
+Or install it and register it yourself:
+
+:::code-tabs
+
+```bash npm
+npm install @jaamd/astro
+```
+
+```bash pnpm
+pnpm add @jaamd/astro
+```
+
+```bash yarn
+yarn add @jaamd/astro
+```
+
+```bash bun
+bun add @jaamd/astro
+```
+
+:::
+
+```ts
+// astro.config.mjs
+import jaamd from '@jaamd/astro'
+import { defineConfig } from 'astro/config'
+
+export default defineConfig({
+    integrations: [jaamd()],
+})
+```
+
+## Requirements
+
+| Requirement                | Detail                                                    |
+| -------------------------- | --------------------------------------------------------- |
+| Astro                      | `^7.3.0`                                                  |
+| Node                       | `>=22.12.0`                                               |
+| Markdown processor         | Sätteri (Astro's default) or `unified()`                  |
+| `@astrojs/markdown-remark` | Only with `unified()`: an optional peer, installed by you |
+| Toolchain                  | Must compile TypeScript and `.astro` sources              |
+
+`@jaamd/astro` is published as TypeScript and `.astro` source, which any Astro
+project compiles. It is not consumable from plain Node, a CommonJS build, or a
+TypeScript project using `"moduleResolution": "node16"`: outside Astro, use
+the compiled [`@jaamd/core`](../05-advanced/03-other-frameworks.md).
+
+## Wrapping your content
+
+Wrap your markdown content with the
+[`MarkdownContent`](../03-usage/01-markdown-content.md) component in your
+layout:
+
+```astro
+---
+// src/layouts/BlogPost.astro
+import MarkdownContent from '@jaamd/astro/components'
+---
+
+<MarkdownContent>
+    <slot />
+</MarkdownContent>
+```
+
+The integration registers its plugins on the configured markdown processor and
+injects the stylesheet. 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.
+
+> [!IMPORTANT]
+> `<MarkdownContent>` loads the stylesheets for you. If you render markdown
+> **without** it, import them yourself in your layout frontmatter:
+>
+> ```astro
+> ---
+> import '@jaamd/astro/default.css'
+> import '@jaamd/astro/styles.css'
+> ---
+> ```

package/docs/01-getting-started/02-options.md

@@ -0,0 +1,81 @@
+---
+description: 'Every option of the jaamd() integration: theme, selector, default variables, features and labels.'
+---
+
+# Options
+
+`jaamd()` works with no options. Each one below changes a single behaviour:
+
+```ts
+jaamd({
+    selector: '.jaamd-content', // elements the client script enhances
+    theme: 'github-light', // Shiki theme name, or { light, dark }; see below
+    defaultVariables: true, // inject @jaamd/astro/default.css on every page
+    features: {}, // features to turn off, such as { lightbox: false }
+    labels: {}, // text JAAMD writes into the page
+})
+```
+
+## `theme`
+
+The Shiki theme for code blocks, or `{ light, dark }` for
+[dual-theme mode](../04-styling/02-themes.md#dual-theme-shiki). 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.
+
+## `defaultVariables`
+
+Set to `false` 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/astro/default.css` or
+not.
+
+## `features`
+
+Every feature is on. Set one to `false` to turn it off, in the build and in the
+client script:
+
+| Feature        | What                                         | Where         |
+| -------------- | -------------------------------------------- | ------------- |
+| `alerts`       | `> [!NOTE]` blockquotes                      | build         |
+| `codeTabs`     | `:::code-tabs` blocks                        | build, client |
+| `toc`          | `:::toc` blocks                              | build, client |
+| `spoilers`     | `:spoiler[…]` and `:::spoiler`               | build, client |
+| `directives`   | The `:::` syntax, for directives of your own | build         |
+| `tables`       | Scroll container around tables               | build, client |
+| `headingLinks` | Anchor on every heading                      | build, client |
+| `copyButtons`  | Copy button on code blocks                   | client        |
+| `lightbox`     | Images open in a dialog                      | client        |
+
+`directives` stays on while `codeTabs`, `toc` or `spoilers` is, since they are
+written in it.
+
+## `labels`
+
+The text JAAMD writes into the page, in English by default. Set the ones to
+translate:
+
+```ts
+jaamd({ labels: { copy: 'Copia il codice', headingLink: 'Link alla sezione' } })
+```
+
+| Label           | Default                                           |
+| --------------- | ------------------------------------------------- |
+| `headingLink`   | `Link to section`, followed by the heading        |
+| `toc`           | `Table of contents`, for a `:::toc` without title |
+| `copy`          | `Copy code`                                       |
+| `copied`        | `Code copied to clipboard`                        |
+| `copySelected`  | `Code selected: copy it with your keyboard`       |
+| `lightbox`      | `Image preview`                                   |
+| `lightboxOpen`  | `Enlarge image`, followed by the alt text         |
+| `lightboxClose` | `Close image preview`                             |
+| `spoiler`       | `Spoiler`                                         |

package/docs/02-markdown.md

@@ -0,0 +1,156 @@
+---
+description: The blocks JAAMD adds to CommonMark and GitHub Flavored Markdown, each with its result.
+keywords: [alerts, code tabs, toc, spoilers, directives]
+---
+
+# Markdown syntax
+
+JAAMD extends [CommonMark](https://commonmark.org/help/) and
+[GitHub Flavored Markdown](https://github.github.com/gfm/) with the blocks
+below. Each one is shown as you write it, then as it renders. Every one of them
+can be turned off with the
+[`features` option](./01-getting-started/02-options.md#features).
+
+## Alerts
+
+GitHub-style blockquote alerts, in five types: `NOTE`, `TIP`, `IMPORTANT`,
+`WARNING` and `CAUTION`.
+
+```markdown
+> [!NOTE]
+> Useful information the reader should know.
+
+> [!WARNING]
+> Urgent information needing immediate attention.
+```
+
+> [!NOTE]
+> Useful information the reader should know.
+
+> [!WARNING]
+> Urgent information needing immediate attention.
+
+## Code tabs
+
+Group several code blocks into a tabbed panel. The text after the language is
+the tab label; it falls back to the language, then to `Tab N`.
+
+````markdown
+:::code-tabs
+
+```bash npm
+npm install
+```
+
+```bash pnpm
+pnpm install
+```
+
+:::
+````
+
+:::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.
+
+```markdown
+:::toc[On this page]
+
+- [Alerts](#alerts)
+- [Code tabs](#code-tabs)
+
+:::
+```
+
+:::toc[On this page]
+
+- [Alerts](#alerts)
+- [Code tabs](#code-tabs)
+
+:::
+
+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"`. The title is a `<p>`, so it stays
+out of `getHeadings()` and has no anchor.
+
+### Writing the anchors
+
+Heading ids come from Astro, slugged with
+[`github-slugger`](https://github.com/Flet/github-slugger):
+
+| Heading                  | Anchor                                                                   |
+| ------------------------ | ------------------------------------------------------------------------ |
+| `## Getting started`     | `#getting-started`                                                       |
+| `## Details / accordion` | `#details--accordion` (one dash per space, the `/` dropped between them) |
+| `## What's new?`         | `#whats-new` (punctuation removed, not replaced)                         |
+| `## snake_case`          | `#snake_case` (underscores survive)                                      |
+| a second `## Setup`      | `#setup-1`                                                               |
+
+The client script 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`).
+
+> [!NOTE]
+> `:::toc` needs the directive syntax, on by default. With
+> `features: { toc: false }` the block degrades to a plain `<div>`: list and
+> links intact, unstyled.
+
+## Spoilers
+
+Text hidden until the reader activates it, inline or as a block. Spoilers are
+reachable from the keyboard and hide again on reload.
+
+```markdown
+The answer is :spoiler[42].
+
+:::spoiler
+A whole paragraph, hidden.
+:::
+```
+
+The answer is :spoiler[42].
+
+:::spoiler
+A whole paragraph, hidden.
+:::
+
+In HTML you write yourself, the class is `jaamd-spoiler`.
+
+## Details
+
+`<details>` is plain HTML. JAAMD styles it and animates it open and closed, in
+CSS alone.
+
+```html
+<details>
+    <summary>Why is the sky blue?</summary>
+    Shorter wavelengths scatter more.
+</details>
+```
+
+<details>
+    <summary>Why is the sky blue?</summary>
+    Shorter wavelengths scatter more.
+</details>
+
+## Without writing anything
+
+Some enhancements need no syntax. Every heading gets an anchor link, every code
+block a copy button, every image a lightbox, and every table a scroll container
+on narrow screens. See [Client script](./03-usage/02-client.md).

package/docs/03-usage/01-markdown-content.md

@@ -0,0 +1,45 @@
+---
+description: The MarkdownContent component, which wraps rendered Markdown and loads the styles.
+---
+
+# MarkdownContent
+
+`MarkdownContent` is a polymorphic component. It renders as `<div>` by default
+and accepts any valid HTML tag via the `as` prop. It loads the stylesheets; the
+[client script](./02-client.md) the integration injects enhances its content.
+
+```ts
+import MarkdownContent from '@jaamd/astro/components'
+```
+
+## Props
+
+| Prop      | Type      | Default | Description                                                                               |
+| --------- | --------- | ------- | ----------------------------------------------------------------------------------------- |
+| `as`      | `HTMLTag` | `"div"` | The HTML element to render as.                                                            |
+| `class`   | `string`  | -       | Extra CSS classes appended to the wrapper.                                                |
+| _...rest_ | -         | -       | All standard HTML attributes for the chosen `as` element (e.g. `id`, `data-*`, `aria-*`). |
+
+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.
+
+```astro
+---
+import MarkdownContent from '@jaamd/astro/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>
+```

package/docs/03-usage/02-client.md

@@ -0,0 +1,70 @@
+---
+description: What the client script adds in the browser, and how it behaves from the keyboard.
+---
+
+# Client script
+
+A dependency-free ES module enhances the rendered markdown. The integration
+injects it on every page; it runs on the elements matching
+[`selector`](../01-getting-started/02-options.md#selector), with the
+[`features`](../01-getting-started/02-options.md#features) and
+[`labels`](../01-getting-started/02-options.md#labels) of the integration. 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).
+
+| Enhancement       | Behaviour                                                                                                                                                 |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Heading links     | Adds an anchor link to `h1`–`h6` where the build did not. Fills in a missing `id` with a `github-slugger`-compatible slug, de-duplicated across the page. |
+| Table of contents | Marks the `:::toc` entry whose section is on screen with `aria-current="location"`.                                                                       |
+| Copy buttons      | Adds a copy button to every `pre`. Without clipboard access it selects the code instead. The only clipboard write in the package.                         |
+| Image lightbox    | Wraps each image in a button that opens it in a modal `<dialog>`. Closes on <kbd>Esc</kbd>, the ✕ button or a click outside the image.                    |
+| Responsive tables | Wraps a `table` in a horizontally scrollable container where the build did not.                                                                           |
+| Code tabs         | Drives the `:::code-tabs` tablist.                                                                                                                        |
+| Spoilers          | Reveals a spoiler on click or <kbd>Enter</kbd>/<kbd>Space</kbd>.                                                                                          |
+
+## Keyboard
+
+| Element   | Keys                                                                                                                                                  |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Code tabs | <kbd>←</kbd> <kbd>→</kbd> move between tabs, <kbd>Home</kbd> <kbd>End</kbd> jump to first/last. Panels are focusable so wide samples can be scrolled. |
+| Spoilers  | <kbd>Tab</kbd> to focus, <kbd>Enter</kbd> or <kbd>Space</kbd> to reveal. Hover does not reveal.                                                       |
+| Lightbox  | <kbd>Tab</kbd> to an image, <kbd>Enter</kbd> or <kbd>Space</kbd> to open, <kbd>Esc</kbd> to close. Focus returns to the image.                        |
+
+`<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](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API)
+on the `<dialog>`, and `closedby="any"` closes it on a click outside the image.
+
+| Browser       | Lightbox | Click outside closes               |
+| ------------- | -------- | ---------------------------------- |
+| Chrome / Edge | 135+     | 134+                               |
+| Firefox       | 144+     | 141+                               |
+| Safari        | 26.2+    | not yet: <kbd>Esc</kbd> and ✕ only |
+
+Older browsers show the image as a plain image.
+
+### Excluding images from the lightbox
+
+Linked images are skipped automatically, so badges keep navigating:
+
+```markdown
+[![build](https://img.shields.io/badge/build-passing-green)](https://github.com/you/repo)
+```
+
+Opt a standalone image out with `data-no-lightbox`:
+
+```html
+<img src="/diagram.svg" alt="Architecture diagram" data-no-lightbox />
+```