@jaamd/jaad 0.0.0-stage → 0.11.0

package/src/content.ts

@@ -0,0 +1,42 @@
+import { glob } from 'astro/loaders'
+import { z } from 'astro/zod'
+import { defineCollection } from 'astro:content'
+import config from 'virtual:jaad/config'
+import { getDocCollectionId } from './utils/docs.ts'
+
+const docsPages = defineCollection({
+    loader: glob({
+        pattern: '**/*.md',
+        base: config.docsDir,
+        // Keep URLs file-driven even if markdown contains an unrelated slug field.
+        generateId: ({ entry }) => getDocCollectionId(entry),
+    }),
+    // Every field is optional: markdown without frontmatter works as-is.
+    schema: z.object({
+        title: z.string().optional(),
+        description: z.string().optional(),
+        /** Shorter label, in navigation only. */
+        label: z.string().optional(),
+        /** Pairs this page with its translations when the slugs differ. */
+        translationKey: z.string().optional(),
+        /** Replaces the filename prefix number. */
+        order: z.number().int().optional(),
+        /** Left out of production builds. */
+        draft: z.boolean().default(false),
+        /** Metadata and search weight; never rendered. */
+        keywords: z.array(z.string()).default([]),
+        author: z.string().optional(),
+        /** Public path or URL; false drops the site's. */
+        ogImage: z
+            .union([
+                z.string().refine((v) => v.startsWith('/') || /^https?:\/\//.test(v), {
+                    message: 'ogImage must be a public url, such as "/og/page.png"',
+                }),
+                z.literal(false),
+            ])
+            .optional(),
+        lastUpdated: z.coerce.date().optional(),
+    }),
+})
+
+export const collections = { docsPages }

package/src/docs-config.ts

@@ -0,0 +1,30 @@
+import type { Locale } from './locales.ts'
+import type { DocsUrlOptions } from './urls.ts'
+import config from 'virtual:jaad/config'
+import * as locales from './locales.ts'
+import { uiString, type UiKey } from './ui.ts'
+
+/** The virtual config, read once. */
+export const LOCALES: Locale[] = config.docsLocales
+export const DEFAULT_LOCALE: string = config.defaultLocale
+
+/** The four fields every href builder takes, in one place. */
+export function docsUrls(locale?: string): DocsUrlOptions {
+    return {
+        docsBase: config.docsBase,
+        deploymentBase: import.meta.env.BASE_URL,
+        locale,
+        defaultLocale: DEFAULT_LOCALE,
+    }
+}
+
+export const localePrefix = (locale?: string) => locales.localePrefix(locale, DEFAULT_LOCALE)
+
+export const buildLocales = () => locales.routedLocales(LOCALES)
+
+export const prefixedCodes = () => locales.prefixedLocales(LOCALES, DEFAULT_LOCALE)
+
+/** The interface strings for a page, already resolved. */
+export function ui(locale: string = DEFAULT_LOCALE) {
+    return (key: UiKey) => uiString(config.ui, locale, key)
+}

package/src/env.d.ts

@@ -0,0 +1,13 @@
+/// <reference types="astro/client" />
+
+declare module 'virtual:jaad/config' {
+    // oxlint-disable-next-line typescript/consistent-type-imports
+    const config: import('./config.ts').JaadResolvedConfig
+    export default config
+}
+
+declare module 'virtual:jaad/docs-frame' {
+    // oxlint-disable-next-line typescript/consistent-type-imports
+    const DocsFrame: typeof import('./layouts/DefaultDocsFrame.astro').default
+    export default DocsFrame
+}

package/src/fonts/OFL.txt

@@ -0,0 +1,94 @@
+Copyright 2020 The Inter Project Authors (https://github.com/rsms/inter)
+Copyright 2020 The Merriweather Project Authors (https://github.com/EbenSorkin/Merriweather4) with Reserved Font Name "Merriweather".
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/src/fonts.ts

@@ -0,0 +1,29 @@
+import { fontProviders } from 'astro/config'
+
+const file = (name: string) => new URL(`./fonts/${name}.woff2`, import.meta.url)
+
+export const fonts = [
+    {
+        provider: fontProviders.local(),
+        name: 'Inter',
+        cssVariable: '--font-inter',
+        options: {
+            variants: [{ weight: '400 600', style: 'normal', src: [file('inter')] }],
+        },
+    },
+    {
+        provider: fontProviders.local(),
+        name: 'Merriweather',
+        cssVariable: '--font-merriweather',
+        options: {
+            variants: [
+                { weight: '300 700', style: 'normal', src: [file('merriweather')] },
+                {
+                    weight: '300 700',
+                    style: 'italic',
+                    src: [file('merriweather-italic')],
+                },
+            ],
+        },
+    },
+]

package/src/forges.ts

@@ -0,0 +1,60 @@
+// Icon paths from simple-icons (CC0-1.0). Only git forges are bundled: they
+// are what the repository link inferred from the git remote needs.
+
+interface Forge {
+    label: string
+    /** Single 24×24 filled path. */
+    path: string
+    /** Host that identifies this forge in a git remote, when unambiguous. */
+    host: string | null
+}
+
+export const FORGES: Record<string, Forge> = {
+    github: {
+        label: 'GitHub',
+        host: 'github.com',
+        path: 'M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12',
+    },
+    gitlab: {
+        label: 'GitLab',
+        host: 'gitlab.com',
+        path: 'm23.6004 9.5927-.0337-.0862L20.3.9814a.851.851 0 0 0-.3362-.405.8748.8748 0 0 0-.9997.0539.8748.8748 0 0 0-.29.4399l-2.2055 6.748H7.5375l-2.2057-6.748a.8573.8573 0 0 0-.29-.4412.8748.8748 0 0 0-.9997-.0537.8585.8585 0 0 0-.3362.4049L.4332 9.5015l-.0325.0862a6.0657 6.0657 0 0 0 2.0119 7.0105l.0113.0087.03.0213 4.976 3.7264 2.462 1.8633 1.4995 1.1321a1.0085 1.0085 0 0 0 1.2197 0l1.4995-1.1321 2.4619-1.8633 5.006-3.7489.0125-.01a6.0682 6.0682 0 0 0 2.0094-7.003z',
+    },
+    codeberg: {
+        label: 'Codeberg',
+        host: 'codeberg.org',
+        path: 'M11.999.747A11.974 11.974 0 0 0 0 12.75c0 2.254.635 4.465 1.833 6.376L11.837 6.19c.072-.092.251-.092.323 0l4.178 5.402h-2.992l.065.239h3.113l.882 1.138h-3.674l.103.374h3.86l.777 1.003h-4.358l.135.483h4.593l.695.894h-5.038l.165.589h5.326l.609.785h-5.717l.182.65h6.038l.562.727h-6.397l.183.65h6.717A12.003 12.003 0 0 0 24 12.75 11.977 11.977 0 0 0 11.999.747zm3.654 19.104.182.65h5.326c.173-.204.353-.433.513-.65zm.385 1.377.18.65h3.563c.233-.198.485-.428.712-.65zm.383 1.377.182.648h1.203c.356-.204.685-.412 1.042-.648z',
+    },
+    gitea: {
+        label: 'Gitea',
+        host: 'gitea.com',
+        path: 'M4.209 4.603c-.247 0-.525.02-.84.088-.333.07-1.28.283-2.054 1.027C-.403 7.25.035 9.685.089 10.052c.065.446.263 1.687 1.21 2.768 1.749 2.141 5.513 2.092 5.513 2.092s.462 1.103 1.168 2.119c.955 1.263 1.936 2.248 2.89 2.367 2.406 0 7.212-.004 7.212-.004s.458.004 1.08-.394c.535-.324 1.013-.893 1.013-.893s.492-.527 1.18-1.73c.21-.37.385-.729.538-1.068 0 0 2.107-4.471 2.107-8.823-.042-1.318-.367-1.55-.443-1.627-.156-.156-.366-.153-.366-.153s-4.475.252-6.792.306c-.508.011-1.012.023-1.512.027v4.474l-.634-.301c0-1.39-.004-4.17-.004-4.17-1.107.016-3.405-.084-3.405-.084s-5.399-.27-5.987-.324c-.187-.011-.401-.032-.648-.032zm.354 1.832h.111s.271 2.269.6 3.597C5.549 11.147 6.22 13 6.22 13s-.996-.119-1.641-.348c-.99-.324-1.409-.714-1.409-.714s-.73-.511-1.096-1.52C1.444 8.73 2.021 7.7 2.021 7.7s.32-.859 1.47-1.145c.395-.106.863-.12 1.072-.12zm8.33 2.554c.26.003.509.127.509.127l.868.422-.529 1.075a.686.686 0 0 0-.614.359.685.685 0 0 0 .072.756l-.939 1.924a.69.69 0 0 0-.66.527.687.687 0 0 0 .347.763.686.686 0 0 0 .867-.206.688.688 0 0 0-.069-.882l.916-1.874a.667.667 0 0 0 .237-.02.657.657 0 0 0 .271-.137 8.826 8.826 0 0 1 1.016.512.761.761 0 0 1 .286.282c.073.21-.073.569-.073.569-.087.29-.702 1.55-.702 1.55a.692.692 0 0 0-.676.477.681.681 0 1 0 1.157-.252c.073-.141.141-.282.214-.431.19-.397.515-1.16.515-1.16.035-.066.218-.394.103-.814-.095-.435-.48-.638-.48-.638-.467-.301-1.116-.58-1.116-.58s0-.156-.042-.27a.688.688 0 0 0-.148-.241l.516-1.062 2.89 1.401s.48.218.583.619c.073.282-.019.534-.069.657-.24.587-2.1 4.317-2.1 4.317s-.232.554-.748.588a1.065 1.065 0 0 1-.393-.045l-.202-.08-4.31-2.1s-.417-.218-.49-.596c-.083-.31.104-.691.104-.691l2.073-4.272s.183-.37.466-.497a.855.855 0 0 1 .35-.077z',
+    },
+    forgejo: {
+        label: 'Forgejo',
+        host: null,
+        path: 'M16.7773 0c1.6018 0 2.9004 1.2986 2.9004 2.9005s-1.2986 2.9004-2.9004 2.9004c-1.0854 0-2.0315-.596-2.5288-1.4787H12.91c-2.3322 0-4.2272 1.8718-4.2649 4.195l-.0007 2.1175a7.0759 7.0759 0 0 1 4.148-1.4205l.1176-.001 1.3385.0002c.4973-.8827 1.4434-1.4788 2.5288-1.4788 1.6018 0 2.9004 1.2986 2.9004 2.9005s-1.2986 2.9004-2.9004 2.9004c-1.0854 0-2.0315-.596-2.5288-1.4787H12.91c-2.3322 0-4.2272 1.8718-4.2649 4.195l-.0007 2.319c.8827.4973 1.4788 1.4434 1.4788 2.5287 0 1.602-1.2986 2.9005-2.9005 2.9005-1.6018 0-2.9004-1.2986-2.9004-2.9005 0-1.0853.596-2.0314 1.4788-2.5287l-.0002-9.9831c0-3.887 3.1195-7.0453 6.9915-7.108l.1176-.001h1.3385C14.7458.5962 15.692 0 16.7773 0ZM7.2227 19.9052c-.6596 0-1.1943.5347-1.1943 1.1943s.5347 1.1943 1.1943 1.1943 1.1944-.5347 1.1944-1.1943-.5348-1.1943-1.1944-1.1943Zm9.5546-10.4644c-.6596 0-1.1944.5347-1.1944 1.1943s.5348 1.1943 1.1944 1.1943c.6596 0 1.1943-.5347 1.1943-1.1943s-.5347-1.1943-1.1943-1.1943Zm0-7.7346c-.6596 0-1.1944.5347-1.1944 1.1943s.5348 1.1943 1.1944 1.1943c.6596 0 1.1943-.5347 1.1943-1.1943s-.5347-1.1943-1.1943-1.1943Z',
+    },
+    bitbucket: {
+        label: 'Bitbucket',
+        host: 'bitbucket.org',
+        path: 'M.778 1.213a.768.768 0 00-.768.892l3.263 19.81c.084.5.515.868 1.022.873H19.95a.772.772 0 00.77-.646l3.27-20.03a.768.768 0 00-.768-.891zM14.52 15.53H9.522L8.17 8.466h7.561z',
+    },
+    sourcehut: {
+        label: 'SourceHut',
+        host: 'sr.ht',
+        path: 'M12 0C5.371 0 0 5.371 0 12s5.371 12 12 12 12-5.371 12-12S18.629 0 12 0Zm0 21.677A9.675 9.675 0 0 1 2.323 12 9.675 9.675 0 0 1 12 2.323 9.675 9.675 0 0 1 21.677 12 9.675 9.675 0 0 1 12 21.677Z',
+    },
+}
+
+/** Matches a repository URL to a bundled forge icon, if we recognise the host. */
+export function forgeForUrl(url: string): string | null {
+    const host = url.match(/^https?:\/\/([^/]+)/)?.[1]
+    if (!host) return null
+    for (const [name, forge] of Object.entries(FORGES)) {
+        if (forge.host && (host === forge.host || host.endsWith('.' + forge.host))) {
+            return name
+        }
+    }
+    return null
+}

package/src/infer.ts

@@ -0,0 +1,75 @@
+import { execFileSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const git = (args: string[], cwd: string): string | null => {
+    try {
+        return execFileSync('git', args, {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim()
+    } catch {
+        return null
+    }
+}
+
+/** `git@host:owner/repo.git` and `https://host/owner/repo.git` both become
+ *  `https://host/owner/repo`. */
+export function normaliseRemote(remote: string): string | null {
+    const ssh = remote.match(/^[\w.-]+@([\w.-]+):(.+?)(?:\.git)?$/)
+    if (ssh) return `https://${ssh[1]}/${ssh[2]}`
+
+    const https = remote.match(/^https?:\/\/(?:[^@/]+@)?([\w.-]+)\/(.+?)(?:\.git)?$/)
+    if (https) return `https://${https[1]}/${https[2]}`
+
+    return null
+}
+
+export interface RepoInfo {
+    /** Browsable base, e.g. https://github.com/owner/repo */
+    url: string
+    branch: string
+    /** Path from the repository root to the Astro project, "" at the root. */
+    prefix: string
+}
+
+/** Returns null outside a repository, in a tarball, or without an origin. */
+export function inferRepo(cwd: string = process.cwd()): RepoInfo | null {
+    const remote = git(['remote', 'get-url', 'origin'], cwd)
+    if (!remote) return null
+
+    const url = normaliseRemote(remote)
+    if (!url) return null
+
+    return {
+        url,
+        branch: git(['rev-parse', '--abbrev-ref', 'HEAD'], cwd) || 'main',
+        prefix: git(['rev-parse', '--show-prefix'], cwd) ?? '',
+    }
+}
+
+/** Ends in a slash. `docsDir` resolves against the repository root, not the
+ *  Astro project, so a site in a subdirectory still links correctly. */
+export function editBaseFrom(repo: RepoInfo, docsDir: string): string {
+    const dir = docsDir.replace(/^\.\//, '').replace(/\/$/, '')
+    const path = `${repo.prefix}${dir}`.replace(/^\/+/, '')
+    return `${repo.url}/edit/${repo.branch}/${path}/`
+}
+
+/** `:path` is substituted when present, otherwise the file is appended. */
+export function editUrl(base: string, filePath: string): string {
+    return base.includes(':path') ? base.replace(':path', filePath) : base.replace(/\/?$/, '/') + filePath
+}
+
+export function inferDescription(cwd: string = process.cwd()): string | null {
+    try {
+        const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8')) as {
+            description?: unknown
+        }
+
+        return typeof pkg.description === 'string' && pkg.description ? pkg.description : null
+    } catch {
+        return null
+    }
+}

package/src/integration.ts

@@ -0,0 +1,270 @@
+import type { JaadResolvedConfig, resolveStylesheets } from './config.ts'
+import type { AstroIntegration, AstroUserConfig } from 'astro'
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join, relative, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { fonts } from './fonts.ts'
+import { prefixedLocales } from './locales.ts'
+import { docsPageHref, normaliseBasePath, type DocsUrlOptions } from './urls.ts'
+import { getCleanSlug, getDocCollectionId, sortDocPages, splitDocLocale } from './utils/docs.ts'
+import { jaadVirtualPlugin } from './virtual.ts'
+
+type Stylesheets = ReturnType<typeof resolveStylesheets>
+type VitePlugins = NonNullable<NonNullable<AstroUserConfig['vite']>['plugins']>
+
+const NOT_INSTALLED = new Set(['MODULE_NOT_FOUND', 'ERR_PACKAGE_PATH_NOT_EXPORTED'])
+
+/** The site's own `@tailwindcss/vite`, unless it already registered one. */
+export function loadTailwindPlugin(root: string, registered: VitePlugins | undefined): VitePlugins {
+    const plugins = ([registered] as unknown[]).flat(Infinity) as ({
+        name?: string
+    } | null)[]
+    if (plugins.some((p) => p?.name?.startsWith('@tailwindcss/vite'))) return []
+
+    const load = createRequire(join(root, 'package.json'))
+    let tailwindcss: () => VitePlugins
+    try {
+        load.resolve('tailwindcss/package.json')
+        ;({ default: tailwindcss } = load('@tailwindcss/vite') as {
+            default: () => VitePlugins
+        })
+    } catch (error) {
+        if (!NOT_INSTALLED.has((error as { code?: string }).code ?? '')) throw error
+        throw new Error(
+            'jaad: `tailwind: true` needs Tailwind in your project:\n  npm i -D tailwindcss @tailwindcss/vite',
+            { cause: error },
+        )
+    }
+    return tailwindcss()
+}
+
+/** One per locale: each has its own first page, and its own redirect. */
+export interface OpeningPage {
+    locale?: string
+    slug: string
+}
+
+export interface IntegrationState {
+    deploymentBase: string
+    openingPages: OpeningPage[]
+    docsFrame: string
+}
+
+const INDEX_PAGE_NAMES = ['index.astro', 'index.md', 'index.mdx', 'index.html', 'index.js', 'index.ts']
+
+const NOT_FOUND_PAGE_NAMES = ['404.astro', '404.md', '404.mdx', '404.html', '404.js', '404.ts']
+
+const routeEntrypoint = (file: string) => fileURLToPath(new URL(`./routes/${file}`, import.meta.url))
+
+export function shouldInjectNotFound(docsBase: string, srcDir: URL): boolean {
+    return docsBase === '' && !NOT_FOUND_PAGE_NAMES.some((name) => existsSync(new URL(`pages/${name}`, srcDir)))
+}
+
+/** The two fields that move the opening page. The content collection is not
+ *  available this early, so `order` and `draft` are read from the file. */
+function readFrontmatter(source: string): { order?: number; draft?: boolean } {
+    const block = /^---\r?\n([\s\S]*?)\r?\n---/.exec(source)
+    if (!block) return {}
+
+    const order = /^order:\s*(-?\d+)\s*$/m.exec(block[1])
+    const draft = /^draft:\s*(true|false)\s*$/m.exec(block[1])
+    return {
+        order: order ? Number(order[1]) : undefined,
+        draft: draft ? draft[1] === 'true' : undefined,
+    }
+}
+
+export function findOpeningPages(dir: string, locales: string[] = []): OpeningPage[] {
+    if (!existsSync(dir)) return []
+
+    const pages: {
+        id: string
+        localeId: string
+        locale: string | null
+        data: { order?: number }
+    }[] = []
+
+    const visit = (current: string) => {
+        for (const entry of readdirSync(current, { withFileTypes: true }).toSorted((a, b) =>
+            a.name.localeCompare(b.name),
+        )) {
+            const file = join(current, entry.name)
+            if (entry.isDirectory()) visit(file)
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                const front = readFrontmatter(readFileSync(file, 'utf8'))
+                if (front.draft) continue
+
+                const id = getDocCollectionId(relative(dir, file))
+                const split = splitDocLocale(id, locales)
+                pages.push({
+                    id,
+                    localeId: split.id,
+                    locale: split.locale,
+                    data: { order: front.order },
+                })
+            }
+        }
+    }
+
+    visit(dir)
+
+    const groups = locales.length > 0 ? locales : [null]
+    return groups.flatMap((locale) => {
+        const first = sortDocPages(pages.filter((page) => page.locale === locale))[0]
+        // Indexed access is typed as always present; a locale can have no pages.
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (!first) return []
+        return [{ locale: locale ?? undefined, slug: getCleanSlug(first.localeId) }]
+    })
+}
+
+export function getInjectedRoutes(docsBase: string, locales: string[] = []): [string, string][] {
+    // `[...slug]` already absorbs "it/guide" and "it". Only the two fixed
+    // endpoints need a route of their own, and `[locale]` hands them the code.
+    const perLocale: [string, string][] =
+        locales.length > 0
+            ? [
+                  [`${docsBase}/[locale]/search-index.json`, 'search-index-locale.json.ts'],
+                  [`${docsBase}/[locale]/llms.txt`, 'llms-locale.txt.ts'],
+              ]
+            : []
+
+    return [
+        [docsBase, 'docs-index.astro'],
+        [`${docsBase}/search-index.json`, 'search-index.json.ts'],
+        [`${docsBase}/llms.txt`, 'llms.txt.ts'],
+        ...perLocale,
+        [`${docsBase}/[...slug]`, 'docs-slug.astro'],
+        [`${docsBase}/[...slug].md`, 'docs-slug.md.ts'],
+    ]
+}
+
+export function createIntegrationState(): IntegrationState {
+    return {
+        deploymentBase: '',
+        openingPages: [],
+        docsFrame: fileURLToPath(new URL('./layouts/DefaultDocsFrame.astro', import.meta.url)),
+    }
+}
+
+export function createCoreIntegration(
+    config: JaadResolvedConfig,
+    stylesheets: Stylesheets,
+    state: IntegrationState,
+    discoverOpeningPage: boolean,
+): AstroIntegration {
+    return {
+        name: 'jaad',
+        hooks: {
+            'astro:config:setup': ({ config: astroConfig, updateConfig, injectRoute, addWatchFile, logger }) => {
+                updateConfig({
+                    vite: {
+                        plugins: [
+                            jaadVirtualPlugin(
+                                config,
+                                stylesheets.user,
+                                stylesheets.theme,
+                                stylesheets.bridge,
+                                stylesheets.tailwind,
+                                () => state.docsFrame,
+                            ),
+                            ...(config.tailwind
+                                ? [loadTailwindPlugin(fileURLToPath(astroConfig.root), astroConfig.vite.plugins)]
+                                : []),
+                        ],
+                        // Package .astro sources must reach the Astro compiler.
+                        ssr: { noExternal: ['@jaamd/jaad'] },
+                    },
+                    fonts,
+                })
+
+                for (const [pattern, entrypoint] of getInjectedRoutes(
+                    config.docsBase,
+                    prefixedLocales(config.docsLocales, config.defaultLocale),
+                )) {
+                    injectRoute({
+                        pattern,
+                        entrypoint: routeEntrypoint(entrypoint),
+                        prerender: true,
+                    })
+                }
+
+                const customDocsFrame = new URL('jaad/DocsFrame.astro', astroConfig.srcDir)
+                if (existsSync(customDocsFrame)) {
+                    state.docsFrame = fileURLToPath(customDocsFrame)
+                    addWatchFile(customDocsFrame)
+                }
+
+                if (shouldInjectNotFound(config.docsBase, astroConfig.srcDir)) {
+                    injectRoute({
+                        pattern: '/404',
+                        entrypoint: routeEntrypoint('404.astro'),
+                        prerender: true,
+                    })
+                }
+
+                const docsDirPath = resolve(fileURLToPath(astroConfig.root), config.docsDir)
+                const docsDir = pathToFileURL(docsDirPath)
+                if (!existsSync(docsDir)) {
+                    logger.warn(
+                        `${config.docsDir} does not exist, so the site has no pages. ` +
+                            'Create it, or point docsDir at your markdown.',
+                    )
+                } else if (discoverOpeningPage) {
+                    state.openingPages = findOpeningPages(
+                        docsDirPath,
+                        config.docsLocales.map((locale) => locale.code),
+                    )
+                }
+                addWatchFile(docsDir)
+
+                if (config.docsBase === '') {
+                    const ownIndex = INDEX_PAGE_NAMES.find((name) =>
+                        existsSync(new URL(`pages/${name}`, astroConfig.srcDir)),
+                    )
+                    if (ownIndex) {
+                        logger.warn(
+                            `${ownIndex} owns the site root while JAAD docs are mounted there. ` +
+                                'Set routeBase: "/docs" to keep a landing page and mount the docs below it.',
+                        )
+                    }
+                }
+            },
+
+            'astro:config:done': ({ config: astroConfig, injectTypes }) => {
+                state.deploymentBase = normaliseBasePath(astroConfig.base)
+                injectTypes({
+                    filename: 'jaad.d.ts',
+                    content: `declare module "virtual:jaad/config" {
+  const config: import("@jaamd/jaad").JaadResolvedConfig;
+  export default config;
+}`,
+                })
+            },
+        },
+    }
+}
+
+const withoutTrailingSlash = (value: string) => (value.length > 1 ? value.replace(/\/$/, '') : value)
+
+export function createSitemapFilter(
+    docsBase: string,
+    state: Pick<IntegrationState, 'deploymentBase' | 'openingPages'>,
+    defaultLocale?: string,
+): (page: string) => boolean {
+    return (page) => {
+        if (state.openingPages.length === 0) return true
+
+        const pathname = withoutTrailingSlash(new URL(page).pathname)
+        return !state.openingPages.some((opening) => {
+            const urls: DocsUrlOptions = {
+                docsBase,
+                deploymentBase: state.deploymentBase,
+                locale: opening.locale,
+                defaultLocale,
+            }
+            return pathname === withoutTrailingSlash(docsPageHref(opening.slug, urls))
+        })
+    }
+}

package/src/layouts/DefaultDocsFrame.astro

@@ -0,0 +1,31 @@
+---
+import type { DocsFrameProps } from '../advanced.ts'
+
+type Props = DocsFrameProps
+---
+
+<div data-jaad-default-frame class="docs-frame">
+    <slot name="header" />
+
+    <div class="docs-container">
+        <slot name="sidebar" />
+
+        <div class="docs-main docs-main-gutters">
+            <main class="docs-page-main">
+                <slot name="mobile-navigation" />
+
+                <article>
+                    <slot name="breadcrumbs" />
+                    <slot name="page-actions" />
+                    <slot name="content" />
+                </article>
+
+                <slot name="page-navigation" />
+            </main>
+        </div>
+
+        <slot name="table-of-contents" />
+    </div>
+
+    <slot name="footer" />
+</div>