@jaamd/jaad 0.11.0 → 1.0.0

package/docs/02-configurations/07-custom-pages.md

@@ -0,0 +1,119 @@
+---
+description: "Pages of your own beside the documentation, with your layout or with JAAD's."
+---
+
+# Custom pages
+
+Files in `src/pages/` are regular Astro pages. They keep their own layouts,
+styles and metadata; JAAD options affect only documentation below `routeBase`.
+
+The `site` template creates a local layout and landing page, then mounts the
+documentation at `/docs`:
+
+:::code-tabs
+
+```bash npm
+npm create @jaamd/jaad@latest my-site -- --template site
+```
+
+```bash pnpm
+pnpm create @jaamd/jaad@latest my-site --template site
+```
+
+```bash yarn
+yarn create @jaamd/jaad@latest my-site --template site
+```
+
+```bash bun
+bun create @jaamd/jaad@latest my-site --template site
+```
+
+:::
+
+```
+src/
+  layouts/SiteLayout.astro
+  pages/index.astro
+  styles/site.css
+  utils/base.ts
+public/
+  favicon.svg
+docs/
+  01-introduction.md
+tsconfig.json
+```
+
+`utils/base.ts` exports `withBase()`, which applies Astro's deployment base to
+a root-relative href. Use it for every link the layout writes, so the site keeps
+working when it moves to a subpath.
+
+Use the generated layout for other application pages:
+
+```astro
+---
+import SiteLayout from '../layouts/SiteLayout.astro'
+---
+
+<SiteLayout pageTitle="Pricing">
+    <h1>Pricing</h1>
+</SiteLayout>
+```
+
+JAAD still generates documentation pages, search, `llms.txt`, raw Markdown
+routes and the sitemap without controlling the rest of the application.
+
+## Keeping JAAD's header and footer
+
+A site with a landing page of its own wants its own identity, and a local
+layout is the right answer for it. A documentation-first site is the other
+case: when `routeBase` is `/` and you add one page beside the documentation —
+a changelog, a pricing page — rebuilding the header and footer to match would
+be work spent on looking the same.
+
+Import the page layout instead:
+
+```astro
+---
+import Page from '@jaamd/jaad/layouts/Page.astro'
+---
+
+<Page title="Changelog">
+    <h1>Changelog</h1>
+</Page>
+```
+
+It renders the documentation header and footer, the theme, and your
+configuration's title, navigation and social links around whatever you put
+inside. `title` and `description` set the metadata for the page; `bare` drops
+the default spacing when the content needs the full width; `class` is added to
+the body.
+
+Search comes with the header. A documentation page shows the full search field;
+a page outside the documentation shows the magnifier alone, because
+<kbd>Ctrl</kbd>/<kbd>⌘</kbd> + <kbd>K</kbd> opens the palette there too and the
+icon is what says so. Clicking it opens the same palette.
+
+This is the site chrome, not the reading layout: there is no sidebar and no
+table of contents, because a page outside the documentation has no place in
+its navigation. To restructure documentation pages themselves, use
+[Advanced layout](08-advanced-layout.md).
+
+## Matching the documentation's layout
+
+- `.jaad-chrome`: the column shared by header, footer and documentation
+  content, as wide as `--jaad-chrome-width`.
+- `.jaad-main`: vertical margin and horizontal padding of the main landmark.
+  `bare` swaps it for `.jaad-main-bare`, which has none.
+- Layout tokens (`--jaad-content-width`, `--jaad-page-padding`, …) are listed
+  in [Styles](06-styles.md).
+
+```astro
+<Page title="Changelog">
+    <div class="jaad-chrome">…</div>
+</Page>
+```
+
+## Tailwind
+
+With `tailwind: true`, utilities on `Page` pages use JAAD's tokens. See
+[Styles](06-styles.md#tailwind).

package/docs/02-configurations/08-advanced-layout.md

@@ -0,0 +1,139 @@
+---
+description: Replace the documentation page layout with a DocsFrame of your own.
+---
+
+# Advanced layout
+
+Use the default layout unless the documentation needs a different structure.
+To replace it, create:
+
+```
+src/jaad/DocsFrame.astro
+```
+
+JAAD detects the file automatically. Restart the development server after
+creating it; later edits are watched.
+
+The frame controls `<body data-docs>`. JAAD still owns the HTML document,
+metadata, theme, fonts, view transitions and keyboard navigation.
+
+## Frame contract
+
+| Slot                | Contents                                      |
+| ------------------- | --------------------------------------------- |
+| `header`            | Header, navigation and search                 |
+| `sidebar`           | Desktop page navigation, every section open   |
+| `mobile-navigation` | Mobile navigation and table of contents menus |
+| `breadcrumbs`       | Section and chapter of the page               |
+| `page-actions`      | Copy and edit actions                         |
+| `content`           | Rendered Markdown article                     |
+| `page-navigation`   | Previous and next links                       |
+| `table-of-contents` | Desktop heading navigation                    |
+| `footer`            | Documentation footer                          |
+
+Omitting a slot removes that element from every documentation page.
+
+```astro
+---
+import type { DocsFrameProps } from '@jaamd/jaad/advanced'
+
+type Props = DocsFrameProps
+const { page, headings } = Astro.props
+---
+
+<div class="docs-frame" data-page={page.id}>
+    <slot name="header" />
+    <slot name="mobile-navigation" />
+
+    <div class="docs-grid">
+        <aside class="docs-aside">
+            <slot name="sidebar" />
+        </aside>
+        <main>
+            <slot name="breadcrumbs" />
+            <slot name="page-actions" />
+            <slot name="content" />
+            <slot name="page-navigation" />
+        </main>
+        {headings.length > 0 && (
+            <aside class="docs-aside">
+                <slot name="table-of-contents" />
+            </aside>
+        )}
+    </div>
+
+    <slot name="footer" />
+</div>
+
+<style>
+    .docs-grid {
+        display: grid;
+        grid-template-columns: minmax(0, 56rem);
+        justify-content: center;
+    }
+
+    .docs-aside {
+        display: none;
+    }
+
+    @media (min-width: 64rem) {
+        .docs-grid {
+            grid-template-columns: 16rem minmax(0, 56rem) 16rem;
+        }
+
+        .docs-aside {
+            display: block;
+        }
+    }
+</style>
+```
+
+Wrap the slots you need to position in elements of your own, and style those.
+
+`DocsFrameProps` exposes the current page, headings and navigation model for
+conditional placement. JAAD's internal components are not part of this API.
+
+| Property                  | Contents                                     |
+| ------------------------- | -------------------------------------------- |
+| `page.id`                 | Content collection ID                        |
+| `page.slug`               | File-derived slug, including the opening one |
+| `page.title`              | Resolved page title                          |
+| `page.section`            | Section key, when the docs have sections     |
+| `page.chapter`            | Chapter slug, when present                   |
+| `headings`                | `{ depth, slug, text }[]` for levels 2 and 3 |
+| `navigation.groups`       | The whole tree: sections, chapters and pages |
+| `navigation.previousPage` | Previous navigation item or `null`           |
+| `navigation.nextPage`     | Next navigation item or `null`               |
+
+`page.chapter` and a chapter group's `chapter` are directory slugs, such as
+`getting-started`. Title-case them for display.
+
+### Navigation shapes
+
+`DocsNavGroup` is a union discriminated on `type`. With sections, every group
+is a `section`, holding the pages and chapters of that section.
+
+```ts
+type DocsNavEntry = { type: 'page'; item: DocsNavItem } | { type: 'chapter'; chapter: string; items: DocsNavItem[] }
+
+type DocsNavGroup = DocsNavEntry | { type: 'section'; section: string; label: string; entries: DocsNavEntry[] }
+
+interface DocsNavItem {
+    title: string
+    section?: string
+    chapter?: string
+    href: string
+    isActive: boolean
+}
+```
+
+Groups and their items arrive in display order.
+
+`href` already carries `routeBase` and the deployment `base`. `isActive` marks
+the current page.
+
+`DocsFrameProps`, `DocsNavigation`, `DocsNavGroup`, `DocsNavEntry`,
+`DocsHeading`, `DocsNavItem` and `DocsPageData` are exported from `@jaamd/jaad/advanced`.
+
+For colours, fonts, widths and spacing, use
+[`src/jaad.css`](06-styles.md) instead.

package/docs/03-upgrading.md

@@ -0,0 +1,208 @@
+---
+description: How to upgrade JAAD, and the changes that need action, by the version you upgrade from.
+---
+
+# Upgrading
+
+JAAD is usually upgraded together with Astro: each JAAD release targets one Astro
+major, and most releases follow an Astro release. Upgrade both at once:
+
+:::code-tabs
+
+```bash npm
+npx @astrojs/upgrade
+```
+
+```bash pnpm
+pnpm dlx @astrojs/upgrade
+```
+
+```bash yarn
+yarn dlx @astrojs/upgrade
+```
+
+```bash bun
+bunx @astrojs/upgrade
+```
+
+:::
+
+To upgrade JAAD alone:
+
+:::code-tabs
+
+```bash npm
+npm install @jaamd/jaad@latest
+```
+
+```bash pnpm
+pnpm add @jaamd/jaad@latest
+```
+
+```bash yarn
+yarn add @jaamd/jaad@latest
+```
+
+```bash bun
+bun add @jaamd/jaad@latest
+```
+
+:::
+
+Then run a build and read below the changes since the version you upgrade from.
+
+## From 0.10 and 0.11
+
+### The package is now @jaamd/jaad
+
+`@lancher-dev/jaad` is now `@jaamd/jaad`, and `@lancher-dev/create-jaad` is
+`@jaamd/create-jaad`. The old packages are deprecated and receive no further
+releases. `@jaamd/jaad` 0.11 was 0.10 under the new scope: from it, skip to
+the next heading.
+
+:::code-tabs
+
+```bash npm
+npm uninstall @lancher-dev/jaad
+npm install @jaamd/jaad
+```
+
+```bash pnpm
+pnpm remove @lancher-dev/jaad
+pnpm add @jaamd/jaad
+```
+
+```bash yarn
+yarn remove @lancher-dev/jaad
+yarn add @jaamd/jaad
+```
+
+```bash bun
+bun remove @lancher-dev/jaad
+bun add @jaamd/jaad
+```
+
+:::
+
+Then replace `@lancher-dev/jaad` with `@jaamd/jaad` in every import:
+`astro.config.*`, `src/content.config.*`, `jaad.config.ts`, and any page using
+`@jaamd/jaad/layouts/Page.astro` or `@jaamd/jaad/advanced`.
+
+The documentation moved from `jaad.lancher.dev` to `docs.jaamd.org/jaad`: update
+the links in `AGENTS.md` if `create-jaad` generated one.
+
+### JAAMD is now @jaamd/astro
+
+JAAD installs it for you: a site that only uses `@jaamd/jaad` has nothing to do.
+A project that imports `@lancher-dev/jaamd` or `@jaamd/jaamd` directly follows
+[JAAMD's upgrade guide](../../astro/docs/06-upgrading.md#from-011).
+
+### Page titles name their section
+
+With [sections](01-getting-started/02-pages.md#sections), the browser title of
+a page is `Page · Section | Site`, so pages with the same name in two sections
+no longer share a title. Docs without sections are unchanged.
+
+### A fixed shell
+
+The header and both sidebars are fixed to the window and only the page
+scrolls. They sit in one column, `--jaad-chrome-width`, which now defaults to
+the sidebars, the page and their gaps; to fit the documentation to a site of
+your own, set it. See [Layout tokens](02-configurations/06-styles.md#layout-tokens).
+
+- The sidebar lists every section with all its pages, under the section's name.
+- Above the title, the page shows its section and chapter instead of a full
+  breadcrumb trail.
+- Copy and edit sit under the table of contents, in the right column.
+- Previous and next are a line of text, and the footer closes the page column.
+- On narrow screens, a menu named after the current page opens the navigation,
+  and another opens the table of contents. The scroll-to-top button is gone.
+
+`--jaad-sidebar-offset` and the `.docs-main-gutters` class are gone: set
+`--jaad-chrome-width` and `--jaad-sidebar-width` instead. The `ui` keys
+`breadcrumb.root`, `nav.jumpToSection`, `nav.selectPage` and `scrollTop` are no
+longer used: remove them from your overrides.
+
+### Custom docs frame: renamed navigation types
+
+"Section" now names a part of the documentation with its own directory. A
+`src/jaad/DocsFrame.astro` that reads the navigation follows these renames:
+
+| Before                          | After               |
+| ------------------------------- | ------------------- |
+| `navigation.sections`           | `navigation.groups` |
+| `NavSection`                    | `DocsNavGroup`      |
+| `DocsHeadings`                  | `DocsHeading`       |
+| `order` on a group              | removed             |
+| `primaryOrder` on `DocsNavItem` | removed             |
+
+Groups and items arrive in display order, so nothing replaces the two removed
+fields.
+
+`DocsEntry` is no longer exported: no prop of the frame carried it. The page a
+frame renders is `DocsFrameProps['page']`.
+
+### Search index
+
+`search-index.json` now holds one entry per heading, for
+[search by heading](02-configurations/04-search.md). Its format is internal to
+JAAD's search and can change in any release: do not read it from code of your
+own.
+
+### Fewer exports
+
+`@jaamd/jaad` exports `jaad()`, `defineJaadConfig()` and the `JaadUserConfig`
+type. `defineJaadSite`, `JaadConfig` and `JaadResolvedConfig` are gone:
+`@jaamd/jaad/site` builds the Astro configuration, and the resolved
+configuration, `virtual:jaad/config` included, is internal.
+
+## From 0.9
+
+### Tailwind on your own pages
+
+0.9 left Tailwind to the site: plugin in `astro.vite.plugins` and a stylesheet
+importing `tailwindcss`. Replace both with the option:
+
+```ts
+// jaad.config.ts
+defineJaadConfig({ title: 'My Project', tailwind: true })
+```
+
+- Remove `@tailwindcss/vite` from `astro.vite.plugins`. If it stays, JAAD
+  leaves it and skips its own.
+- Remove CSS that imports `tailwindcss` for pages using `Page`: it adds a second
+  preflight and Tailwind's default fonts over JAAD's. Utilities now read JAAD's
+  tokens directly (`bg-surface`, `text-primary`), with no `@theme` to write.
+- Pages on a local layout keep their own `@import "tailwindcss";`.
+- `tailwindcss` and `@tailwindcss/vite` stay in your devDependencies.
+
+See [Styles](02-configurations/06-styles.md#tailwind).
+
+### Component classes
+
+JAAD's markup no longer uses Tailwind utilities: every element has a
+`jaad-*` or `docs-*` class, styled in `@layer components`. CSS that targeted
+utilities in JAAD's markup needs the new names:
+
+| Before                           | Now                                   |
+| -------------------------------- | ------------------------------------- |
+| `body` utilities                 | `.jaad-body`                          |
+| default frame wrapper `contents` | `.docs-frame`                         |
+| `.theme-icon-to-dark` / `-light` | `.jaad-theme-icon-to-dark` / `-light` |
+| active ToC link class            | `[aria-current="location"]`           |
+
+`dist/jaad.css` no longer contains stray utilities (`.hidden`, `.block`,
+`.relative`, …). Pages that used them without Tailwind need `tailwind: true` or
+their own CSS.
+
+## From 0.8
+
+JAAD ships a precompiled stylesheet and no longer depends on Tailwind. Until
+0.8 its Tailwind plugin also generated the utilities used in your own pages;
+from 0.9 those classes are missing unless the site provides Tailwind. Use
+`tailwind: true` (see [From 0.9](#from-09)).
+
+## From 0.7
+
+`@jaamd/jaad/layouts/Base.astro` is gone. It forwarded every prop to the
+page layout: change the import to `@jaamd/jaad/layouts/Page.astro`.

package/index.ts

@@ -1,16 +1,17 @@
 import type { AstroIntegration } from 'astro'
 import sitemap from '@astrojs/sitemap'
-import jaamd from '@jaamd/jaamd'
-import { defineConfig } from 'astro/config'
-import { resolveConfig, resolveStylesheets, type JaadUserConfig } from './src/config.ts'
-import { createCoreIntegration, createIntegrationState, createSitemapFilter } from './src/integration.ts'
+import jaamd from '@jaamd/astro'
+import { resolveConfig, type JaadUserConfig } from './src/config.ts'
+import { createIntegrationState, createSitemapFilter } from './src/docs/integration.ts'
+import { createJaadIntegration } from './src/integration.ts'
+import { resolveStylesheets } from './src/site/config.ts'
 
 /** The whole set: Astro flattens nested arrays in `integrations`. */
 export default function jaad(options: JaadUserConfig): AstroIntegration[] {
     const config = resolveConfig(options)
     const css = resolveStylesheets(config)
     const state = createIntegrationState()
-    const core = createCoreIntegration(config, css, state, Boolean(options.site))
+    const core = createJaadIntegration(config, css, state, Boolean(options.site))
 
     // Without `site` the sitemap integration can only warn and skip.
     return [
@@ -18,7 +19,7 @@ export default function jaad(options: JaadUserConfig): AstroIntegration[] {
         ...(options.site
             ? [
                   sitemap({
-                      filter: createSitemapFilter(config.docsBase, state, config.defaultLocale),
+                      filter: createSitemapFilter(config.docs.base, state, config.defaultLocale),
                   }),
               ]
             : []),
@@ -26,20 +27,5 @@ export default function jaad(options: JaadUserConfig): AstroIntegration[] {
     ]
 }
 
-/** The whole Astro config for a JAAD site. `astro` is merged in, with its
- *  integrations appended rather than replacing ours. */
-export function defineJaadSite(options: JaadUserConfig) {
-    const { site, base, astro } = options
-    const extra = astro ?? {}
-    const extraIntegrations = Array.isArray(extra.integrations) ? (extra.integrations as AstroIntegration[]) : []
-
-    return defineConfig({
-        ...(site ? { site } : {}),
-        ...(base ? { base } : {}),
-        ...extra,
-        integrations: [...jaad(options), ...extraIntegrations],
-    })
-}
-
 export { defineJaadConfig } from './src/config.ts'
-export type { JaadUserConfig, JaadConfig, JaadResolvedConfig } from './src/config.ts'
+export type { JaadUserConfig } from './src/config.ts'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaamd/jaad",
-  "version": "0.11.0",
+  "version": "1.0.0",
   "description": "Turn a folder of markdown into a documentation site. An Astro integration.",
   "keywords": [
     "astro",
@@ -10,7 +10,7 @@
     "markdown",
     "withastro"
   ],
-  "homepage": "https://jaamd.org/docs/jaad",
+  "homepage": "https://docs.jaamd.org/jaad",
   "bugs": "https://github.com/jaamd/jaamd/issues",
   "license": "MIT",
   "author": "Kasui92 <info@lucapattocchio.dev>",
@@ -24,15 +24,16 @@
     "site.ts",
     "src",
     "dist",
+    "docs",
     "README.md",
     "LICENSE"
   ],
   "type": "module",
   "exports": {
     ".": "./index.ts",
-    "./advanced": "./src/advanced.ts",
-    "./content": "./src/content.ts",
-    "./layouts/Page.astro": "./src/layouts/Page.astro",
+    "./advanced": "./src/docs/advanced.ts",
+    "./content": "./src/docs/content.ts",
+    "./layouts/Page.astro": "./src/docs/layouts/Page.astro",
     "./site": "./site.ts"
   },
   "publishConfig": {
@@ -40,7 +41,7 @@
   },
   "dependencies": {
     "@astrojs/sitemap": "^3.7.4",
-    "@jaamd/jaamd": "^0.12.0",
+    "@jaamd/astro": "^1.0.0",
     "github-slugger": "^2.0.0"
   },
   "devDependencies": {
@@ -49,7 +50,7 @@
   },
   "peerDependencies": {
     "@tailwindcss/vite": "^4.3.0",
-    "astro": ">=7.0.0 <8.0.0",
+    "astro": "^7.3.0",
     "tailwindcss": "^4.3.0"
   },
   "peerDependenciesMeta": {
@@ -64,10 +65,10 @@
     "node": ">=22.12.0"
   },
   "scripts": {
-    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tailwindcss -i ./src/styles/global.css -o ./dist/jaad.css",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tailwindcss -i ./src/styles.css -o ./dist/jaad.css",
     "check": "astro check && tsc --noEmit -p tests",
     "test": "node --test \"tests/unit/**/*.test.ts\" \"tests/unit/**/*.test.mjs\"",
-    "test:consumer": "node --test \"tests/consumer/**/*.test.mjs\"",
+    "test:consumer": "pnpm --filter \"@jaamd/jaad...\" run build && node --test \"tests/consumer/**/*.test.mjs\"",
     "test:build": "pnpm --filter jaad-fixture build && node --test \"tests/build/**/*.test.mjs\""
   }
 }

package/site.ts

@@ -1,8 +1,10 @@
 import type { JaadUserConfig } from './src/config.ts'
+import type { AstroIntegration } from 'astro'
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { defineJaadSite } from './index.ts'
+import { defineConfig } from 'astro/config'
+import jaad from './index.ts'
 
 const CANDIDATES = ['jaad.config.ts', 'jaad.config.mjs', 'jaad.config.js']
 
@@ -16,4 +18,19 @@ const loaded = (await import(/* @vite-ignore */ pathToFileURL(file).href)) as {
     default: JaadUserConfig
 }
 
+/** The whole Astro config for a JAAD site. `astro` is merged in, with its
+ *  integrations appended rather than replacing ours. */
+function defineJaadSite(options: JaadUserConfig) {
+    const { site, base, astro } = options
+    const extra = astro ?? {}
+    const extraIntegrations = Array.isArray(extra.integrations) ? (extra.integrations as AstroIntegration[]) : []
+
+    return defineConfig({
+        ...(site ? { site } : {}),
+        ...(base ? { base } : {}),
+        ...extra,
+        integrations: [...jaad(options), ...extraIntegrations],
+    })
+}
+
 export default defineJaadSite(loaded.default)