@zebradil/docs-kit 0.0.0-stage → 0.11.0

package/packages/docs-kit/Landing.astro

@@ -0,0 +1,372 @@
+---
+import { readFileSync } from 'node:fs';
+import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
+import { Code, LinkCard, TabItem, Tabs } from '@astrojs/starlight/components';
+import site from 'virtual:docs-kit/site';
+import { escape, inline } from './text.mjs';
+import Cascade from './Cascade.astro';
+import Diff from './Diff.astro';
+import Tree from './Tree.astro';
+
+// The hero's text column is Starlight's: the eyebrow rides in the tagline slot and CSS moves it above the title.
+const lede = `<span class="kit-lede">${inline(site.description ?? site.tagline)}</span>`;
+const eyebrow = site.eyebrow ? `<span class="kit-eyebrow">${escape(site.eyebrow)}</span>` : '';
+
+// Illustrations are project content, inlined so they can follow the color scheme and animate.
+// Paths are relative to the docs directory, the working directory of a build.
+const svg = (path: string) => readFileSync(path, 'utf8');
+const art = site.art && `<div class="kit-art" aria-hidden="true">${svg(site.art)}</div>`;
+
+// The flow panel fills Starlight's hero image slot, which only takes an HTML string, unless `art` takes it;
+// then the panel opens a section below the hero. With `flow.art` the rows stay for screen readers only.
+const arrows = { forward: '→', back: '←', both: '↔' };
+const node = (name: string) =>
+  `<span class="kit-flow-node${name === site.flow?.highlight ? ' kit-flow-node-hl' : ''}">${escape(name)}</span>`;
+const flow =
+  site.flow &&
+  [
+    `<div class="kit-flow">`,
+    art ? '' : `<p class="kit-flow-title">${escape(site.flow.title ?? 'How it fits')}</p>`,
+    site.flow.art ? `<div class="kit-flow-art" aria-hidden="true">${svg(site.flow.art)}</div><div class="sr-only">` : '',
+    ...site.flow.steps.map(
+      (s) =>
+        `<div class="kit-flow-row">${node(s.from)}` +
+        `<span class="kit-flow-edge" data-arrow="${s.arrow ?? 'forward'}"><span class="kit-flow-label">${escape(s.label)}</span>` +
+        `<span class="sr-only">${arrows[s.arrow ?? 'forward']}</span></span>${node(s.to)}</div>`,
+    ),
+    site.flow.art ? '</div>' : '',
+    site.flow.note && !art ? `<p class="kit-flow-note">${inline(site.flow.note)}</p>` : '',
+    '</div>',
+  ].join('');
+
+const frontmatter = {
+  title: site.name,
+  description: site.tagline,
+  template: 'splash' as const,
+  hero: {
+    title: escape(site.headline ?? site.name),
+    tagline: eyebrow + lede,
+    ...((art || flow) && { image: { html: art || flow } }),
+    actions: [
+      { text: 'Get started', link: `${import.meta.env.BASE_URL.replace(/\/$/, '')}/getting-started/`, icon: 'right-arrow' },
+      { text: 'GitHub', link: site.repo, icon: 'github', variant: 'minimal' },
+    ],
+  },
+};
+const number = (i: number) => String(i + 1).padStart(2, '0');
+---
+
+<StarlightPage frontmatter={frontmatter}>
+  <div class="kit-landing not-content">
+    <section class="kit-install" aria-label="Install">
+      <Tabs>
+        {site.install.map((m) => <TabItem label={m.label}><Code code={m.code} lang="sh" /></TabItem>)}
+      </Tabs>
+    </section>
+
+    {site.diff && <Diff />}
+
+    {
+      art && flow && (
+        <section class="kit-flow-section">
+          <div>
+            <h2>{site.flow.title ?? 'How it fits'}</h2>
+            {site.flow.note && <p set:html={inline(site.flow.note)} />}
+          </div>
+          <Fragment set:html={flow} />
+        </section>
+      )
+    }
+
+    {site.tree && <Tree />}
+
+    {site.cascade && <Cascade />}
+
+    <section>
+      <h2>Features</h2>
+      <div class="kit-features">
+        {
+          site.features.map((f, i) => (
+            <article class="kit-feature">
+              <span class="kit-number">{number(i)}</span>
+              <h3 set:html={escape(f.title)} />
+              <p set:html={inline(f.body)} />
+            </article>
+          ))
+        }
+      </div>
+    </section>
+
+    {
+      site.components && (
+        <section class="kit-components">
+          <div>
+            <h2>{site.components.title ?? 'Components'}</h2>
+            {site.components.intro && <p set:html={inline(site.components.intro)} />}
+          </div>
+          <dl>
+            {site.components.items.map((c) => (
+              <div>
+                <dt>
+                  <code>{c.name}</code>
+                </dt>
+                <dd set:html={inline(c.body)} />
+              </div>
+            ))}
+          </dl>
+        </section>
+      )
+    }
+
+    {
+      !!site.links?.length && (
+        <section>
+          <h2>Links</h2>
+          <div class="kit-links">
+            {site.links.map((l) => <LinkCard title={l.label} href={l.href} />)}
+          </div>
+        </section>
+      )
+    }
+  </div>
+</StarlightPage>
+
+<style is:global>
+  /* Hero: Starlight's markup in the kit's layout, scoped to the landing page with :has(). */
+  :root:has(.kit-landing) {
+    --kit-display: var(--kit-font-display, var(--sl-font));
+  }
+  :root:has(.kit-landing) .hero .tagline {
+    display: contents;
+  }
+  :root:has(.kit-landing) .hero h1 {
+    font-family: var(--kit-display);
+    letter-spacing: -0.03em;
+    line-height: 1.05;
+  }
+  .kit-eyebrow {
+    order: -1;
+    font-family: var(--sl-font-mono);
+    font-size: var(--sl-text-xs);
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+    color: var(--sl-color-text-accent);
+  }
+  .kit-lede {
+    font-size: clamp(var(--sl-text-base), calc(0.0625rem + 2vw), var(--sl-text-xl));
+    line-height: 1.55;
+    color: var(--sl-color-gray-2);
+  }
+  :root:has(.kit-landing) .hero > .hero-html {
+    order: 2;
+    width: 100%;
+  }
+  @media (min-width: 50rem) {
+    :root:has(.kit-landing) .hero:has(> .hero-html) {
+      grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+      gap: 4rem;
+    }
+  }
+
+  /* Illustrations: project SVGs scaled to their column. */
+  .kit-art {
+    display: grid;
+    place-items: center;
+    width: 100%;
+  }
+  .kit-art svg {
+    width: min(100%, 26rem);
+    height: auto;
+  }
+  .kit-flow-art svg {
+    display: block;
+    width: 100%;
+    height: auto;
+  }
+  .kit-flow-section {
+    display: grid;
+    grid-template-columns: minmax(0, 2fr) minmax(0, 3fr);
+    gap: 2rem 3rem;
+    align-items: center;
+  }
+  .kit-flow-section > div > p {
+    margin: 0;
+    line-height: 1.55;
+    color: var(--sl-color-gray-2);
+  }
+  @media (max-width: 50rem) {
+    .kit-flow-section {
+      grid-template-columns: minmax(0, 1fr);
+    }
+  }
+
+  /* Flow panel */
+  .kit-flow {
+    width: 100%;
+    display: flex;
+    flex-direction: column;
+    gap: 1.125rem;
+    padding: 1.75rem;
+    border: 1px solid var(--sl-color-hairline-light);
+    border-radius: 1.25rem;
+    background: var(--sl-color-bg-nav);
+    text-align: start;
+  }
+  .kit-flow-title {
+    margin: 0;
+    font-family: var(--sl-font-mono);
+    font-size: var(--sl-text-2xs);
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: var(--sl-color-gray-3);
+  }
+  .kit-flow-row {
+    display: grid;
+    grid-template-columns: minmax(0, 9rem) minmax(4rem, 1fr) minmax(0, 9rem);
+    align-items: center;
+    gap: 0.75rem;
+  }
+  .kit-flow-node {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    min-height: 3.25rem;
+    padding: 0.25rem 0.75rem;
+    border: 1.5px solid var(--sl-color-gray-5);
+    border-radius: 0.75rem;
+    font-size: var(--sl-text-sm);
+    font-weight: 600;
+    line-height: 1.25;
+    text-align: center;
+    color: var(--sl-color-white);
+  }
+  .kit-flow-node-hl {
+    border-color: var(--sl-color-white);
+    background: var(--sl-color-white);
+    color: var(--sl-color-black);
+  }
+  .kit-flow-edge {
+    position: relative;
+    display: flex;
+    justify-content: center;
+    padding-bottom: 0.625rem;
+    border-bottom: 2px solid var(--sl-color-gray-3);
+  }
+  .kit-flow-edge::before,
+  .kit-flow-edge::after {
+    position: absolute;
+    bottom: -7px;
+    border-block: 6px solid transparent;
+  }
+  .kit-flow-edge:is([data-arrow='forward'], [data-arrow='both'])::after {
+    content: '';
+    right: -2px;
+    border-left: 9px solid var(--sl-color-gray-3);
+  }
+  .kit-flow-edge:is([data-arrow='back'], [data-arrow='both'])::before {
+    content: '';
+    left: -2px;
+    border-right: 9px solid var(--sl-color-gray-3);
+  }
+  .kit-flow-label {
+    font-family: var(--sl-font-mono);
+    font-size: var(--sl-text-2xs);
+    line-height: 1.3;
+    text-align: center;
+    color: var(--sl-color-gray-2);
+  }
+  .kit-flow-note {
+    margin: 0;
+    padding-top: 0.875rem;
+    border-top: 1px dashed var(--sl-color-hairline-light);
+    font-size: var(--sl-text-sm);
+    color: var(--sl-color-gray-3);
+  }
+
+  /* Sections below the hero */
+  .kit-landing {
+    display: flex;
+    flex-direction: column;
+    gap: 4.5rem;
+    padding-bottom: 3rem;
+  }
+  .kit-landing h2 {
+    margin: 0 0 1.5rem;
+    font-family: var(--kit-display);
+    font-size: clamp(var(--sl-text-3xl), calc(1rem + 2.5vw), var(--sl-text-5xl));
+    letter-spacing: -0.025em;
+    line-height: 1.1;
+    color: var(--sl-color-white);
+  }
+  .kit-features {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr));
+    gap: 1.25rem;
+  }
+  .kit-feature {
+    display: flex;
+    flex-direction: column;
+    gap: 0.75rem;
+    padding: 1.75rem;
+    border: 1px solid var(--sl-color-hairline-light);
+    border-radius: 1rem;
+    background: var(--sl-color-bg-nav);
+  }
+  .kit-feature h3 {
+    margin: 0;
+    font-family: var(--kit-display);
+    font-size: var(--sl-text-xl);
+    letter-spacing: -0.015em;
+    color: var(--sl-color-white);
+  }
+  .kit-feature p {
+    margin: 0;
+    line-height: 1.55;
+    color: var(--sl-color-gray-2);
+  }
+  .kit-number {
+    font-family: var(--sl-font-mono);
+    font-size: var(--sl-text-xs);
+    color: var(--sl-color-text-accent);
+  }
+  .kit-components {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) minmax(0, 2fr);
+    gap: 2rem 3rem;
+    padding: clamp(1.75rem, 4vw, 3.5rem);
+    border-radius: 1.5rem;
+    background: var(--sl-color-gray-6);
+  }
+  .kit-components p {
+    margin: 0;
+    line-height: 1.55;
+    color: var(--sl-color-gray-2);
+  }
+  .kit-components dl {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(14rem, 1fr));
+    gap: 1.25rem 3rem;
+    margin: 0;
+  }
+  @media (max-width: 50rem) {
+    .kit-components {
+      grid-template-columns: minmax(0, 1fr);
+    }
+  }
+  .kit-components dt code {
+    padding: 0;
+    background: none;
+    font-size: var(--sl-text-sm);
+    font-weight: 600;
+    color: var(--sl-color-white);
+  }
+  .kit-components dd {
+    margin: 0.25rem 0 0;
+    font-size: var(--sl-text-sm);
+    color: var(--sl-color-gray-2);
+  }
+  .kit-links {
+    display: grid;
+    gap: 1rem;
+  }
+</style>

package/packages/docs-kit/SiteTitle.astro

@@ -0,0 +1,45 @@
+---
+import Default from '@astrojs/starlight/components/SiteTitle.astro';
+import Select from '@astrojs/starlight/components/Select.astro';
+import { root, version } from 'virtual:docs-kit/site';
+---
+
+<Default />
+{/* Filled from versions.json at runtime, so the docs of a past release list releases made after it. */}
+<kit-versions data-root={root} data-version={version} hidden>
+  <Select icon="open-book" label="Docs version" options={[]} width="auto" />
+</kit-versions>
+
+<script>
+  customElements.define(
+    'kit-versions',
+    class extends HTMLElement {
+      async connectedCallback() {
+        const { root, version } = this.dataset as { root: string; version: string };
+        const select = this.querySelector('select')!;
+        const response = await fetch(`${root}versions.json`).catch(() => undefined);
+        if (!response?.ok) return;
+        const versions: { name: string; path: string; latest?: true }[] = await response.json();
+        const current = version && `${version}/`;
+        // The same page in another version: the URL path below the current version's base.
+        const page = location.pathname.slice(root.length + current.length);
+        for (const { name, path, latest } of versions) {
+          select.add(new Option(latest ? `${name} (latest release)` : name, path, false, path === current));
+        }
+        select.addEventListener('change', async () => {
+          const target = root + select.value;
+          const exists = await fetch(target + page, { method: 'HEAD' }).then((r) => r.ok, () => false);
+          location.href = exists ? target + page : target;
+        });
+        this.hidden = false;
+      }
+    },
+  );
+</script>
+
+<style>
+  kit-versions:not([hidden]) {
+    display: flex;
+    align-items: center;
+  }
+</style>

package/packages/docs-kit/Tree.astro

@@ -0,0 +1,139 @@
+---
+// The inheritance tree: one tab per node with an `id`, numbering the nodes it inherits from, root first.
+import { TabItem, Tabs } from '@astrojs/starlight/components';
+import site from 'virtual:docs-kit/site';
+import { escape, inline } from './text.mjs';
+
+const tree = site.tree;
+const chains = [];
+const walk = (node, chain) => {
+  const here = [...chain, node];
+  if (node.id) chains.push(here);
+  node.children?.forEach((child) => walk(child, here));
+};
+walk(tree.root, []);
+
+const render = (node, chain) => {
+  const step = chain.indexOf(node) + 1;
+  const row =
+    `<div class="kit-tree-row"${step ? ` data-step="${step}"` : ''}>` +
+    `<span class="kit-tree-step">${step || ''}</span>` +
+    `<code>${escape(node.name)}</code>` +
+    (node.file ? `<span class="kit-tree-file">${escape(node.file)}</span>` : '') +
+    (node.note ? `<span class="kit-tree-note">${inline(node.note)}</span>` : '') +
+    '</div>';
+  const children = node.children ? `<ul>${node.children.map((c) => render(c, chain)).join('')}</ul>` : '';
+  return `<li>${row}${children}</li>`;
+};
+---
+
+<section class="kit-tree" aria-labelledby="kit-tree-title">
+  <div>
+    <h2 id="kit-tree-title">{tree.title ?? 'How settings inherit'}</h2>
+    {tree.intro && <p set:html={inline(tree.intro)} />}
+  </div>
+  <div class="kit-tree-panel">
+    <Tabs>
+      {
+        chains.map((chain) => (
+          <TabItem label={chain.at(-1).id}>
+            <ul class="kit-tree-list" set:html={render(tree.root, chain)} />
+          </TabItem>
+        ))
+      }
+    </Tabs>
+  </div>
+</section>
+
+<style is:global>
+  .kit-tree {
+    display: grid;
+    grid-template-columns: minmax(0, 2fr) minmax(0, 3fr);
+    gap: 2rem 3rem;
+    align-items: start;
+  }
+  @media (max-width: 50rem) {
+    .kit-tree {
+      grid-template-columns: minmax(0, 1fr);
+    }
+  }
+  .kit-tree > div > p {
+    margin: 0;
+    line-height: 1.55;
+    color: var(--sl-color-gray-2);
+  }
+  .kit-tree-panel {
+    min-width: 0;
+    padding: 0.5rem 1.25rem 1.25rem;
+    border: 1px solid var(--sl-color-hairline-light);
+    border-radius: 1rem;
+    background: var(--sl-color-bg-nav);
+  }
+  .kit-tree starlight-tabs {
+    display: block;
+  }
+  .kit-tree-list,
+  .kit-tree-list ul {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+  .kit-tree-list {
+    margin-top: 1rem;
+  }
+  .kit-tree-list ul {
+    margin-left: 0.875rem;
+    padding-left: 1rem;
+    border-left: 1px solid var(--sl-color-gray-5);
+  }
+  .kit-tree-list li {
+    margin: 0;
+  }
+  .kit-tree-row {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 0.25rem 0.625rem;
+    padding: 0.375rem 0;
+    font-size: var(--sl-text-sm);
+    color: var(--sl-color-gray-3);
+  }
+  .kit-tree-row > code {
+    padding: 0;
+    background: none;
+    font-size: var(--sl-text-sm);
+    color: var(--sl-color-gray-3);
+  }
+  .kit-tree-step {
+    display: inline-grid;
+    place-items: center;
+    width: 1.5rem;
+    height: 1.5rem;
+    border: 1px dashed var(--sl-color-gray-5);
+    border-radius: 50%;
+    font-family: var(--sl-font-mono);
+    font-size: var(--sl-text-xs);
+  }
+  .kit-tree-file {
+    font-family: var(--sl-font-mono);
+    font-size: var(--sl-text-xs);
+  }
+  .kit-tree-note {
+    flex-basis: 100%;
+    padding-left: 2.125rem;
+    font-size: var(--sl-text-xs);
+  }
+  .kit-tree-row[data-step] {
+    color: var(--sl-color-gray-2);
+  }
+  .kit-tree-row[data-step] > code {
+    font-weight: 600;
+    color: var(--sl-color-white);
+  }
+  .kit-tree-row[data-step] .kit-tree-step {
+    border: 0;
+    background: var(--sl-color-text-accent);
+    color: var(--sl-color-black);
+    font-weight: 600;
+  }
+</style>

package/packages/docs-kit/content.mjs

@@ -0,0 +1,5 @@
+import { docsLoader } from '@astrojs/starlight/loaders';
+import { docsSchema } from '@astrojs/starlight/schema';
+import { defineCollection } from 'astro:content';
+
+export const collections = { docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }) };

package/packages/docs-kit/index.mjs

@@ -0,0 +1,94 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import starlight from '@astrojs/starlight';
+import { defineConfig } from 'astro/config';
+import { parse } from 'yaml';
+import { validateSite } from '../../schema/validate.mjs';
+
+const kitPath = (path) => fileURLToPath(new URL(path, import.meta.url));
+
+/** Builds the whole Astro config of a consuming project from its site.yaml (path relative to the working directory). */
+export default function docsKit({ site: sitePath = 'site.yaml' } = {}) {
+  const site = parse(readFileSync(sitePath, 'utf8'));
+  const errors = validateSite(site);
+  if (errors.length) throw new Error(`${sitePath} is invalid:\n  ${errors.join('\n  ')}`);
+
+  // Hosting is GitHub Pages per repo: https://github.com/<owner>/<repo> is served at https://<owner>.github.io/<repo>,
+  // or at the root of its custom domain.
+  const [owner, repo] = new URL(site.repo).pathname.split('/').filter(Boolean);
+  const root = site.domain ? '' : `/${repo}`;
+  // Set by docs-kit-versions when it builds a release's docs into <root>/<version>/.
+  const version = process.env.DOCS_KIT_VERSION ?? '';
+  if (!/^[\w.-]*$/.test(version)) throw new Error(`DOCS_KIT_VERSION '${version}' is not a path segment`);
+  const base = version ? `${root}/${version}` : root;
+
+  // Starlight links public/favicon.svg itself; these are linked only when the project ships them.
+  const icons = [
+    ['favicon.ico', { rel: 'icon', sizes: '32x32' }],
+    ['apple-touch-icon.png', { rel: 'apple-touch-icon' }],
+  ]
+    .filter(([file]) => existsSync(`public/${file}`))
+    .map(([file, attrs]) => ({ tag: 'link', attrs: { ...attrs, href: `${base}/${file}` } }));
+  // A release's docs stay readable but out of search results, which should point at the current docs.
+  const noindex = version ? [{ tag: 'meta', attrs: { name: 'robots', content: 'noindex' } }] : [];
+
+  return defineConfig({
+    site: site.domain ? `https://${site.domain}` : `https://${owner.toLowerCase()}.github.io`,
+    base: base || '/',
+    vite: { plugins: [siteModule(site, { version, root: `${root}/` })] },
+    integrations: [
+      starlight({
+        title: site.name,
+        description: site.tagline,
+        logo: site.logo && (site.logo.dark ? { light: site.logo.light, dark: site.logo.dark } : { src: site.logo.light }),
+        head: [
+          ...icons,
+          ...noindex,
+          ...(site.analytics
+            ? [{ tag: 'script', attrs: { src: site.analytics.script, defer: true, ...site.analytics.attributes } }]
+            : []),
+        ],
+        social: [{ icon: 'github', label: 'GitHub', href: site.repo }],
+        // A release's pages live in a tag, which GitHub cannot edit.
+        editLink: version ? {} : { baseUrl: `${site.repo}/edit/main/docs/` },
+        components: site.versions ? { SiteTitle: kitPath('SiteTitle.astro'), Banner: kitPath('Banner.astro') } : {},
+        customCss: [kitPath('layout.css'), kitPath(`themes/${site.theme ?? 'default'}.css`)],
+        sidebar: [
+          { label: 'Getting started', slug: 'getting-started' },
+          ...['Guides', 'Concepts', 'Reference'].map((label) => ({
+            label,
+            items: [{ autogenerate: { directory: label.toLowerCase() } }],
+          })),
+        ],
+      }),
+      {
+        name: 'docs-kit',
+        hooks: {
+          'astro:config:setup': ({ injectRoute }) => {
+            injectRoute({ pattern: '/', entrypoint: kitPath('Landing.astro') });
+            injectRoute({ pattern: '/[...slug].md', entrypoint: kitPath('page.md.mjs') });
+            injectRoute({ pattern: '/[name].txt', entrypoint: kitPath('llms.txt.mjs') });
+          },
+        },
+      },
+    ],
+  });
+}
+
+/**
+ * Exposes the validated site.yaml to the kit's components as `virtual:docs-kit/site`, with the docs version being built
+ * ('' for the default branch) and the site root URL path, where versions.json lives.
+ */
+function siteModule(site, { version, root }) {
+  const id = 'virtual:docs-kit/site';
+  const code = [
+    `export default ${JSON.stringify(site)};`,
+    `export const version = ${JSON.stringify(version)};`,
+    `export const root = ${JSON.stringify(root)};`,
+  ].join('\n');
+  return {
+    name: 'docs-kit-site',
+    resolveId: (source) => (source === id ? `\0${id}` : undefined),
+    load: (resolved) => (resolved === `\0${id}` ? code : undefined),
+  };
+}