@icebreakers/monorepo-templates 2.0.7 → 2.1.0

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()

package/templates/nimbus/src/pages/[...slug].astro

@@ -0,0 +1,36 @@
+---
+import { getDocsPage, getDocsStaticPaths, getSidebar, getTOC, stripBase } from '@cloudflare/nimbus-docs/runtime'
+import { components } from '../components'
+import DocsLayout from '../layouts/docs.astro'
+import { alternatePath, isChinese, localizeSidebar } from '../lib/locale'
+
+export const prerender = true
+export const getStaticPaths = getDocsStaticPaths
+
+const page = await getDocsPage(Astro)
+if (page instanceof Response) {
+  return page
+}
+const { entry, Content, headings, markdownUrl } = page
+const pathname = stripBase(Astro.url.pathname, import.meta.env.BASE_URL)
+const chinese = isChinese(pathname)
+const sidebar = localizeSidebar(await getSidebar(pathname), chinese)
+const toc = entry.data.tableOfContents === false ? false : getTOC(headings, entry.data.tableOfContents)
+---
+
+<DocsLayout
+  title={entry.data.title}
+  description={entry.data.description}
+  sidebar={entry.data.sidebar === false ? false : sidebar}
+  headings={toc}
+  markdownUrl={markdownUrl}
+  collection={entry.collection}
+  entryId={entry.id}
+  noindex={entry.data.noindex}
+  draft={entry.data.draft}
+  searchable={entry.data.searchable}
+  chinese={chinese}
+  alternate={alternatePath(pathname)}
+>
+  <Content components={components} />
+</DocsLayout>

package/templates/nimbus/src/pages/[section]/llms.txt.ts

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

package/templates/nimbus/src/pages/llms-full.txt.ts

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

package/templates/nimbus/src/pages/llms.txt.ts

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

package/templates/nimbus/src/pages/robots.txt.ts

@@ -0,0 +1,18 @@
+import { withBase } from '@cloudflare/nimbus-docs/runtime'
+import { config } from 'virtual:nimbus/config'
+
+export const prerender = true
+
+export function GET() {
+  const body = [
+    'User-agent: *',
+    'Allow: /',
+    '',
+    `Sitemap: ${new URL(withBase('/sitemap-index.xml', import.meta.env.BASE_URL), config.site).href}`,
+    '',
+  ].join('\n')
+
+  return new Response(body, {
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  })
+}

package/templates/nimbus/src/styles/base.css

@@ -0,0 +1,121 @@
+@layer base {
+  :root {
+    font-family: system-ui, sans-serif;
+    line-height: 1.7;
+    color: var(--ink);
+    color-scheme: light dark;
+    background: var(--surface);
+
+    --surface: #fafbfc;
+    --ink: #263247;
+    --muted: #5d6b80;
+    --line: #dce2eb;
+    --accent: #1d4ed8;
+    --soft: #edf2fc;
+  }
+
+  * {
+  box-sizing: border-box;
+}
+
+  body {
+  margin: 0;
+}
+
+  a {
+  color: var(--accent);
+  text-underline-offset: 0.2em;
+}
+
+  a:hover {
+  text-decoration-thickness: 2px;
+}
+
+  :focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 4px;
+}
+
+  h1, h2, h3 {
+  line-height: 1.25;
+  text-wrap: balance;
+}
+
+  h1 {
+  margin: 0 0 1rem;
+  font-family: Charter, Georgia, serif;
+  font-size: clamp(2.4rem, 5vw, 3.6rem);
+  font-weight: 500;
+}
+
+  h2 {
+  margin-top: 2.5rem;
+  font-size: 1.5rem;
+}
+
+  h3 {
+  margin-top: 2rem;
+}
+
+  p, li {
+  overflow-wrap: anywhere;
+}
+
+  code {
+  font-family: ui-monospace, monospace;
+  font-size: 0.88em;
+}
+
+  pre {
+  padding: 1.2rem;
+  overflow: auto;
+  border: 1px solid var(--line);
+  border-radius: 0.4rem;
+}
+
+  :not(pre) > code {
+  padding: 0.15rem 0.35rem;
+  background: var(--soft);
+  border-radius: 0.2rem;
+}
+
+  img {
+  max-width: 100%;
+}
+
+  table {
+  display: block;
+  overflow-x: auto;
+  border-collapse: collapse;
+}
+
+  td, th {
+  padding: 0.6rem 1rem;
+  text-align: start;
+  border: 1px solid var(--line);
+}
+
+  button, input {
+  font: inherit;
+}
+
+  button, summary {
+  cursor: pointer;
+}
+
+  button {
+  padding: 0.4rem 0.7rem;
+  color: var(--surface);
+  background: var(--accent);
+  border: 0;
+  border-radius: 0.3rem;
+}
+
+  input {
+  width: 100%;
+  min-width: 0;
+  padding: 0.4rem;
+  border: 1px solid var(--line);
+  border-radius: 0.3rem;
+}
+}