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

package/docs/00-overview.md

@@ -0,0 +1,25 @@
+---
+description: JAAD turns a folder of Markdown files into a documentation site.
+---
+
+# Overview
+
+**Just Another Astro Docs**: JAAD is an Astro integration that turns a folder
+of Markdown files into a documentation site. The folder is the configuration:
+there is no sidebar to declare and no route to write.
+
+- **Navigation** from the file tree: sidebar, chapters, previous
+  and next links. See [Pages and structure](01-getting-started/02-pages.md).
+- **Search** across every page, built at compile time, with no external
+  service. See [Search](02-configurations/04-search.md).
+- **Languages**, one site per locale directory, with a switcher and `hreflang`.
+  See [Languages](02-configurations/03-i18n.md).
+- **Themes** for the interface and the code, light and dark. See
+  [Themes](02-configurations/05-themes.md).
+- **Metadata** for search engines and social cards, a sitemap, raw Markdown
+  routes and an `llms.txt` for language models.
+
+Pages are rendered with [JAAMD](../../astro/docs/00-overview.md), so its
+Markdown syntax and enhancements come with them.
+
+Start with [Installation](01-getting-started/01-installation.md).

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

@@ -0,0 +1,216 @@
+---
+description: Create a JAAD project, or add JAAD to an existing repository or Astro project.
+---
+
+# Installation
+
+`create-jaad` sets up a project in one command. To add JAAD by hand, see
+[Manual installation](#manual-installation).
+
+## Create a project
+
+:::code-tabs
+
+```bash npm
+npm create @jaamd/jaad@latest
+```
+
+```bash pnpm
+pnpm create @jaamd/jaad@latest
+```
+
+```bash yarn
+yarn create @jaamd/jaad@latest
+```
+
+```bash bun
+bun create @jaamd/jaad@latest
+```
+
+:::
+
+The CLI asks for a destination, template, title and whether to install
+dependencies. The `docs` template puts documentation at `/` and is the default;
+`site` adds a landing page at `/` and moves documentation to `/docs`.
+
+To provide every answer as flags:
+
+:::code-tabs
+
+```bash npm
+npm create @jaamd/jaad@latest my-docs -- --title "My Docs" --install
+```
+
+```bash pnpm
+pnpm create @jaamd/jaad@latest my-docs --title "My Docs" --install
+```
+
+```bash yarn
+yarn create @jaamd/jaad@latest my-docs --title "My Docs" --install
+```
+
+```bash bun
+bun create @jaamd/jaad@latest my-docs --title "My Docs" --install
+```
+
+:::
+
+Use `--here` inside an existing repository:
+
+:::code-tabs
+
+```bash npm
+npm create @jaamd/jaad@latest -- --here
+```
+
+```bash pnpm
+pnpm create @jaamd/jaad@latest --here
+```
+
+```bash yarn
+yarn create @jaamd/jaad@latest --here
+```
+
+```bash bun
+bun create @jaamd/jaad@latest --here
+```
+
+:::
+
+The command keeps the existing `package.json` and Markdown files. It stops
+without writing when a custom Astro or Content configuration requires a manual
+merge, and when `--template site` meets a `jaad.config.*` it did not write:
+the landing page needs `routeBase: "/docs"`, which only you can set.
+
+> [!NOTE]
+> Non-interactive environments require a destination or `--here`, `--title`,
+> and either `--install` or `--no-install`.
+
+## Run locally
+
+:::code-tabs
+
+```bash npm
+npm run dev
+```
+
+```bash pnpm
+pnpm dev
+```
+
+```bash yarn
+yarn dev
+```
+
+```bash bun
+bun run dev
+```
+
+:::
+
+The development server starts at `http://localhost:4321`.
+
+Add pages to `docs/`, following the conventions in
+[Pages and structure](02-pages.md).
+
+## Manual installation
+
+Install JAAD in a project on Astro 7.3 or a later 7.x, with Node.js 22.12 or later:
+
+:::code-tabs
+
+```bash npm
+npm install @jaamd/jaad
+```
+
+```bash pnpm
+pnpm add @jaamd/jaad
+```
+
+```bash yarn
+yarn add @jaamd/jaad
+```
+
+```bash bun
+bun add @jaamd/jaad
+```
+
+:::
+
+Add the following files:
+
+```ts
+// jaad.config.ts
+import { defineJaadConfig } from '@jaamd/jaad'
+
+export default defineJaadConfig({
+    site: 'https://example.dev',
+    title: 'My Project',
+})
+```
+
+```js
+// astro.config.mjs
+export { default } from '@jaamd/jaad/site'
+```
+
+```ts
+// src/content.config.ts
+export { collections } from '@jaamd/jaad/content'
+```
+
+```json
+// tsconfig.json
+{
+    "extends": "astro/tsconfigs/strict"
+}
+```
+
+Only `title` is required. See the
+[configuration reference](../02-configurations/01-reference.md) for the remaining
+options.
+
+## Existing Astro project
+
+If `--here` reports custom `astro.config.*` or `src/content.config.*` files,
+keep their existing configuration and merge JAAD manually.
+
+Add the integration to the Astro configuration:
+
+```ts
+import jaad from '@jaamd/jaad'
+// astro.config.ts
+import { defineConfig } from 'astro/config'
+import jaadConfig from './jaad.config'
+
+export default defineConfig({
+    site: jaadConfig.site,
+    base: jaadConfig.base,
+    integrations: [jaad(jaadConfig)],
+})
+```
+
+`jaad()` returns integrations only. `site` and `base` are lifted above, and the
+[`astro`](../02-configurations/01-reference.md#extending-astro) field is ignored here.
+Write those options in `defineConfig`.
+
+If the project defines content collections, add JAAD's collection without
+replacing them:
+
+```ts
+import { collections as jaadCollections } from '@jaamd/jaad/content'
+// src/content.config.ts
+import { defineCollection } from 'astro:content'
+
+const blog = defineCollection({/* existing loader and schema */})
+
+export const collections = {
+    blog,
+    ...jaadCollections,
+}
+```
+
+The collection name `docsPages` is reserved for JAAD.
+
+Create `docs/`, add a Markdown page, then run the project with its existing
+development script.

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

@@ -0,0 +1,109 @@
+---
+description: How the files in docs/ become pages, chapters, sections and URLs.
+---
+
+# Pages and structure
+
+Every Markdown file in `docs/` is a page. Its place in the folder sets its URL
+and its place in the navigation; nothing else needs configuring.
+
+```
+docs/
+  01-introduction.md     → /
+  02-guides/             → sidebar chapter "Guides"
+    01-setup.md          → /guides/setup
+    02-deployment.md     → /guides/deployment
+  03-reference.md        → /reference
+```
+
+The same tree builds the sidebar, the mobile menu, the line above each title and the
+previous and next links.
+
+## Rules
+
+- A numeric prefix sets the order and is removed from the URL. Files without
+  one sort after the numbered files.
+- A folder becomes a chapter. Only one folder level is supported.
+- The first `# Heading` is the page title.
+- The `##` and `###` headings make the page's table of contents. Wrap headings
+  in `<div data-toc-ignore>` to leave them out.
+- Removing the prefixes must leave every page and chapter with a unique path.
+
+Invalid nesting and duplicate paths stop the build and name the conflicting
+files.
+
+## The opening page
+
+The file that sorts first opens the documentation at `routeBase`, which is `/`
+by default. Its browser title is the site name alone, and its own slug
+redirects to it: with `routeBase: "/docs"`, `01-introduction.md` opens at
+`/docs`, and `/docs/introduction` redirects there.
+
+## Linking between pages
+
+Link to another page by its file, relative to the one you are writing:
+
+```markdown
+See [Deployment](./02-guides/02-deployment.md#hosting).
+```
+
+JAAD turns the link into the page's URL, so it also works on GitHub and in an
+editor. A link to a file that does not exist stops the build.
+
+## Sections
+
+A larger site can split its documentation into sections, each with its own
+directory, chapters and sidebar group:
+
+```ts
+defineJaadConfig({
+    title: 'My Project',
+    sections: {
+        guide: { dir: './docs/guide', label: 'Guide' },
+        api: { dir: '../packages/api/docs' },
+    },
+})
+```
+
+- The key is the URL segment: `api/01-client.md` is served at `/api/client`.
+- `label` names the section, in the sidebar and in the browser title of its
+  pages; it defaults to the key.
+- A directory can sit outside the project, such as the `docs/` of a package. No
+  section's directory can be inside another's.
+- Sections appear in the order they are declared. `docsDir` is read alongside
+  them only when you set it: its pages sit outside every section, come first,
+  and the first of them opens the docs. Its directory cannot hold a section's.
+- Previous and next links run on from one section into the next.
+- The first page of the first section opens at `routeBase`; the first page of
+  every other section opens at the section's own URL.
+- The rules above apply inside each section.
+
+This documentation is built that way: one section for JAAMD and one for JAAD,
+each read from its package.
+
+## Overriding the file tree
+
+[Frontmatter](../02-configurations/02-frontmatter.md) renames a page, moves it
+without renaming the file, or keeps it out of the build:
+
+```markdown
+---
+title: Images & Videos
+label: Media
+order: 5
+draft: true
+---
+```
+
+## More than one language
+
+Directories named after language codes turn the tree into one site per
+language, and the rules above then apply inside each of them. With sections,
+every section holds the same language directories. See
+[Languages](../02-configurations/03-i18n.md).
+
+## Markdown
+
+Pages are rendered with [JAAMD](../../../astro/docs/00-overview.md): alerts,
+code tabs, tables of contents and spoilers are written as described in
+[Markdown syntax](../../../astro/docs/02-markdown.md).

package/docs/01-getting-started/03-deployment.md

@@ -0,0 +1,100 @@
+---
+description: Build JAAD as a static site and publish it on GitHub Pages or any static host.
+---
+
+# Deployment
+
+JAAD builds a static site in `dist/`:
+
+:::code-tabs
+
+```bash npm
+npm run build
+npm run preview
+```
+
+```bash pnpm
+pnpm build
+pnpm preview
+```
+
+```bash yarn
+yarn build
+yarn preview
+```
+
+```bash bun
+bun run build
+bun run preview
+```
+
+:::
+
+Set `site` to the public URL so JAAD can generate canonical links, the sitemap
+and social image URLs. Add `base` when the site is served from a subpath.
+
+```ts
+export default defineJaadConfig({
+    site: 'https://me.github.io',
+    base: '/my-repo',
+    title: 'My Project',
+})
+```
+
+## GitHub Pages
+
+Select **GitHub Actions** as the Pages source, then add:
+
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy
+
+on:
+    push:
+        branches: [main]
+    workflow_dispatch:
+
+permissions:
+    contents: read
+    pages: write
+    id-token: write
+
+concurrency:
+    group: pages
+    cancel-in-progress: false
+
+jobs:
+    build:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v7
+            - uses: withastro/action@v6
+              # with:
+              #   path: .                     # the Astro project, if not the root
+              #   node-version: 24
+              #   package-manager: npm@latest
+
+    deploy:
+        needs: build
+        runs-on: ubuntu-latest
+        environment:
+            name: github-pages
+            url: ${{ steps.deployment.outputs.page_url }}
+        steps:
+            - id: deployment
+              uses: actions/deploy-pages@v5
+```
+
+## Other hosts
+
+For [Netlify](https://docs.astro.build/en/guides/integrations-guide/netlify/), [Vercel](https://docs.astro.build/en/guides/integrations-guide/vercel/), [Cloudflare Pages](https://docs.astro.build/en/guides/integrations-guide/cloudflare/) or another static host, use
+`npm run build` as the build command and `dist` as the publish directory.
+
+## Generated files
+
+In addition to the pages, the build writes:
+
+- `sitemap-index.xml` when `site` is set;
+- `<routeBase>/search-index.json` for search;
+- `<routeBase>/llms.txt` as a plain-text page index;
+- `<routeBase>/**.md` for raw Markdown routes.

package/docs/02-configurations/01-reference.md

@@ -0,0 +1,215 @@
+---
+description: Every option of jaad.config.ts, and the values JAAD detects from the project.
+---
+
+# Configuration
+
+All JAAD options live in `jaad.config.ts`. Only `title` is required.
+
+```ts
+import { defineJaadConfig } from '@jaamd/jaad'
+
+export default defineJaadConfig({
+    site: 'https://example.dev',
+    title: 'My Project',
+})
+```
+
+These options apply only to documentation pages. Pages in `src/pages/` keep
+their own layout, styles and metadata.
+
+## Site
+
+| Option | Type     | Default | Description                                         |
+| ------ | -------- | ------- | --------------------------------------------------- |
+| `site` | `string` | none    | Public URL used for canonical links and the sitemap |
+| `base` | `string` | none    | Subpath when the site is not served from `/`        |
+
+## Identity
+
+| Option        | Type     | Default        | Description                                       |
+| ------------- | -------- | -------------- | ------------------------------------------------- |
+| `title`       | `string` | none           | **Required.** Site name and metadata              |
+| `description` | `string` | `package.json` | Site description                                  |
+| `lang`        | `string` | `"en"`         | Site language, and the default when localised     |
+| `logo`        | `string` | none           | Public path or URL shown instead of the site name |
+| `homeLink`    | `string` | `"/"`          | Where the site name in the header leads           |
+
+A source file path passed to `logo` produces a build error. Use a public path
+such as `/logo.svg`.
+
+When the documentation is part of a larger site, point `homeLink` at that
+site's home: `homeLink: "https://example.dev"`. A path such as `/` gets
+Astro's `base`.
+
+## Content
+
+| Option      | Type                | Default    | Description                               |
+| ----------- | ------------------- | ---------- | ----------------------------------------- |
+| `docsDir`   | `string`            | `"./docs"` | Directory containing Markdown files       |
+| `routeBase` | `string`            | `"/"`      | Route where documentation is mounted      |
+| `sections`  | `object`            | none       | One directory per section, by URL segment |
+| `locales`   | `string[] \| false` | detected   | Override the detected locale directories  |
+| `ui`        | `object`            | `{}`       | Interface string overrides, per locale    |
+
+Locale directories under `docsDir` are detected on their own; `locales` only
+overrides that. See [Languages](03-i18n.md).
+
+With `sections`, `docsDir` is read only when set, for pages outside every
+section. See [Sections](../01-getting-started/02-pages.md#sections).
+
+To keep a landing page at `/`, mount documentation below it:
+
+```ts
+defineJaadConfig({ title: 'My Project', routeBase: '/docs' })
+```
+
+When documentation is mounted at `/`, an existing `src/pages/index.*` creates
+a route conflict and JAAD reports the required `routeBase` setting.
+
+## Navigation
+
+| Option   | Type                                | Default  | Description       |
+| -------- | ----------------------------------- | -------- | ----------------- |
+| `nav`    | `{ label: string; href: string }[]` | `[]`     | Header text links |
+| `social` | `Record<string, string \| object>`  | inferred | Header icon links |
+
+For example:
+
+```ts
+defineJaadConfig({
+    title: 'My Project',
+    nav: [{ label: 'API', href: 'https://api.example.dev' }],
+    social: {
+        github: 'https://github.com/me/repo',
+        forum: {
+            href: 'https://forum.example.dev',
+            label: 'Forum',
+            svg: `<svg viewBox="0 0 24 24">...</svg>`,
+        },
+    },
+})
+```
+
+Bundled forge icons are available for `github`, `gitlab`, `codeberg`, `gitea`,
+`forgejo`, `bitbucket` and `sourcehut`. Other keys require an `svg`.
+
+Object entries accept `href`, with optional `label` and `svg` fields.
+
+When `social` is omitted, JAAD derives the repository link and forge icon from
+the git remote. An explicit forge entry overrides that inference.
+
+## Footer
+
+| Option   | Type              | Default   | Description                          |
+| -------- | ----------------- | --------- | ------------------------------------ |
+| `footer` | `string \| false` | `:credit` | Footer HTML, or `false` to remove it |
+
+Use `:credit` to place the JAAD credit inside custom text:
+
+```ts
+defineJaadConfig({ title: '...', footer: '© 2026 Me · :credit' })
+```
+
+## Repository
+
+| Option     | Type                | Default | Description                                     |
+| ---------- | ------------------- | ------- | ----------------------------------------------- |
+| `editLink` | `boolean \| string` | `true`  | Derive, override or hide “Edit this page” links |
+
+Pass a URL to override the inferred repository. `:path` is replaced with the
+source file path, or appended when absent:
+
+```ts
+defineJaadConfig({
+    title: '...',
+    editLink: 'https://git.example.dev/me/repo/edit/main/docs/:path',
+})
+```
+
+The link is omitted when the git remote, branch or repository root cannot be
+resolved safely.
+
+With [sections](../01-getting-started/02-pages.md#sections), each one links
+to its own directory. A URL passed here applies to all of them, and `:path` is
+the file's path inside its section's directory.
+
+## SEO and head tags
+
+| Option    | Type              | Default          | Description                       |
+| --------- | ----------------- | ---------------- | --------------------------------- |
+| `head`    | `object[]`        | `[]`             | Extra elements in `<head>`        |
+| `ogImage` | `string \| false` | detected or none | Social image path, URL or `false` |
+
+JAAD detects `public/og-image.png`, `.jpg`, `.jpeg` or `.webp`, in that order.
+Local images and canonical URLs require `site`; absolute image URLs do not.
+
+Each `head` entry accepts `tag`, optional `attrs`, and optional `content`. Use
+it for analytics, verification tags and preconnects:
+
+```ts
+defineJaadConfig({
+    title: '...',
+    head: [
+        { tag: 'meta', attrs: { name: 'robots', content: 'index,follow' } },
+        { tag: 'script', attrs: { src: '/analytics.js', defer: true } },
+    ],
+})
+```
+
+## Theme and appearance
+
+| Option       | Type                                        | Default     |
+| ------------ | ------------------------------------------- | ----------- |
+| `theme`      | `string \| { light: string; dark: string }` | `"default"` |
+| `appearance` | `"auto" \| "light" \| "dark"`               | `"auto"`    |
+| `tailwind`   | `boolean`                                   | `false`     |
+
+A named theme styles the interface, Markdown and code blocks. A `{ light,
+dark }` object changes only the Shiki code themes. See
+[Themes](05-themes.md) for available names and custom themes.
+
+`tailwind: true` enables Tailwind utilities with JAAD's tokens on documentation
+pages, `Page` pages and a custom `DocsFrame`; see
+[Styles](06-styles.md#tailwind).
+
+`appearance: "auto"` follows the reader's preference and shows the switcher.
+`"light"` and `"dark"` pin the appearance and remove it.
+
+## Detected project values
+
+| Value                                     | Source                                            |
+| ----------------------------------------- | ------------------------------------------------- |
+| Repository and edit links                 | git remote, branch and `docsDir`                  |
+| Missing description                       | `package.json`                                    |
+| Favicon                                   | `public/favicon.svg`, `.ico` or `.png`            |
+| Social image                              | `public/og-image.png`, `.jpg`, `.jpeg` or `.webp` |
+| Custom styles                             | `src/jaad.css`                                    |
+| Locales                                   | Directory names under `docsDir`                   |
+| Sitemap                                   | Generated when `site` is set                      |
+| Search index, `llms.txt` and raw Markdown | Generated below `routeBase`                       |
+
+## Extending Astro
+
+| Option  | Type              | Default |
+| ------- | ----------------- | ------- |
+| `astro` | `AstroUserConfig` | `{}`    |
+
+Pass additional Astro options through `astro`. Extra integrations are appended
+to JAAD's integrations:
+
+```ts
+defineJaadConfig({
+    title: 'My Project',
+    astro: {
+        build: { format: 'file' },
+        integrations: [mdx()],
+    },
+})
+```
+
+`astro` is read by `@jaamd/jaad/site`. `jaad(config)` ignores it.
+
+For full control, use a regular Astro configuration and add `jaad(config)` to
+its integrations, as shown in
+[Existing Astro project](../01-getting-started/01-installation.md#existing-astro-project).