@jaamd/jaad 0.0.0-stage → 1.0.0-rc.1

package/docs/02-configurations/02-frontmatter.md

@@ -0,0 +1,105 @@
+---
+description: Every frontmatter field JAAD reads, and what each one changes.
+keywords: [frontmatter, metadata, seo]
+---
+
+# Frontmatter
+
+Frontmatter is optional. Markdown without it works as-is: the filename sets the
+order and the URL, and the first `# Heading` sets the title. Each field below
+overrides something the file tree or the body already supplies.
+
+```markdown
+---
+title: Images & Videos
+label: Media
+translationKey: media
+description: Add accessible images and embedded videos.
+keywords: [markdown, media]
+order: 5
+draft: false
+author: Ada Lovelace
+ogImage: /og/media.png
+lastUpdated: 2026-09-12
+---
+
+# Images and videos
+```
+
+| Field            | Type              | Effect                                       |
+| ---------------- | ----------------- | -------------------------------------------- |
+| `title`          | `string`          | Page title, everywhere the page is named     |
+| `label`          | `string`          | Shorter name, in navigation only             |
+| `translationKey` | `string`          | Pairs this page with its translations        |
+| `description`    | `string`          | Description metadata and `llms.txt`          |
+| `order`          | `number`          | Replaces the number from the filename prefix |
+| `draft`          | `boolean`         | Kept in development, left out of the build   |
+| `keywords`       | `string[]`        | Keyword metadata, and weight in search       |
+| `author`         | `string`          | Author metadata                              |
+| `ogImage`        | `string \| false` | Social image for this page                   |
+| `lastUpdated`    | `date`            | Modification date in metadata                |
+
+Fields JAAD does not know are ignored, so frontmatter your own tooling
+reads can sit alongside these. A wrong type is a build error.
+
+## Naming
+
+`title` names the page in metadata, breadcrumbs, search and the table of
+contents. The filename still determines the URL, whatever the title says.
+
+`label` is for pages whose title is too long for a sidebar entry. It changes
+the sidebar, the mobile selectors and the previous/next links, and nothing
+else:
+
+```markdown
+---
+title: Frequently Asked Questions
+label: FAQ
+---
+```
+
+Without `title`, JAAD uses the first `# Heading`, then the filename.
+
+`translationKey` pairs a page with its translations when their slugs differ.
+See [Languages](03-i18n.md).
+
+## Ordering and drafts
+
+`order` replaces the number a filename prefix supplies, so a page can move
+without being renamed. Inside a chapter it moves the page within that chapter;
+the chapter keeps the order of its own directory prefix.
+
+```markdown
+---
+order: 0
+---
+```
+
+A page ordered ahead of every other becomes the opening page at `routeBase`.
+
+`draft` pages are served in development and left out of production builds:
+they disappear from routes, navigation, search, the sitemap and `llms.txt`.
+The file tree is still validated as a whole, so a draft that would collide
+with another page is reported while it is being written.
+
+## Metadata
+
+`description` is used for the description metadata, Open Graph, structured
+data and `llms.txt`. Without it, JAAD uses the first paragraph of the page, followed
+by the site description.
+
+`keywords` become `<meta name="keywords">` and the `keywords` of the page's
+structured data, and they rank a page in search below its chapter and above
+its body. They are metadata, not a visible list: JAAD renders nothing for
+them, though a frame of your own can, through
+[`page.data`](08-advanced-layout.md).
+
+`author` becomes `<meta name="author">` and the structured-data author.
+
+`ogImage` overrides the site's social image for one page. It takes a public
+path or an absolute URL, and `false` removes the image from that page. Local
+paths need `site` to resolve, as elsewhere.
+
+`lastUpdated` takes a date. It becomes `article:modified_time` and
+`dateModified` in structured data, and is shown under the page, formatted for
+its language.

package/docs/02-configurations/03-i18n.md

@@ -0,0 +1,210 @@
+---
+description: One documentation site per language, from locale directories under docs/.
+keywords: [i18n, locales, translation, hreflang]
+---
+
+# Languages
+
+Name the directories directly under `docs/` after language codes and JAAD
+builds one documentation site per language, with a switcher in the header.
+
+```
+docs/
+  en/
+    01-introduction.md      → /
+    02-guides/
+      01-setup.md           → /guides/setup
+  it/
+    01-introduzione.md      → /it
+    02-guide/
+      01-installazione.md   → /it/guide/installazione
+```
+
+Nothing needs configuring. With one language, or with no locale directory at
+all, everything behaves exactly as it did before.
+
+## Detection
+
+A directory is a locale when its name is an ISO 639-1 language, optionally with
+a script and a region: `it`, `pt-BR`, `zh-Hans`. A three-letter directory such
+as `api` is never a locale.
+
+**Two directories make the tree localised.** A single one counts only when
+`lang` names it — so `docs/en/` with `lang: "en"` is a first language you are
+about to translate, while a lone `docs/it/` on an English site stays the
+chapter an "IT" section depends on.
+
+A locale directory with no markdown in it is not a language: it would be
+offered in the switcher and then answer 404. It is dropped, and if that leaves
+one language the documentation stays localised — the remaining directory is
+still stripped from the URLs, so nothing moves.
+
+Once the tree is localised, every entry under `docs/` has to be a locale
+directory. A stray one stops the build and is named:
+
+```
+jaad: mixed documentation tree
+  docs/guides is not a locale, but en, it are
+Move every page under a locale directory, or set locales: false.
+```
+
+The nesting limit applies inside each language, not to the tree as a whole:
+`it/guides/setup.md` is a chapter inside Italian, and still only one level.
+
+## The default language
+
+`lang` names the language that keeps the unprefixed URLs:
+
+```ts
+defineJaadConfig({ title: 'My Project', lang: 'en' })
+```
+
+`/guide` is English and `/it/guide` is Italian. Adding a second language to an
+existing site therefore changes none of its URLs. `lang` must match one of the
+directories, or the build stops and lists what it found.
+
+## Overriding detection
+
+`locales` is only for when detection guesses wrong:
+
+```ts
+defineJaadConfig({ title: 'My Project', locales: ['en', 'it'] })
+defineJaadConfig({ title: 'My Project', locales: false })
+```
+
+A list pins the set. `false` switches detection off, so every directory is a
+chapter again.
+
+## Pairing translations
+
+Two pages are translations of each other when their slugs match:
+`en/guides/setup.md` and `it/guides/setup.md` both resolve to `guides/setup`.
+That is the whole rule, and it is why nothing pairs when a language translates
+its own file and directory names.
+
+To translate the URLs too, give both files the same `translationKey`:
+
+```markdown
+---
+translationKey: setup
+---
+```
+
+```
+docs/en/02-handbook/01-setup.md        → /handbook/setup
+docs/it/02-guida/01-installazione.md   → /it/guida/installazione
+```
+
+With the key the two link to each other in the switcher and in `hreflang`;
+without it neither would know the other existed. Two pages of one language
+claiming the same key stop the build.
+
+## Untranslated pages
+
+Each language has exactly the pages in its own directory. There is no fallback:
+a page that exists only in English is not built under `/it`, does not appear in
+the Italian sidebar, and is not in the Italian search index or `llms.txt`.
+
+A language whose every page is a [draft](02-frontmatter.md)
+empties out in the production build, and drops out of the switcher there too.
+
+The switcher accounts for this. On a page with no counterpart in a language, it
+links to that language's opening page rather than to a URL that would 404.
+
+## The switcher
+
+It sits next to the theme switcher and shows the current language's flag and
+code, with the languages' own names in the menu. It renders only when there is
+more than one language.
+
+Flags come from the region: explicit in `pt-BR`, and otherwise from the
+language's usual one. A language with no usual region shows its code alone —
+better than a wrong flag.
+
+## Metadata
+
+Per-language metadata is handled for you:
+
+| Tag                      | Value                                   |
+| ------------------------ | --------------------------------------- |
+| `<html lang>`            | The page's language                     |
+| `og:locale`              | The page's language                     |
+| `og:locale:alternate`    | Every language that has this page       |
+| `<link rel="alternate">` | `hreflang` per translation, `x-default` |
+
+`hreflang` links need absolute URLs, so they are emitted only when `site` is
+set, like `canonical`.
+
+Everything in [frontmatter](02-frontmatter.md) is per file, so
+`description`, `keywords` and the rest are already per language: write them in
+the language of the file they sit in.
+
+Each language also gets its own search index and `llms.txt`, at
+`/it/llms.txt` and so on. Search only ever returns pages in the language the
+reader is in.
+
+## The interface
+
+JAAD ships its own interface in English and Italian. It picks the catalogue
+from each page's locale automatically, so Italian documentation needs no UI
+configuration. Regional locales inherit their base language: `it-IT` and
+`it-CH` both use Italian.
+
+Use `ui` only for wording you want to replace:
+
+```ts
+defineJaadConfig({
+    title: 'My Project',
+    ui: {
+        it: {
+            'search.trigger': 'Cerca…',
+            'page.copy': 'Copia la pagina',
+        },
+    },
+})
+```
+
+Overrides are matched case-insensitively. An exact override comes first, then
+one for the base language, then the bundled catalogue. A locale without a
+bundled catalogue falls back to English. For example, `ui["it-IT"]` wins over
+`ui.it`, while the latter also applies to `it-CH`.
+
+An override can therefore stay partial without blanking or changing any other
+label. These are all the keys and their English fallback values:
+
+```ts
+ui: {
+  en: {
+    "breadcrumb.label": "Breadcrumb",
+    home: "Home",
+    "locale.change": "Change language",
+    "nav.documentation": "Documentation navigation",
+    "nav.mobile": "Toggle mobile menu",
+    "nav.page": "Page navigation",
+    "page.copied": "Copied!",
+    "page.copy": "Copy page",
+    "page.edit": "Edit this page",
+    "page.lastUpdated": "Last updated on",
+    "search.all": "All",
+    "search.close": "close",
+    "search.empty": "No results for",
+    "search.label": "Search documentation",
+    "search.loading": "Loading...",
+    "search.navigate": "navigate",
+    "search.open": "open",
+    "search.placeholder": "Search documentation...",
+    "search.results": "Search results",
+    "search.sections": "Search in",
+    "search.trigger": "Search docs...",
+    "theme.toggle": "Toggle color theme",
+    "toc.label": "Table of contents",
+    "toc.title": "On this page",
+  },
+},
+```
+
+To add another bundled language, see the
+[translation contribution guide](https://github.com/jaamd/jaamd/blob/main/CONTRIBUTING.md#translating-the-interface).
+
+Your documentation, its navigation, its chapter names and its metadata come
+from your files and are already in whatever language you wrote them.

package/docs/02-configurations/04-search.md

@@ -0,0 +1,58 @@
+---
+description: What JAAD's search indexes, how it ranks results, and the keyboard shortcuts.
+---
+
+# Search
+
+Every JAAD site has full-text search, with no configuration and no external
+service. Readers open it from the header or with <kbd>Ctrl</kbd>+<kbd>K</kbd>
+(<kbd>⌘</kbd>+<kbd>K</kbd> on macOS).
+
+## What is indexed
+
+The build cuts every page at its `##` and `###` headings and indexes each part
+with:
+
+- the page title, its chapter and its `keywords`;
+- the heading;
+- the text below it, excluding code blocks, images and directives.
+
+Drafts are left out of production builds. The index is emitted at
+`<routeBase>/search-index.json`, one per language, loaded on first use and
+cached for the session. It holds the text of every page, so its size grows with
+the documentation.
+
+## How results are found
+
+- Every word of the query must appear in a part of a page or in the page's
+  title, chapter or keywords.
+- A word also matches the words it starts: `config` finds `configuration`.
+- Case and accents are ignored: `citta` finds `città`.
+- A match in the title ranks first, then the heading, the keywords, the
+  chapter and the text.
+
+Results are grouped by page. Under each page are the headings that matched,
+and choosing one opens the page at that heading.
+
+With an empty query, search lists the first pages of the documentation. When
+the docs have [sections](../01-getting-started/02-pages.md#sections), it lists
+the first pages of each, and buttons above the results limit the search to one
+section.
+
+## Keyboard shortcuts
+
+| Where  | Keys                                                      | Action                  |
+| ------ | --------------------------------------------------------- | ----------------------- |
+| Search | <kbd>Ctrl</kbd>+<kbd>K</kbd> or <kbd>⌘</kbd>+<kbd>K</kbd> | Open the search palette |
+| Search | <kbd>↑</kbd> <kbd>↓</kbd>                                 | Select a result         |
+| Search | <kbd>Enter</kbd>                                          | Open the result         |
+| Search | <kbd>Esc</kbd>                                            | Close the palette       |
+| Page   | <kbd>←</kbd>                                              | Open the previous page  |
+| Page   | <kbd>→</kbd>                                              | Open the next page      |
+
+The page shortcuts are off while:
+
+- an input, textarea, select or editable element has focus;
+- the focus is inside a sideways-scrollable area, such as a wide table or code
+  block;
+- a modifier key is held.

package/docs/02-configurations/05-themes.md

@@ -0,0 +1,104 @@
+---
+description: Named themes, a fixed appearance, code themes and custom palettes.
+---
+
+# Themes
+
+Dark mode works without configuration. The default `appearance: "auto"`
+follows the reader's system preference and shows a switcher.
+
+## Named themes
+
+```ts
+defineJaadConfig({ title: 'My Project', theme: 'dracula' })
+```
+
+| Name             | Light         | Dark         |
+| ---------------- | ------------- | ------------ |
+| `default`        | Paper         | GitHub Dark  |
+| `catppuccin`     | Latte         | Mocha        |
+| `gruvbox`        | Gruvbox Light | Gruvbox Dark |
+| `rose-pine`      | Dawn          | Rosé Pine    |
+| `rose-pine-moon` | Dawn          | Moon         |
+| `dracula`        | Dracula       | Dracula      |
+| `nord`           | Nord          | Nord         |
+| `one-dark`       | One Dark      | One Dark     |
+| `tokyo-night`    | Tokyo Night   | Tokyo Night  |
+
+Unknown names stop the build. Themes without a light palette stay dark in both
+modes; use `appearance: "dark"` for a consistently dark site.
+
+## Fixed appearance
+
+```ts
+defineJaadConfig({
+    title: 'My Project',
+    theme: 'tokyo-night',
+    appearance: 'dark',
+})
+```
+
+`"light"` and `"dark"` remove the switcher and the client-side preference
+script. The default is `"auto"`.
+
+## Code theme only
+
+Pass a [Shiki](https://shiki.style/themes) pair to change syntax highlighting
+without changing the interface colours:
+
+```ts
+defineJaadConfig({
+    title: 'My Project',
+    theme: { light: 'github-light', dark: 'github-dark' },
+})
+```
+
+## Custom themes
+
+Set theme seeds in `src/jaad.css`:
+
+```css
+:root,
+html.dark {
+    --color-background: #1e1e2e;
+    --color-surface: #313244;
+    --color-foreground: #cdd6f4;
+    --color-foreground-bright: #f5f5f5;
+    --color-primary: #89b4fa;
+    --color-error: #f38ba8;
+    --color-warning: #f9e2af;
+    --color-info: #89dceb;
+    --color-success: #a6e3a1;
+}
+```
+
+Use `:root` for light mode and `html.dark` for dark mode. Override individual
+`--jaamd-` tokens only when a palette needs values that cannot derive from the
+seeds.
+
+## Sharing the theme with your own pages
+
+[Pages of your own](07-custom-pages.md) use your layout, not
+JAAD's. Two values keep both halves of a site in step:
+
+| What                      | Value                         |
+| ------------------------- | ----------------------------- |
+| Class on `<html>` in dark | `dark`                        |
+| Stored preference         | `localStorage["theme"]`       |
+| Stored values             | `"dark"` / `"light"`          |
+| No stored value           | follow `prefers-color-scheme` |
+
+Apply the class in the `<head>`, before anything paints:
+
+```astro
+<script is:inline>
+    ;(function () {
+        var t = localStorage.getItem('theme')
+        var dark = t === 'dark' || (!t && matchMedia('(prefers-color-scheme: dark)').matches)
+        document.documentElement.classList.toggle('dark', dark)
+    })()
+</script>
+```
+
+Write `"dark"` or `"light"` to that key from your own switcher. JAAD reads it
+again on the next documentation page.

package/docs/02-configurations/06-styles.md

@@ -0,0 +1,156 @@
+---
+description: Colours, fonts and widths as CSS custom properties in src/jaad.css, and Tailwind.
+---
+
+# Styles
+
+JAAD's look is a set of CSS custom properties. Override them in
+`src/jaad.css`, which loads after the bundled stylesheet on documentation pages
+and on pages using `Page`:
+
+```css
+:root {
+    --color-primary: #3b5bdb;
+    --color-background: #ffffff;
+}
+
+html.dark {
+    --color-primary: #748ffc;
+    --color-background: #0d1117;
+}
+```
+
+JAAD ships its stylesheet compiled and adds nothing to your project. Use any
+CSS for pages of your own.
+
+## Colour tokens
+
+| Token                | Purpose                          |
+| -------------------- | -------------------------------- |
+| `--color-background` | Page background                  |
+| `--color-foreground` | Body text                        |
+| `--color-primary`    | Links, accents and active states |
+| `--color-surface`    | Raised surfaces                  |
+| `--color-border`     | Separators and outlines          |
+
+The complete groups are:
+
+- Backgrounds: `--color-background`, `--color-background-secondary`,
+  `--color-background-tertiary`, `--color-surface`, `--color-surface-hover`.
+- Text: `--color-foreground`, `--color-foreground-secondary`,
+  `--color-foreground-muted`, `--color-foreground-bright`.
+- Accent: `--color-primary`, `--color-primary-dark`, `--color-primary-light`.
+- Borders: `--color-border`, `--color-border-light`, `--color-border-dark`.
+- Status: `--color-error`, `--color-warning`, `--color-info`, `--color-success`.
+
+The rendered Markdown follows these colours. To change it alone, set JAAMD's
+`--jaamd-*` [variables](../../../astro/docs/04-styling/01-variables.md). For a
+whole palette, see [Themes](05-themes.md).
+
+## Fonts
+
+JAAD uses self-hosted Inter for the interface and Merriweather for headings.
+Three tokens choose the families:
+
+```css
+:root {
+    --font-sans: 'IBM Plex Sans', system-ui, sans-serif;
+    --font-serif: 'IBM Plex Serif', Georgia, serif;
+    --font-mono: 'IBM Plex Mono', monospace;
+}
+```
+
+A token does not load the font. Add the family with Astro's font
+configuration, then point the token at its CSS variable:
+
+```ts
+// jaad.config.ts
+import { defineJaadConfig } from '@jaamd/jaad'
+import { fontProviders } from 'astro/config'
+
+export default defineJaadConfig({
+    title: 'My Project',
+    astro: {
+        fonts: [
+            {
+                provider: fontProviders.google(),
+                name: 'IBM Plex Sans',
+                cssVariable: '--font-plex',
+                weights: [400, 600],
+            },
+        ],
+    },
+})
+```
+
+```css
+:root {
+    --font-sans: var(--font-plex), system-ui, sans-serif;
+}
+```
+
+For system fonts only, point the tokens at a system stack. JAAD's bundled
+fonts are still downloaded during the build even when unused.
+
+## Layout tokens
+
+| Token                  | Default                                           |
+| ---------------------- | ------------------------------------------------- |
+| `--jaad-chrome-width`  | content, both sidebars and their gaps             |
+| `--jaad-content-width` | `56rem`, the most the page column takes           |
+| `--jaad-sidebar-width` | `16rem`, the navigation and the table of contents |
+| `--jaad-page-padding`  | `2rem`, on each side of the page                  |
+| `--jaad-header-height` | `4.25rem`, the fixed header                       |
+
+`--jaad-chrome-width` is the column the header, the sidebars and the page share.
+The header and the two sidebars are fixed to the window, and only the page
+scrolls; raise `--jaad-header-height` along with a logo taller than the header.
+Set it to fit the documentation to the width of the rest of a site; the page
+column takes what the sidebars leave, up to `--jaad-content-width`:
+
+```css
+:root {
+    --jaad-chrome-width: 80rem;
+    --jaad-sidebar-width: 14rem;
+}
+```
+
+Use [Advanced layout](08-advanced-layout.md) when token changes are not
+enough.
+
+## Tailwind
+
+:::code-tabs
+
+```bash npm
+npm i -D tailwindcss @tailwindcss/vite
+```
+
+```bash pnpm
+pnpm add -D tailwindcss @tailwindcss/vite
+```
+
+```bash yarn
+yarn add -D tailwindcss @tailwindcss/vite
+```
+
+```bash bun
+bun add -d tailwindcss @tailwindcss/vite
+```
+
+:::
+
+```ts
+// jaad.config.ts
+defineJaadConfig({ title: 'My Project', tailwind: true })
+```
+
+JAAD registers the plugin, unless `astro.vite.plugins` already has it.
+
+- Applies to documentation pages, pages using `Page` and a custom `DocsFrame`.
+- Colours and fonts follow JAAD's tokens: `bg-surface`, `border-border-light`,
+  `font-mono`.
+- `dark:` follows JAAD's theme switch.
+- Layout tokens via arbitrary values: `max-w-(--jaad-chrome-width)`.
+- Pages on a local layout get plain Tailwind (no JAAD tokens) by adding
+  `@import "tailwindcss";` to their CSS.