@icebreakers/monorepo-templates 2.0.7 → 2.2.0

package/templates/nimbus/UPSTREAM.md

@@ -0,0 +1,16 @@
+# Upstream source
+
+This template adapts the static empty starter from [Cloudflare Nimbus](https://github.com/cloudflare/nimbus), released under the MIT license (see `LICENSE`).
+
+- Starter tag: `templates-v0.7.9`
+- Starter commit: `aae348048a8c659f84c39696ee6b20c2ad2f5ae2`
+- Nimbus package: `@cloudflare/nimbus-docs@0.15.2`
+- Astro: `7.3.1`
+
+Nimbus declares Astro `>=7.2.6 <8`; Astro requires Node `>=22.12.0`, so this workspace retains its stricter Node `>=22.13.0` baseline. Builds, Astro diagnostics and TypeScript checks were verified with the repository's TypeScript `6.0.3` and Vite `8.3.1` constraints. Resolved dependencies are recorded in the monorepo's root `pnpm-lock.yaml`; generated projects use their own root workspace lockfile.
+
+Agent endpoint routes and the content-loading approach come from that starter. The bilingual layout, navigation, search interface, examples and workspace checks are repoctl adaptations. These files are maintained locally; generating a project never downloads the upstream starter.
+
+The local head component emits page-specific language metadata because the upstream head uses the site-wide locale. Client scripts are emitted as external assets so Astro does not inline them before Vite finalizes Pagefind's dynamic import.
+
+The package version and starter tag were checked against published package metadata. `nimbus.json` records the reviewed package API baseline. The original full starter was not copied wholesale, so upstream starter diffs are not a claim that every local file is an unmodified upstream component.

package/templates/nimbus/astro.config.ts

@@ -0,0 +1,28 @@
+import nimbus, { defineConfig as defineNimbusConfig } from '@cloudflare/nimbus-docs'
+import { defineConfig } from 'astro/config'
+
+export default defineConfig({
+  output: 'static',
+  // Keep the Pagefind loader external so Vite finalizes dynamic imports before Astro renders it.
+  vite: { build: { assetsInlineLimit: 0 } },
+  integrations: [nimbus(defineNimbusConfig({
+    // Set your production origin before publishing.
+    site: 'https://docs.example.com',
+    title: 'Project docs',
+    description: 'Guides and examples for your project.',
+    locale: 'en',
+    github: null,
+  }), {
+    icons: false,
+    rules: {
+      'nimbus/frontmatter-shape': 'error',
+      'nimbus/internal-link': 'error',
+      'nimbus/single-h1': 'error',
+    },
+    markdown: {
+      componentMap: {
+        Aside: { revision: '1', render: ({ children }) => children },
+      },
+    },
+  })],
+})

package/templates/nimbus/eslint.config.js

@@ -0,0 +1,25 @@
+import astro from 'eslint-plugin-astro'
+import * as mdx from 'eslint-plugin-mdx'
+import { defineEslintConfig } from 'repoctl/tooling'
+
+const shared = await defineEslintConfig({ options: { astro: false, formatters: false } })
+
+// Markup has its own parser and formatter. Shared JS rules still check the
+// virtual TypeScript files extracted from Astro script blocks.
+const code = shared.map((config) => {
+  if (Object.keys(config).every(key => key === 'name' || key === 'ignores')) {
+    return config
+  }
+  return { ...config, ignores: [...(config.ignores ?? []), '**/*.astro', '**/*.mdx', '**/*.mdx/**'] }
+})
+
+export default [
+  ...code,
+  ...astro.configs['flat/recommended'],
+  {
+    ...mdx.flat,
+    files: ['**/*.mdx'],
+    languageOptions: { ...mdx.flat.languageOptions, globals: { Aside: 'readonly' } },
+  },
+  { ignores: ['.astro/**', '.nimbus/**', 'dist/**', '**/*.css'] },
+]

package/templates/nimbus/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+.astro/
+.nimbus/
+.turbo/

package/templates/nimbus/nimbus.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://nimbus-docs.com/schema/nimbus.json",
+  "lastReviewedNimbusVersion": "0.15.2"
+}

package/templates/nimbus/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@icebreakers/nimbus-template",
+  "type": "module",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Bilingual Nimbus documentation starter",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "dev": "astro dev",
+    "build": "pnpm check:locales && astro build",
+    "preview": "astro preview",
+    "typecheck": "astro check && tsc --noEmit",
+    "lint": "eslint . && stylelint \"src/styles/**/*.css\" && nimbus-docs lint",
+    "lint:docs": "nimbus-docs lint",
+    "lint:docs:fix": "nimbus-docs lint --fix",
+    "check:locales": "node scripts/check-locales.mjs"
+  },
+  "dependencies": {
+    "@cloudflare/nimbus-docs": "0.15.2",
+    "astro": "7.3.5"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.10",
+    "@astrojs/language-server": "2.17.1",
+    "astro-eslint-parser": "^3.2.0",
+    "eslint-plugin-astro": "^3.2.1",
+    "eslint-plugin-mdx": "^3.8.1",
+    "pagefind": "^1.5.2",
+    "typescript": "^6.0.3"
+  }
+}

package/templates/nimbus/public/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="7" fill="#1d4ed8"/><path d="M9 8h10l4 4v12H9zM18 8v5h5M12 17h8M12 21h6" fill="none" stroke="white" stroke-width="1.6" stroke-linejoin="round"/></svg>

package/templates/nimbus/scripts/check-locales.mjs

@@ -0,0 +1,11 @@
+import assert from 'node:assert/strict'
+import { readdir } from 'node:fs/promises'
+import path from 'node:path'
+
+const content = new URL('../src/content/docs/', import.meta.url)
+const files = await readdir(content, { recursive: true })
+const pages = files.filter(file => /\.mdx?$/.test(file)).map(file => file.split(path.sep).join('/'))
+const english = pages.filter(file => !file.startsWith('zh/')).sort()
+const chinese = pages.filter(file => file.startsWith('zh/')).map(file => file.slice(3)).sort()
+assert.deepEqual(chinese, english, 'Every published page needs matching English and Chinese source files.')
+console.log(`Locale parity checked: ${english.length} page pairs.`)

package/templates/nimbus/src/components/aside.astro

@@ -0,0 +1,9 @@
+---
+interface Props { title?: string }
+const { title } = Astro.props
+---
+
+<aside class="callout">
+  {title && <strong>{title}</strong>}
+  <slot />
+</aside>

package/templates/nimbus/src/components/head.astro

@@ -0,0 +1,43 @@
+---
+import { withBase } from '@cloudflare/nimbus-docs/runtime'
+import { config } from 'virtual:nimbus/config'
+
+interface Props {
+  title: string
+  description?: string | undefined
+  markdownUrl?: string | undefined
+  noindex?: boolean | undefined
+  chinese: boolean
+}
+
+const { title, description = config.description, markdownUrl, noindex, chinese } = Astro.props
+const base = import.meta.env.BASE_URL
+const fullTitle = `${title} | ${config.title}`
+const language = chinese ? 'zh-CN' : 'en'
+const canonical = new URL(Astro.url.pathname, Astro.site)
+const structuredData = JSON.stringify({
+  '@context': 'https://schema.org',
+  '@type': 'WebPage',
+  'name': fullTitle,
+  description,
+  'url': canonical.href,
+  'inLanguage': language,
+})
+---
+
+<title>{fullTitle}</title>
+<meta name="generator" content={Astro.generator} />
+<meta name="description" content={description} />
+{noindex && <meta name="robots" content="noindex" />}
+<link rel="icon" type="image/svg+xml" href={withBase('/favicon.svg', base)} />
+<link rel="stylesheet" href={withBase('/_nimbus/shiki.css', base)} />
+<link rel="canonical" href={canonical} />
+<link rel="sitemap" href={withBase('/sitemap-index.xml', base)} />
+{markdownUrl && <link rel="alternate" type="text/markdown" href={new URL(withBase(markdownUrl, base), Astro.site)} />}
+<meta property="og:title" content={fullTitle} />
+<meta property="og:type" content="article" />
+<meta property="og:site_name" content={config.title} />
+<meta property="og:locale" content={chinese ? 'zh_CN' : 'en_US'} />
+<meta property="og:description" content={description} />
+<meta property="og:url" content={canonical} />
+<script type="application/ld+json" set:html={structuredData} />

package/templates/nimbus/src/components/search/client.ts

@@ -0,0 +1,62 @@
+interface SearchResult {
+  url: string
+  meta: { title?: string }
+}
+
+interface Pagefind {
+  init: () => Promise<void>
+  search: (query: string) => Promise<{ results: { data: () => Promise<SearchResult> }[] }>
+}
+
+// Pagefind is emitted by the Nimbus production build, not bundled by Vite.
+export function mountSearch(root: HTMLElement) {
+  const form = root.querySelector('form')!
+  const input = root.querySelector('input')!
+  const status = root.querySelector<HTMLElement>('[role="status"]')!
+  const results = root.querySelector('ul')!
+  let api: Promise<Pagefind> | undefined
+  let request = 0
+
+  form.addEventListener('submit', async (event) => {
+    event.preventDefault()
+    const current = ++request
+    results.replaceChildren()
+    const query = input.value.trim()
+    if (!query) {
+      status.textContent = ''
+      return
+    }
+    status.textContent = root.dataset.loading ?? ''
+    try {
+      const base = (root.dataset.base ?? '/').replace(/\/$/, '')
+      api ??= import(/* @vite-ignore */ `${base}/pagefind/pagefind.js`).then(async (module: Pagefind) => {
+        await module.init()
+        return module
+      })
+      const response = await (await api).search(query)
+      const pages = await Promise.all(response.results.slice(0, 10).map(result => result.data()))
+      if (current !== request) {
+        return
+      }
+      status.textContent = pages.length ? '' : root.dataset.empty ?? ''
+      for (const page of pages) {
+        const url = new URL(page.url, window.location.origin)
+        if (url.origin !== window.location.origin) {
+          continue
+        }
+        const item = document.createElement('li')
+        const link = document.createElement('a')
+        link.href = url.href
+        link.textContent = page.meta.title ?? page.url
+        item.append(link)
+        results.append(item)
+      }
+    }
+    catch {
+      api = undefined
+      if (current === request) {
+        status.textContent = root.dataset.unavailable ?? ''
+      }
+    }
+  })
+}

package/templates/nimbus/src/components/search/index.astro

@@ -0,0 +1,26 @@
+---
+import { labels } from '../../lib/locale'
+
+interface Props { chinese: boolean }
+const { chinese } = Astro.props
+const text = labels[chinese ? 'zh' : 'en']
+---
+
+<details class="search-panel" data-search data-base={import.meta.env.BASE_URL} data-loading={text.loading} data-empty={text.empty} data-unavailable={text.unavailable}>
+  <summary>{text.search}</summary>
+  <form role="search">
+    <label for="docs-search">{text.search}</label>
+    <div class="search-controls">
+      <input id="docs-search" name="query" type="search" required autocomplete="off" />
+      <button type="submit">{text.submit}</button>
+    </div>
+  </form>
+  <p role="status" aria-live="polite"></p>
+  <ul class="search-results"></ul>
+</details>
+
+<script>
+  import { mountSearch } from './client'
+
+  document.querySelectorAll<HTMLElement>('[data-search]').forEach(mountSearch)
+</script>

package/templates/nimbus/src/components/sidebar.astro

@@ -0,0 +1,26 @@
+---
+import type { SidebarItem } from '@cloudflare/nimbus-docs/types'
+import { withBase } from '@cloudflare/nimbus-docs/runtime'
+
+interface Props { items: SidebarItem[] }
+const { items } = Astro.props
+---
+
+<ul class="navigation-list">
+  {items.map(item => (
+    <li>
+      {item.type === 'group'
+        ? (
+            <>
+              {item.indexHref
+                ? <a href={withBase(item.indexHref, import.meta.env.BASE_URL)} aria-current={item.indexIsCurrent ? 'page' : undefined}>{item.label}</a>
+                : <span>{item.label}</span>}
+              <Astro.self items={item.children} />
+            </>
+          )
+        : (
+            <a href={withBase(item.href, import.meta.env.BASE_URL)} aria-current={item.type === 'link' && item.isCurrent ? 'page' : undefined}>{item.label}</a>
+          )}
+    </li>
+  ))}
+</ul>

package/templates/nimbus/src/components.ts

@@ -0,0 +1,3 @@
+import Aside from './components/aside.astro'
+
+export const components = { Aside }

package/templates/nimbus/src/content/docs/get-started.mdx

@@ -0,0 +1,36 @@
+---
+title: Quick start
+description: Run, edit and publish your documentation.
+sidebar:
+  order: 1
+---
+
+## Install dependencies
+
+At the monorepo root:
+
+```sh
+corepack enable
+pnpm install
+```
+
+## Start the site
+
+In the documentation workspace:
+
+```sh
+pnpm dev
+```
+
+Edit `src/content/docs/index.mdx` and its Chinese counterpart `src/content/docs/zh/index.mdx`.
+
+## Build and preview
+
+```sh
+pnpm build
+pnpm preview
+```
+
+The build writes `dist/` and creates the search index. Set your production URL in `astro.config.ts` before publishing.
+
+Continue with the [writing guide](/writing/).

package/templates/nimbus/src/content/docs/index.mdx

@@ -0,0 +1,16 @@
+---
+title: Welcome
+description: A home for your project’s guides and examples.
+sidebar:
+  order: 0
+---
+
+## Start with the essentials
+
+Follow the [quick start](/get-started/) to run this site locally, then use the [writing guide](/writing/) to add your own documentation.
+
+## One source, two ways to read
+
+Read in your browser or open the Markdown link below each page. The documentation index at `/llms.txt` helps tools find individual pages without downloading the entire site.
+
+[阅读中文文档](/zh/)

package/templates/nimbus/src/content/docs/writing.mdx

@@ -0,0 +1,35 @@
+---
+title: Writing guide
+description: Add pages that work for readers and tools.
+sidebar:
+  order: 2
+---
+
+## Add a page
+
+Create matching files under `src/content/docs/` and `src/content/docs/zh/`. Give each page a title, description and sidebar order in frontmatter.
+
+```yaml
+title: Your page
+description: What the reader will learn.
+sidebar:
+  order: 3
+```
+
+## Use components carefully
+
+<Aside>
+Keep the meaning of an example in its text. Interactive illustrations should have a written explanation too.
+</Aside>
+
+Register components in `src/components.ts` and their text representation in `astro.config.ts`.
+
+## Validate before publishing
+
+```sh
+pnpm build
+pnpm lint
+pnpm typecheck
+```
+
+Use `draft: true` while a page is unfinished. Open the published Markdown link and check that examples, links and component text are readable.

package/templates/nimbus/src/content/docs/zh/get-started.mdx

@@ -0,0 +1,36 @@
+---
+title: 快速开始
+description: 运行、编辑和发布你的文档。
+sidebar:
+  order: 1
+---
+
+## 安装依赖
+
+在 monorepo 根目录执行：
+
+```sh
+corepack enable
+pnpm install
+```
+
+## 启动站点
+
+进入文档工作区执行：
+
+```sh
+pnpm dev
+```
+
+编辑 `src/content/docs/zh/index.mdx`，并同步英文版本 `src/content/docs/index.mdx`。
+
+## 构建与预览
+
+```sh
+pnpm build
+pnpm preview
+```
+
+构建会生成 `dist/` 和搜索索引。发布前，在 `astro.config.ts` 中填写正式站点地址。
+
+继续阅读[写作指南](/zh/writing/)。

package/templates/nimbus/src/content/docs/zh/index.mdx

@@ -0,0 +1,16 @@
+---
+title: 欢迎
+description: 在这里记录项目的使用指南与示例。
+sidebar:
+  order: 0
+---
+
+## 从基础开始
+
+按照[快速开始](/zh/get-started/)在本地运行站点，再参考[写作指南](/zh/writing/)添加自己的文档。
+
+## 一份内容，两种阅读方式
+
+读者可以浏览网页，也可以打开每页底部的 Markdown 链接。文档索引 `/zh/llms.txt`帮助工具定位单个页面，无需下载整个站点。
+
+[Read the English documentation](/)

package/templates/nimbus/src/content/docs/zh/writing.mdx

@@ -0,0 +1,35 @@
+---
+title: 写作指南
+description: 添加适合读者和工具使用的页面。
+sidebar:
+  order: 2
+---
+
+## 添加页面
+
+在 `src/content/docs/` 和 `src/content/docs/zh/` 下创建路径对应的文件，在 frontmatter 中填写标题、描述和导航顺序。
+
+```yaml
+title: 页面标题
+description: 读者将在本页学到什么。
+sidebar:
+  order: 3
+```
+
+## 使用组件
+
+<Aside>
+用文字保留示例的含义。交互图示也需要配套文字说明。
+</Aside>
+
+在 `src/components.ts` 中注册组件，并在 `astro.config.ts` 中定义对应的文本输出。
+
+## 发布前检查
+
+```sh
+pnpm build
+pnpm lint
+pnpm typecheck
+```
+
+未完成的页面设置 `draft: true`。打开构建后的 Markdown 链接，确认示例、链接和组件文字均可阅读。

package/templates/nimbus/src/content.config.ts

@@ -0,0 +1,6 @@
+import { docsCollection } from '@cloudflare/nimbus-docs/content'
+import { defineCollection } from 'astro:content'
+
+export const collections = {
+  docs: defineCollection(docsCollection()),
+}

package/templates/nimbus/src/env.d.ts

@@ -0,0 +1,6 @@
+// Astro checks component props through its generated TSX representation.
+// Plain tsc needs the runtime module shape for imports in src/components.ts.
+declare module '*.astro' {
+  const component: import('astro/runtime/server/index.js').AstroComponentFactory
+  export default component
+}

package/templates/nimbus/src/layouts/docs.astro

@@ -0,0 +1,70 @@
+---
+import type { DocsPageProps } from '@cloudflare/nimbus-docs/types'
+import { withBase } from '@cloudflare/nimbus-docs/runtime'
+import { config } from 'virtual:nimbus/config'
+import Head from '../components/head.astro'
+import Search from '../components/search/index.astro'
+import Sidebar from '../components/sidebar.astro'
+import { labels } from '../lib/locale'
+import '../styles/site.css'
+
+type Props = Omit<DocsPageProps, 'breadcrumbs' | 'prevNext'> & { chinese: boolean, alternate: string }
+const { title, description, sidebar, headings, markdownUrl, chinese, alternate, noindex, draft, searchable } = Astro.props
+const text = labels[chinese ? 'zh' : 'en']
+const base = import.meta.env.BASE_URL
+const indexUrl = withBase(chinese ? '/zh/llms.txt' : '/llms.txt', base)
+---
+
+<!doctype html>
+<html lang={chinese ? 'zh-CN' : 'en'}>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <Head title={title} description={description} markdownUrl={markdownUrl} noindex={noindex || draft} chinese={chinese} />
+    <link rel="alternate" hreflang={chinese ? 'en' : 'zh-CN'} href={new URL(withBase(alternate, base), Astro.site)} />
+    <link rel="alternate" type="text/plain" href={indexUrl} title={text.index} />
+  </head>
+  <body>
+    <a class="skip-link" href="#main-content">{text.skip}</a>
+    <header class="site-header">
+      <a class="brand" href={withBase(chinese ? '/zh/' : '/', base)}>{config.title}</a>
+      <a class="language-link" href={withBase(alternate, base)} lang={chinese ? 'en' : 'zh-CN'}>{chinese ? 'English' : '简体中文'}</a>
+    </header>
+    <div class="docs-grid">
+      <aside class="site-rail">
+        <Search chinese={chinese} />
+        <nav aria-label={text.navigation}>
+          <p class="rail-title">{text.navigation}</p>
+          {sidebar !== false && <Sidebar items={sidebar} />}
+        </nav>
+        <a class="index-link" href={indexUrl}>llms.txt ↗</a>
+      </aside>
+      <main id="main-content" tabindex="-1">
+        <div data-pagefind-body={searchable !== false && !noindex && !draft ? '' : undefined} data-pagefind-ignore={searchable === false || noindex || draft ? '' : undefined}>
+          <h1>{title}</h1>
+          {description && <p class="description">{description}</p>}
+          <article><slot /></article>
+        </div>
+        {markdownUrl && (
+          <footer>
+            <a href={withBase(markdownUrl, base)}>
+              {text.markdown}
+              {' '}
+              ↗
+            </a>
+          </footer>
+        )}
+      </main>
+      <aside class="page-rail">
+        {headings !== false && headings.length > 0 && (
+          <nav aria-label={text.contents}>
+            <p class="rail-title">{text.contents}</p>
+            <ul class="navigation-list">
+              {headings.map(heading => <li><a href={`#${heading.slug}`}>{heading.text}</a></li>)}
+            </ul>
+          </nav>
+        )}
+      </aside>
+    </div>
+  </body>
+</html>

package/templates/nimbus/src/lib/locale.ts

@@ -0,0 +1,50 @@
+import type { SidebarItem } from '@cloudflare/nimbus-docs/types'
+
+export function isChinese(path: string) {
+  return path === '/zh' || path.startsWith('/zh/')
+}
+
+export function alternatePath(path: string) {
+  return isChinese(path) ? path.slice(3) || '/' : `/zh${path}`
+}
+
+export function localizeSidebar(items: SidebarItem[], chinese: boolean): SidebarItem[] {
+  return items.flatMap((item): SidebarItem[] => {
+    if (item.type !== 'group') {
+      return item.type === 'external' || isChinese(item.href) === chinese ? [item] : []
+    }
+    const children = localizeSidebar(item.children, chinese)
+    const indexHref = item.indexHref && isChinese(item.indexHref) === chinese ? item.indexHref : undefined
+    if (!children.length && !indexHref) {
+      return []
+    }
+    return [{ ...item, indexHref, children }]
+  })
+}
+
+export const labels = {
+  en: {
+    navigation: 'On this site',
+    contents: 'On this page',
+    skip: 'Skip to content',
+    search: 'Search documentation',
+    submit: 'Search',
+    empty: 'No matching pages.',
+    loading: 'Searching…',
+    unavailable: 'Search is unavailable. Try again after building the site.',
+    markdown: 'Read Markdown',
+    index: 'Documentation index',
+  },
+  zh: {
+    navigation: '站点导航',
+    contents: '本页目录',
+    skip: '跳转到正文',
+    search: '搜索文档',
+    submit: '搜索',
+    empty: '没有找到匹配的页面。',
+    loading: '正在搜索…',
+    unavailable: '搜索暂不可用，请构建站点后重试。',
+    markdown: '阅读 Markdown',
+    index: '文档索引',
+  },
+} as const

package/templates/nimbus/src/pages/[...slug]/index.md.ts

@@ -0,0 +1,4 @@
+import { markdownRoute } from '@cloudflare/nimbus-docs/agent-endpoints'
+
+export const prerender = true
+export const { GET, getStaticPaths } = markdownRoute()

package/templates/nimbus/src/pages/[...slug]/index.mdx.ts

@@ -0,0 +1,4 @@
+import { markdownSourceRoute } from '@cloudflare/nimbus-docs/agent-endpoints'
+
+export const prerender = true
+export const { GET, getStaticPaths } = markdownSourceRoute()