create-thally-docs 0.7.1 → 0.7.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -1
- package/dist/{chunk-YAG5BZEM.js → chunk-PGTE4X3G.js} +1 -1
- package/dist/chunk-WMVWYKAB.js +789 -0
- package/dist/index.js +46 -16
- package/dist/migrate/index.js +2 -2
- package/dist/scaffold.js +1 -1
- package/package.json +1 -1
- package/dist/chunk-6HO6ECUE.js +0 -454
|
@@ -0,0 +1,789 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
// src/scaffold.ts
|
|
4
|
+
import { existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync as readdirSync2 } from "fs";
|
|
5
|
+
import { resolve } from "path";
|
|
6
|
+
|
|
7
|
+
// src/download.ts
|
|
8
|
+
import { Readable, pipeline } from "stream";
|
|
9
|
+
import { promisify } from "util";
|
|
10
|
+
import tar from "tar";
|
|
11
|
+
var pipelineAsync = promisify(pipeline);
|
|
12
|
+
var TEMPLATE_REPOSITORY = "thallylabs/docs";
|
|
13
|
+
var TARBALL_URL = `https://codeload.github.com/${TEMPLATE_REPOSITORY}/tar.gz/main`;
|
|
14
|
+
var EXCLUDE_PATHS = [
|
|
15
|
+
// Match both the directory entry itself and every nested file. Tar invokes
|
|
16
|
+
// the filter for `.../node_modules` before descendants, without a trailing `/`.
|
|
17
|
+
"/node_modules",
|
|
18
|
+
// The canonical docs repository may temporarily retain package sources while
|
|
19
|
+
// runtime work is being upstreamed. A scaffold consumes the published
|
|
20
|
+
// packages declared in package.json; it must never inherit those sources.
|
|
21
|
+
"/packages",
|
|
22
|
+
"/.git/",
|
|
23
|
+
"/.next/",
|
|
24
|
+
"/.data/",
|
|
25
|
+
"/.thally/",
|
|
26
|
+
"/thally-agent.yml",
|
|
27
|
+
"/thally-track.yml",
|
|
28
|
+
"/CODEOWNERS",
|
|
29
|
+
"/CLAUDE.md",
|
|
30
|
+
"/notes/",
|
|
31
|
+
"/public/images/",
|
|
32
|
+
"/src/public/",
|
|
33
|
+
"/snippets/",
|
|
34
|
+
"/.github/ISSUE_TEMPLATE/",
|
|
35
|
+
"/.github/PULL_REQUEST_TEMPLATE.md",
|
|
36
|
+
"/README.md"
|
|
37
|
+
];
|
|
38
|
+
function shouldInclude(path) {
|
|
39
|
+
for (const excluded of EXCLUDE_PATHS) {
|
|
40
|
+
if (path.includes(excluded)) {
|
|
41
|
+
return false;
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
return true;
|
|
45
|
+
}
|
|
46
|
+
async function downloadTemplate(targetDir, siteName) {
|
|
47
|
+
console.log("");
|
|
48
|
+
console.log(` \u23F3 Creating ${siteName?.trim() || "your docs site"}...`);
|
|
49
|
+
const response = await fetch(TARBALL_URL);
|
|
50
|
+
if (!response.ok) {
|
|
51
|
+
throw new Error(`Failed to download template: ${response.status} ${response.statusText}`);
|
|
52
|
+
}
|
|
53
|
+
if (!response.body) {
|
|
54
|
+
throw new Error("Response body is empty");
|
|
55
|
+
}
|
|
56
|
+
const nodeStream = Readable.fromWeb(response.body);
|
|
57
|
+
await pipelineAsync(
|
|
58
|
+
nodeStream,
|
|
59
|
+
tar.extract({ cwd: targetDir, strip: 1, filter: shouldInclude })
|
|
60
|
+
);
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
// src/docs-json.ts
|
|
64
|
+
import { readFileSync, writeFileSync } from "fs";
|
|
65
|
+
import { join } from "path";
|
|
66
|
+
function readDocsJson(projectDir) {
|
|
67
|
+
const docsPath = join(projectDir, "docs.json");
|
|
68
|
+
const raw = readFileSync(docsPath, "utf8");
|
|
69
|
+
return JSON.parse(raw);
|
|
70
|
+
}
|
|
71
|
+
function writeDocsJson(projectDir, config) {
|
|
72
|
+
const docsPath = join(projectDir, "docs.json");
|
|
73
|
+
writeFileSync(docsPath, JSON.stringify(config, null, 2) + "\n", "utf8");
|
|
74
|
+
}
|
|
75
|
+
function resetTrackingConfig(projectDir) {
|
|
76
|
+
const config = readDocsJson(projectDir);
|
|
77
|
+
if (config.tracking) {
|
|
78
|
+
delete config.tracking;
|
|
79
|
+
writeDocsJson(projectDir, config);
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
function writeTrackingConfig(projectDir, repos) {
|
|
83
|
+
if (repos.length === 0) return;
|
|
84
|
+
const config = readDocsJson(projectDir);
|
|
85
|
+
config.tracking = { repos: repos.map((r) => ({ owner: r.owner, repo: r.repo, branch: "main" })) };
|
|
86
|
+
writeDocsJson(projectDir, config);
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
// src/customize.ts
|
|
90
|
+
import { existsSync, mkdirSync, writeFileSync as writeFileSync2, readFileSync as readFileSync2, readdirSync, cpSync, rmSync } from "fs";
|
|
91
|
+
import { join as join2 } from "path";
|
|
92
|
+
var STARTER_PAGES = {
|
|
93
|
+
"introduction.mdx": `---
|
|
94
|
+
title: Introduction
|
|
95
|
+
description: Welcome to {NAME}.
|
|
96
|
+
mode: home
|
|
97
|
+
keywords:
|
|
98
|
+
- {NAME}
|
|
99
|
+
- documentation
|
|
100
|
+
- overview
|
|
101
|
+
- getting started
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
<Hero
|
|
105
|
+
title="Welcome to {NAME}"
|
|
106
|
+
subtitle="Use this starter to introduce your product, guide readers to their first successful outcome, and publish a clear API reference."
|
|
107
|
+
primaryLabel="Start the quickstart"
|
|
108
|
+
primaryHref="/quickstart"
|
|
109
|
+
secondaryLabel="See components"
|
|
110
|
+
secondaryHref="/components"
|
|
111
|
+
/>
|
|
112
|
+
|
|
113
|
+
<CardGroup cols={3}>
|
|
114
|
+
<Card title="Quickstart" icon="party-horn" href="/quickstart">
|
|
115
|
+
Show readers the fastest path to a useful first result.
|
|
116
|
+
</Card>
|
|
117
|
+
<Card title="Components" icon="grid-round" href="/components">
|
|
118
|
+
Structure guides with steps, tabs, cards, callouts, accordions, and more.
|
|
119
|
+
</Card>
|
|
120
|
+
<Card title="API reference" icon="code-simple" href="/api">
|
|
121
|
+
Replace \`openapi.yaml\` with your specification to publish interactive endpoints.
|
|
122
|
+
</Card>
|
|
123
|
+
<Card title="Customize" icon="wrench" href="/customization">
|
|
124
|
+
Make the navigation, brand, typography, and links your own.
|
|
125
|
+
</Card>
|
|
126
|
+
<Card title="Multi-language" icon="message" href="/es">
|
|
127
|
+
Switch to the included Spanish example from the language menu.
|
|
128
|
+
</Card>
|
|
129
|
+
<Card title="Agent-ready docs" icon="link-simple" href="/llms.txt">
|
|
130
|
+
Give coding agents a clean, structured version of your documentation.
|
|
131
|
+
</Card>
|
|
132
|
+
</CardGroup>
|
|
133
|
+
|
|
134
|
+
<Note type="info" title="Make it yours">
|
|
135
|
+
Start by editing \`src/content/introduction.mdx\`. Then update \`docs.json\` to
|
|
136
|
+
organize navigation and \`src/data/site.ts\` to set your product name and links.
|
|
137
|
+
</Note>
|
|
138
|
+
`,
|
|
139
|
+
"quickstart.mdx": `---
|
|
140
|
+
title: Quickstart
|
|
141
|
+
description: Give readers the fastest path to a successful first result with {NAME}.
|
|
142
|
+
keywords:
|
|
143
|
+
- {NAME}
|
|
144
|
+
- quickstart
|
|
145
|
+
- installation
|
|
146
|
+
- getting started
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
Describe the prerequisites and the shortest useful workflow. A good quickstart
|
|
150
|
+
takes someone from zero to a visible result without explaining every option.
|
|
151
|
+
|
|
152
|
+
## Prerequisites
|
|
153
|
+
|
|
154
|
+
- Requirement one, such as an account, API key, or supported runtime
|
|
155
|
+
- Requirement two, such as a compatible device, browser, or operating system
|
|
156
|
+
|
|
157
|
+
<Steps>
|
|
158
|
+
<Step title="Install">
|
|
159
|
+
Explain how to install {NAME} or create an account.
|
|
160
|
+
|
|
161
|
+
\`\`\`bash
|
|
162
|
+
npm install your-package
|
|
163
|
+
\`\`\`
|
|
164
|
+
</Step>
|
|
165
|
+
<Step title="Configure">
|
|
166
|
+
Show only the configuration required for the first successful run.
|
|
167
|
+
|
|
168
|
+
\`\`\`bash
|
|
169
|
+
your-cli init
|
|
170
|
+
\`\`\`
|
|
171
|
+
</Step>
|
|
172
|
+
<Step title="Run it">
|
|
173
|
+
Give readers a command or action with an observable result.
|
|
174
|
+
|
|
175
|
+
\`\`\`bash
|
|
176
|
+
your-cli start
|
|
177
|
+
\`\`\`
|
|
178
|
+
</Step>
|
|
179
|
+
</Steps>
|
|
180
|
+
|
|
181
|
+
<Tip>
|
|
182
|
+
Tell readers where to get help, then link to the next guide they should read.
|
|
183
|
+
</Tip>
|
|
184
|
+
`,
|
|
185
|
+
"components.mdx": `---
|
|
186
|
+
title: Components
|
|
187
|
+
description: A compact tour of the rich MDX components available in {NAME}.
|
|
188
|
+
keywords:
|
|
189
|
+
- {NAME}
|
|
190
|
+
- components
|
|
191
|
+
- MDX
|
|
192
|
+
---
|
|
193
|
+
|
|
194
|
+
Use components to keep complex instructions clear without turning every page
|
|
195
|
+
into a wall of text.
|
|
196
|
+
|
|
197
|
+
## Show equivalent paths
|
|
198
|
+
|
|
199
|
+
<Tabs>
|
|
200
|
+
<Tab title="npm">
|
|
201
|
+
\`\`\`bash
|
|
202
|
+
npm install your-package
|
|
203
|
+
\`\`\`
|
|
204
|
+
</Tab>
|
|
205
|
+
<Tab title="pnpm">
|
|
206
|
+
\`\`\`bash
|
|
207
|
+
pnpm add your-package
|
|
208
|
+
\`\`\`
|
|
209
|
+
</Tab>
|
|
210
|
+
<Tab title="yarn">
|
|
211
|
+
\`\`\`bash
|
|
212
|
+
yarn add your-package
|
|
213
|
+
\`\`\`
|
|
214
|
+
</Tab>
|
|
215
|
+
</Tabs>
|
|
216
|
+
|
|
217
|
+
## Reveal detail when it matters
|
|
218
|
+
|
|
219
|
+
<Accordion title="Where should advanced configuration live?">
|
|
220
|
+
Keep the default path visible and move optional detail into an accordion. This
|
|
221
|
+
lets new readers move quickly without hiding information from experts.
|
|
222
|
+
</Accordion>
|
|
223
|
+
|
|
224
|
+
## Communicate status
|
|
225
|
+
|
|
226
|
+
<Badge variant="success">Stable</Badge>{" "}
|
|
227
|
+
<Badge variant="warning">Beta</Badge>{" "}
|
|
228
|
+
<Badge variant="info">New</Badge>
|
|
229
|
+
|
|
230
|
+
<Tip>
|
|
231
|
+
Browse the complete component library at [docs.thally.io](https://docs.thally.io/components/card).
|
|
232
|
+
</Tip>
|
|
233
|
+
`,
|
|
234
|
+
"customization.mdx": `---
|
|
235
|
+
title: Customization
|
|
236
|
+
description: Make {NAME} feel unmistakably like your product.
|
|
237
|
+
keywords:
|
|
238
|
+
- {NAME}
|
|
239
|
+
- branding
|
|
240
|
+
- navigation
|
|
241
|
+
---
|
|
242
|
+
|
|
243
|
+
Your documentation should feel like part of the product\u2014not a separate website.
|
|
244
|
+
|
|
245
|
+
<CardGroup cols={2}>
|
|
246
|
+
<Card title="Brand and theme" icon="party-horn" href="https://docs.thally.io/guides/branding-and-theming">
|
|
247
|
+
Configure colors, logos, favicons, typography, and light or dark presentation.
|
|
248
|
+
</Card>
|
|
249
|
+
<Card title="Navigation" icon="book-open" href="https://docs.thally.io/guides/configuring-navigation">
|
|
250
|
+
Organize tabs, icon-labelled groups, pages, and external destinations in \`docs.json\`.
|
|
251
|
+
</Card>
|
|
252
|
+
<Card title="Domains" icon="link-simple" href="https://app.thally.io">
|
|
253
|
+
Connect a custom domain from your site settings in Thally Cloud.
|
|
254
|
+
</Card>
|
|
255
|
+
<Card title="Analytics and feedback" icon="message" href="https://app.thally.io">
|
|
256
|
+
Learn what readers need and collect feedback without third-party widgets.
|
|
257
|
+
</Card>
|
|
258
|
+
</CardGroup>
|
|
259
|
+
|
|
260
|
+
<Note type="info" title="Start with docs.json">
|
|
261
|
+
Navigation and portable presentation settings live in \`docs.json\`. Site
|
|
262
|
+
identity and fallback brand values live in \`src/data/site.ts\`.
|
|
263
|
+
</Note>
|
|
264
|
+
`,
|
|
265
|
+
"changelog.mdx": `---
|
|
266
|
+
title: Changelog
|
|
267
|
+
description: Notable changes, releases, and improvements to {NAME}.
|
|
268
|
+
keywords:
|
|
269
|
+
- {NAME}
|
|
270
|
+
- changelog
|
|
271
|
+
- releases
|
|
272
|
+
- updates
|
|
273
|
+
---
|
|
274
|
+
|
|
275
|
+
## v0.1.0
|
|
276
|
+
|
|
277
|
+
The first release of your **{NAME}** documentation.
|
|
278
|
+
|
|
279
|
+
- Initial docs site scaffolded with [Thally](https://github.com/thallylabs/thally)
|
|
280
|
+
- Agent-ready endpoints live: \`/llms.txt\`, \`/ai.txt\`, \`/api/docs-index\`, and \`/api/agent-readiness\`
|
|
281
|
+
- Starter guides in the Overview tab and an interactive API reference
|
|
282
|
+
|
|
283
|
+
Edit this page at \`src/content/changelog.mdx\` to announce your own releases as you ship.
|
|
284
|
+
`
|
|
285
|
+
};
|
|
286
|
+
var STARTER_SPANISH_PAGES = {
|
|
287
|
+
"introduction.mdx": `---
|
|
288
|
+
title: Introducci\xF3n
|
|
289
|
+
description: Te damos la bienvenida a {NAME}.
|
|
290
|
+
mode: home
|
|
291
|
+
---
|
|
292
|
+
|
|
293
|
+
<Hero
|
|
294
|
+
title="Te damos la bienvenida a {NAME}"
|
|
295
|
+
subtitle="Usa este sitio inicial para presentar tu producto, guiar a tus lectores hasta su primer resultado y publicar una referencia de API clara."
|
|
296
|
+
primaryLabel="Abrir inicio r\xE1pido"
|
|
297
|
+
primaryHref="/es/quickstart"
|
|
298
|
+
secondaryLabel="Ver componentes"
|
|
299
|
+
secondaryHref="/es/components"
|
|
300
|
+
/>
|
|
301
|
+
|
|
302
|
+
<CardGroup cols={3}>
|
|
303
|
+
<Card title="Inicio r\xE1pido" icon="party-horn" href="/es/quickstart">
|
|
304
|
+
Ayuda a tus lectores a lograr su primer resultado en minutos.
|
|
305
|
+
</Card>
|
|
306
|
+
<Card title="Componentes" icon="grid-round" href="/es/components">
|
|
307
|
+
Usa pesta\xF1as, pasos, tarjetas, avisos y acordeones.
|
|
308
|
+
</Card>
|
|
309
|
+
<Card title="Referencia de API" icon="code-simple" href="/es/api">
|
|
310
|
+
Convierte \`openapi.yaml\` en documentaci\xF3n interactiva.
|
|
311
|
+
</Card>
|
|
312
|
+
<Card title="Personalizaci\xF3n" icon="wrench" href="/es/customization">
|
|
313
|
+
Adapta la navegaci\xF3n, marca, tipograf\xEDa y enlaces.
|
|
314
|
+
</Card>
|
|
315
|
+
<Card title="Varios idiomas" icon="message" href="/">
|
|
316
|
+
Cambia entre ingl\xE9s y espa\xF1ol desde el selector de idioma.
|
|
317
|
+
</Card>
|
|
318
|
+
<Card title="Preparado para IA" icon="link-simple" href="/llms.txt">
|
|
319
|
+
Publica contenido legible por agentes desde el primer d\xEDa.
|
|
320
|
+
</Card>
|
|
321
|
+
</CardGroup>
|
|
322
|
+
`,
|
|
323
|
+
"quickstart.mdx": `---
|
|
324
|
+
title: Inicio r\xE1pido
|
|
325
|
+
description: Gu\xEDa a tus lectores hasta su primer resultado con {NAME}.
|
|
326
|
+
---
|
|
327
|
+
|
|
328
|
+
Un buen inicio r\xE1pido lleva al lector de cero a un resultado visible sin explicar
|
|
329
|
+
todas las opciones.
|
|
330
|
+
|
|
331
|
+
<Steps>
|
|
332
|
+
<Step title="Instala">
|
|
333
|
+
Explica c\xF3mo instalar {NAME} o crear una cuenta.
|
|
334
|
+
|
|
335
|
+
\`\`\`bash
|
|
336
|
+
npm install your-package
|
|
337
|
+
\`\`\`
|
|
338
|
+
</Step>
|
|
339
|
+
<Step title="Configura">
|
|
340
|
+
Muestra \xFAnicamente la configuraci\xF3n necesaria para comenzar.
|
|
341
|
+
</Step>
|
|
342
|
+
<Step title="Ejecuta">
|
|
343
|
+
Termina con una acci\xF3n y un resultado que el lector pueda comprobar.
|
|
344
|
+
</Step>
|
|
345
|
+
</Steps>
|
|
346
|
+
|
|
347
|
+
<Tip>Enlaza la siguiente gu\xEDa que deber\xEDa leer una vez completado este flujo.</Tip>
|
|
348
|
+
`,
|
|
349
|
+
"components.mdx": `---
|
|
350
|
+
title: Componentes
|
|
351
|
+
description: Una muestra de los componentes MDX disponibles en {NAME}.
|
|
352
|
+
---
|
|
353
|
+
|
|
354
|
+
<Tabs>
|
|
355
|
+
<Tab title="npm">\`npm install your-package\`</Tab>
|
|
356
|
+
<Tab title="pnpm">\`pnpm add your-package\`</Tab>
|
|
357
|
+
<Tab title="yarn">\`yarn add your-package\`</Tab>
|
|
358
|
+
</Tabs>
|
|
359
|
+
|
|
360
|
+
<Accordion title="\xBFD\xF3nde debe ir la configuraci\xF3n avanzada?">
|
|
361
|
+
Mant\xE9n visible el camino principal y coloca los detalles opcionales aqu\xED.
|
|
362
|
+
</Accordion>
|
|
363
|
+
|
|
364
|
+
<Badge variant="success">Estable</Badge>{" "}
|
|
365
|
+
<Badge variant="warning">Beta</Badge>{" "}
|
|
366
|
+
<Badge variant="info">Nuevo</Badge>
|
|
367
|
+
`,
|
|
368
|
+
"customization.mdx": `---
|
|
369
|
+
title: Personalizaci\xF3n
|
|
370
|
+
description: Haz que {NAME} se sienta como una parte natural de tu producto.
|
|
371
|
+
---
|
|
372
|
+
|
|
373
|
+
<CardGroup cols={2}>
|
|
374
|
+
<Card title="Marca y tema" icon="party-horn">Configura colores, logotipos, tipograf\xEDa y apariencia.</Card>
|
|
375
|
+
<Card title="Navegaci\xF3n" icon="book-open">Organiza pesta\xF1as, grupos con iconos y p\xE1ginas en \`docs.json\`.</Card>
|
|
376
|
+
<Card title="Dominios" icon="link-simple">Conecta un dominio personalizado desde Thally Cloud.</Card>
|
|
377
|
+
<Card title="Anal\xEDtica y feedback" icon="message">Comprende qu\xE9 necesitan tus lectores.</Card>
|
|
378
|
+
</CardGroup>
|
|
379
|
+
`,
|
|
380
|
+
"changelog.mdx": `---
|
|
381
|
+
title: Novedades
|
|
382
|
+
description: Cambios, versiones y mejoras destacadas de {NAME}.
|
|
383
|
+
---
|
|
384
|
+
|
|
385
|
+
## v0.1.0
|
|
386
|
+
|
|
387
|
+
La primera versi\xF3n de la documentaci\xF3n de **{NAME}**.
|
|
388
|
+
|
|
389
|
+
- Sitio creado con [Thally](https://github.com/thallylabs/thally)
|
|
390
|
+
- Referencia de API y contenido preparado para agentes
|
|
391
|
+
- Ejemplo biling\xFCe en ingl\xE9s y espa\xF1ol
|
|
392
|
+
`
|
|
393
|
+
};
|
|
394
|
+
function buildStarterDocsJson({
|
|
395
|
+
enableAiChat,
|
|
396
|
+
repoUrl,
|
|
397
|
+
i18nLocales
|
|
398
|
+
}) {
|
|
399
|
+
const config = {};
|
|
400
|
+
config.theme = "default";
|
|
401
|
+
if (enableAiChat) {
|
|
402
|
+
config.ai = { chat: true };
|
|
403
|
+
}
|
|
404
|
+
if (repoUrl) {
|
|
405
|
+
config.navbar = {
|
|
406
|
+
links: [{ label: "GitHub", href: repoUrl, type: "github" }],
|
|
407
|
+
primary: { label: "Get started", href: "/quickstart" }
|
|
408
|
+
};
|
|
409
|
+
}
|
|
410
|
+
const locales = [
|
|
411
|
+
{ code: "en", label: "English" },
|
|
412
|
+
{ code: "es", label: "Espa\xF1ol" },
|
|
413
|
+
...(i18nLocales ?? []).filter(({ code }) => code !== "en" && code !== "es")
|
|
414
|
+
];
|
|
415
|
+
config.i18n = { defaultLocale: "en", locales };
|
|
416
|
+
config.tabs = [
|
|
417
|
+
{
|
|
418
|
+
tab: "Overview",
|
|
419
|
+
groups: [
|
|
420
|
+
{ group: "Getting Started", icon: "book-open", pages: ["introduction", "quickstart"] },
|
|
421
|
+
{ group: "Explore", icon: "grid-round", pages: ["components"] },
|
|
422
|
+
{ group: "Project", icon: "wrench", pages: ["customization"] }
|
|
423
|
+
]
|
|
424
|
+
},
|
|
425
|
+
{ tab: "API Reference", api: { source: "openapi.yaml" } },
|
|
426
|
+
{ tab: "Changelog", href: "/changelog" }
|
|
427
|
+
];
|
|
428
|
+
return JSON.stringify(config, null, 2) + "\n";
|
|
429
|
+
}
|
|
430
|
+
function writeStarterContent(targetDir, projectName, enableAiChat = true, repoUrl = "", i18nLocales) {
|
|
431
|
+
const contentDir = join2(targetDir, "src", "content");
|
|
432
|
+
if (existsSync(contentDir)) {
|
|
433
|
+
const entries = readdirSync(contentDir);
|
|
434
|
+
for (const entry of entries) {
|
|
435
|
+
const fullPath = join2(contentDir, entry);
|
|
436
|
+
rmSync(fullPath, { recursive: true, force: true });
|
|
437
|
+
}
|
|
438
|
+
} else {
|
|
439
|
+
mkdirSync(contentDir, { recursive: true });
|
|
440
|
+
}
|
|
441
|
+
for (const [filename, template] of Object.entries(STARTER_PAGES)) {
|
|
442
|
+
const content = template.replace(/\{NAME\}/g, projectName);
|
|
443
|
+
writeFileSync2(join2(contentDir, filename), content, "utf8");
|
|
444
|
+
}
|
|
445
|
+
const spanishDir = join2(contentDir, "es");
|
|
446
|
+
mkdirSync(spanishDir, { recursive: true });
|
|
447
|
+
for (const [filename, template] of Object.entries(STARTER_SPANISH_PAGES)) {
|
|
448
|
+
const content = template.replace(/\{NAME\}/g, projectName);
|
|
449
|
+
writeFileSync2(join2(spanishDir, filename), content, "utf8");
|
|
450
|
+
}
|
|
451
|
+
writeFileSync2(
|
|
452
|
+
join2(targetDir, "docs.json"),
|
|
453
|
+
buildStarterDocsJson({ enableAiChat, repoUrl: repoUrl || void 0, i18nLocales }),
|
|
454
|
+
"utf8"
|
|
455
|
+
);
|
|
456
|
+
}
|
|
457
|
+
function writeStarterAgentGuide(targetDir, projectName) {
|
|
458
|
+
const guide = `# ${projectName} documentation instructions
|
|
459
|
+
|
|
460
|
+
## About this project
|
|
461
|
+
|
|
462
|
+
- This is a documentation site built with [Thally](https://github.com/thallylabs/thally).
|
|
463
|
+
- Pages are MDX files with YAML frontmatter in \`src/content/\`.
|
|
464
|
+
- Navigation and product features are configured in \`docs.json\`.
|
|
465
|
+
- Site identity and fallback brand values live in \`src/data/site.ts\`.
|
|
466
|
+
- Use \`/llms.txt\`, \`/llms-full.txt\`, and \`/skill.md\` on the deployed site for agent-readable context.
|
|
467
|
+
|
|
468
|
+
## Terminology
|
|
469
|
+
|
|
470
|
+
<!-- Add product-specific terms and preferred usage. -->
|
|
471
|
+
|
|
472
|
+
## Writing style
|
|
473
|
+
|
|
474
|
+
- Use active voice and address the reader as \u201Cyou.\u201D
|
|
475
|
+
- Keep sentences concise and headings in sentence case.
|
|
476
|
+
- Bold interface labels and format commands, files, and code with backticks.
|
|
477
|
+
- Lead with the outcome, then explain prerequisites and steps.
|
|
478
|
+
|
|
479
|
+
## Content boundaries
|
|
480
|
+
|
|
481
|
+
<!-- Define what belongs in public docs and what must remain internal. -->
|
|
482
|
+
`;
|
|
483
|
+
writeFileSync2(join2(targetDir, "AGENTS.md"), guide, "utf8");
|
|
484
|
+
}
|
|
485
|
+
function writeStarterReadme(targetDir, projectName) {
|
|
486
|
+
const readme = `# ${projectName}
|
|
487
|
+
|
|
488
|
+
Documentation powered by [Thally](https://github.com/thallylabs/thally).
|
|
489
|
+
|
|
490
|
+
## Local development
|
|
491
|
+
|
|
492
|
+
\`\`\`bash
|
|
493
|
+
npm install
|
|
494
|
+
npm run dev
|
|
495
|
+
\`\`\`
|
|
496
|
+
|
|
497
|
+
The server starts at [http://localhost:3040](http://localhost:3040), or the next
|
|
498
|
+
available port when 3040 is already in use.
|
|
499
|
+
|
|
500
|
+
## Write your docs
|
|
501
|
+
|
|
502
|
+
- Add MDX pages in \`src/content/\`.
|
|
503
|
+
- Organize navigation and product features in \`docs.json\`.
|
|
504
|
+
- Update the site name, links, and brand defaults in \`src/data/site.ts\`.
|
|
505
|
+
- Copy \`.env.example\` to \`.env.local\` for local secrets.
|
|
506
|
+
|
|
507
|
+
The starter includes a home hero, icon-grouped navigation, English and Spanish
|
|
508
|
+
examples, a guided quickstart, component showcase, changelog, OpenAPI reference,
|
|
509
|
+
and \`AGENTS.md\` writing instructions for coding agents.
|
|
510
|
+
|
|
511
|
+
## Publishing changes
|
|
512
|
+
|
|
513
|
+
Push changes to the default branch to trigger your connected deployment. If the
|
|
514
|
+
site is not connected yet, add the repository in
|
|
515
|
+
[Thally Cloud](https://app.thally.io) or deploy it to any Next.js host.
|
|
516
|
+
|
|
517
|
+
Run \`npx create-thally-docs check --ci .\` before publishing. Deploy the site
|
|
518
|
+
anywhere Next.js is supported, or connect the repository to
|
|
519
|
+
[Thally Cloud](https://app.thally.io) for managed hosting and services.
|
|
520
|
+
`;
|
|
521
|
+
writeFileSync2(join2(targetDir, "README.md"), readme, "utf8");
|
|
522
|
+
}
|
|
523
|
+
function updateSiteConfig(targetDir, projectName, description, brandPreset, repoUrl) {
|
|
524
|
+
const siteFile = join2(targetDir, "src", "data", "site.ts");
|
|
525
|
+
if (!existsSync(siteFile)) {
|
|
526
|
+
console.log(" \u26A0\uFE0F Could not find src/data/site.ts \u2014 skipping config update.");
|
|
527
|
+
return;
|
|
528
|
+
}
|
|
529
|
+
let source = readFileSync2(siteFile, "utf8");
|
|
530
|
+
source = source.replace(
|
|
531
|
+
/name:\s*'[^']*'/,
|
|
532
|
+
`name: '${projectName.replace(/'/g, "\\'")}'`
|
|
533
|
+
);
|
|
534
|
+
source = source.replace(
|
|
535
|
+
/description:\s*\n\s*'[^']*'/,
|
|
536
|
+
`description:
|
|
537
|
+
'${description.replace(/'/g, "\\'")}'`
|
|
538
|
+
);
|
|
539
|
+
source = source.replace(
|
|
540
|
+
/const brandPreset:\s*BrandPresetKey\s*=\s*'[^']*'/,
|
|
541
|
+
`const brandPreset: BrandPresetKey = '${brandPreset}'`
|
|
542
|
+
);
|
|
543
|
+
source = source.replace(/repoUrl:\s*'[^']*'/, `repoUrl: '${repoUrl}'`);
|
|
544
|
+
source = source.replace(
|
|
545
|
+
/\{\s*label:\s*'GitHub',\s*href:\s*'[^']*'\s*\}/,
|
|
546
|
+
`{ label: 'GitHub', href: '${repoUrl}' }`
|
|
547
|
+
);
|
|
548
|
+
source = source.replace(
|
|
549
|
+
/\{\s*label:\s*'Support',\s*href:\s*'[^']*'\s*\}/,
|
|
550
|
+
`{ label: 'Support', href: '${repoUrl ? `${repoUrl}/issues/new` : ""}' }`
|
|
551
|
+
);
|
|
552
|
+
if (!repoUrl) {
|
|
553
|
+
source = source.replace(
|
|
554
|
+
/\n\s*\{\s*label:\s*'(?:GitHub|Support)',\s*href:\s*''\s*\},?/g,
|
|
555
|
+
""
|
|
556
|
+
);
|
|
557
|
+
}
|
|
558
|
+
writeFileSync2(siteFile, source, "utf8");
|
|
559
|
+
}
|
|
560
|
+
function patchApiReferenceGuard(targetDir) {
|
|
561
|
+
const filePath = join2(targetDir, "src", "data", "api-reference.ts");
|
|
562
|
+
if (!existsSync(filePath)) return;
|
|
563
|
+
let source = readFileSync2(filePath, "utf8");
|
|
564
|
+
source = source.replace(
|
|
565
|
+
/export async function buildApiNavigation\([^)]*\)[^{]*\{\n/,
|
|
566
|
+
(match) => `${match} if (apiReferenceConfig.specs.length === 0) return []
|
|
567
|
+
`
|
|
568
|
+
);
|
|
569
|
+
writeFileSync2(filePath, source, "utf8");
|
|
570
|
+
}
|
|
571
|
+
function patchTopBarNavigation(targetDir) {
|
|
572
|
+
const filePath = join2(targetDir, "src", "components", "layout", "top-bar.tsx");
|
|
573
|
+
if (!existsSync(filePath)) return;
|
|
574
|
+
const source = readFileSync2(filePath, "utf8");
|
|
575
|
+
if (!source.includes("target={isExternal ? '_blank' : undefined}")) return;
|
|
576
|
+
const patched = source.replace(
|
|
577
|
+
/if \(collection\.href\) \{\n const isExternal[^\n]+\n return \(\n <a[\s\S]*?<\/a>\n \)\n \}/,
|
|
578
|
+
`if (collection.href) {
|
|
579
|
+
const isExternal = /^https?:\\/\\//.test(collection.href)
|
|
580
|
+
if (isExternal) {
|
|
581
|
+
return (
|
|
582
|
+
<a
|
|
583
|
+
key={collection.id}
|
|
584
|
+
href={collection.href}
|
|
585
|
+
target="_blank"
|
|
586
|
+
rel="noreferrer"
|
|
587
|
+
className={baseClasses}
|
|
588
|
+
>
|
|
589
|
+
{collection.label}
|
|
590
|
+
</a>
|
|
591
|
+
)
|
|
592
|
+
}
|
|
593
|
+
return (
|
|
594
|
+
<Link
|
|
595
|
+
key={collection.id}
|
|
596
|
+
href={collection.href}
|
|
597
|
+
className={baseClasses}
|
|
598
|
+
>
|
|
599
|
+
{collection.label}
|
|
600
|
+
</Link>
|
|
601
|
+
)
|
|
602
|
+
}`
|
|
603
|
+
);
|
|
604
|
+
writeFileSync2(filePath, patched, "utf8");
|
|
605
|
+
}
|
|
606
|
+
function patchOpenApiFetch(targetDir) {
|
|
607
|
+
const filePath = join2(targetDir, "src", "lib", "openapi", "fetch.ts");
|
|
608
|
+
if (!existsSync(filePath)) return;
|
|
609
|
+
let source = readFileSync2(filePath, "utf8");
|
|
610
|
+
source = source.replace(
|
|
611
|
+
/const absolutePath = path\.isAbsolute\(filePath\) \? filePath : path\.resolve\(process\.cwd\(\), filePath\)/,
|
|
612
|
+
`const absolutePath = filePath.startsWith('/')
|
|
613
|
+
? path.resolve(process.cwd(), 'public', filePath.slice(1))
|
|
614
|
+
: path.resolve(process.cwd(), filePath)`
|
|
615
|
+
);
|
|
616
|
+
writeFileSync2(filePath, source, "utf8");
|
|
617
|
+
}
|
|
618
|
+
function updateEnvExample(targetDir) {
|
|
619
|
+
const envFile = join2(targetDir, ".env.example");
|
|
620
|
+
if (existsSync(envFile)) {
|
|
621
|
+
const envLocal = join2(targetDir, ".env.local");
|
|
622
|
+
if (!existsSync(envLocal)) {
|
|
623
|
+
cpSync(envFile, envLocal);
|
|
624
|
+
}
|
|
625
|
+
}
|
|
626
|
+
}
|
|
627
|
+
function patchPackageJson(targetDir, slug) {
|
|
628
|
+
const pkgPath = join2(targetDir, "package.json");
|
|
629
|
+
if (!existsSync(pkgPath)) return;
|
|
630
|
+
const pkg = JSON.parse(readFileSync2(pkgPath, "utf8"));
|
|
631
|
+
const hadWorkspaces = Array.isArray(pkg.workspaces) && pkg.workspaces.length > 0;
|
|
632
|
+
pkg.name = slug;
|
|
633
|
+
delete pkg.workspaces;
|
|
634
|
+
if (pkg.scripts) {
|
|
635
|
+
if (pkg.scripts["prebuild"]) pkg.scripts["prebuild"] = "npm run embeddings:build";
|
|
636
|
+
delete pkg.scripts["pretest"];
|
|
637
|
+
delete pkg.scripts["packages:build"];
|
|
638
|
+
}
|
|
639
|
+
if (pkg.dependencies?.["@thallylabs/mcp"] === "*") {
|
|
640
|
+
pkg.dependencies["@thallylabs/mcp"] = "0.7.0";
|
|
641
|
+
}
|
|
642
|
+
writeFileSync2(pkgPath, `${JSON.stringify(pkg, null, 2)}
|
|
643
|
+
`, "utf8");
|
|
644
|
+
const lockPath = join2(targetDir, "package-lock.json");
|
|
645
|
+
if (!existsSync(lockPath)) return;
|
|
646
|
+
const lock = JSON.parse(readFileSync2(lockPath, "utf8"));
|
|
647
|
+
const hasWorkspaceEntries = Object.keys(lock.packages ?? {}).some(
|
|
648
|
+
(key) => key === "packages" || key.startsWith("packages/")
|
|
649
|
+
);
|
|
650
|
+
if (hadWorkspaces || hasWorkspaceEntries) {
|
|
651
|
+
rmSync(lockPath);
|
|
652
|
+
return;
|
|
653
|
+
}
|
|
654
|
+
lock.name = slug;
|
|
655
|
+
if (lock.packages?.[""]) lock.packages[""].name = slug;
|
|
656
|
+
writeFileSync2(lockPath, `${JSON.stringify(lock, null, 2)}
|
|
657
|
+
`, "utf8");
|
|
658
|
+
}
|
|
659
|
+
function patchGitignore(targetDir) {
|
|
660
|
+
const gitignorePath = join2(targetDir, ".gitignore");
|
|
661
|
+
const existing = existsSync(gitignorePath) ? readFileSync2(gitignorePath, "utf8") : "";
|
|
662
|
+
const lines = existing.split(/\r?\n/);
|
|
663
|
+
if (lines.includes("node_modules/")) return;
|
|
664
|
+
const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
|
|
665
|
+
writeFileSync2(gitignorePath, `${existing}${separator}node_modules/
|
|
666
|
+
`, "utf8");
|
|
667
|
+
}
|
|
668
|
+
|
|
669
|
+
// src/utils.ts
|
|
670
|
+
import { execSync } from "child_process";
|
|
671
|
+
import { basename } from "path";
|
|
672
|
+
function slugify(name) {
|
|
673
|
+
return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
|
|
674
|
+
}
|
|
675
|
+
function run(cmd, cwd) {
|
|
676
|
+
execSync(cmd, { cwd, stdio: "inherit" });
|
|
677
|
+
}
|
|
678
|
+
function initGit(targetDir) {
|
|
679
|
+
try {
|
|
680
|
+
run("git init", targetDir);
|
|
681
|
+
run("git add -A", targetDir);
|
|
682
|
+
run('git commit -m "Initial commit from create-thally-docs"', targetDir);
|
|
683
|
+
} catch {
|
|
684
|
+
console.log(" \u26A0\uFE0F Could not initialize git (you can do this manually).");
|
|
685
|
+
}
|
|
686
|
+
}
|
|
687
|
+
function installDeps(targetDir) {
|
|
688
|
+
console.log("");
|
|
689
|
+
console.log(" \u{1F4E6} Installing dependencies...");
|
|
690
|
+
console.log("");
|
|
691
|
+
run("npm install --prefer-offline --no-audit --no-fund --progress=false", targetDir);
|
|
692
|
+
}
|
|
693
|
+
function logo() {
|
|
694
|
+
console.log("");
|
|
695
|
+
console.log(" \u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557");
|
|
696
|
+
console.log(" \u2551 \u2551");
|
|
697
|
+
console.log(" \u2551 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557 \u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2557 \u2588\u2588\u2557 \u2588\u2588\u2557 \u2588\u2588\u2557 \u2551");
|
|
698
|
+
console.log(" \u2551 \u255A\u2550\u2550\u2588\u2588\u2554\u2550\u2550\u255D\u2588\u2588\u2551 \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2551 \u2588\u2588\u2551 \u255A\u2588\u2588\u2557 \u2588\u2588\u2554\u255D \u2551");
|
|
699
|
+
console.log(" \u2551 \u2588\u2588\u2551 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2551 \u2588\u2588\u2551 \u255A\u2588\u2588\u2588\u2588\u2554\u255D \u2551");
|
|
700
|
+
console.log(" \u2551 \u2588\u2588\u2551 \u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2551\u2588\u2588\u2551 \u2588\u2588\u2551 \u255A\u2588\u2588\u2554\u255D \u2551");
|
|
701
|
+
console.log(" \u2551 \u2588\u2588\u2551 \u2588\u2588\u2551 \u2588\u2588\u2551\u2588\u2588\u2551 \u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2551 \u2551");
|
|
702
|
+
console.log(" \u2551 \u255A\u2550\u255D \u255A\u2550\u255D \u255A\u2550\u255D\u255A\u2550\u255D \u255A\u2550\u255D\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D \u255A\u2550\u255D \u2551");
|
|
703
|
+
console.log(" \u2551 \u2551");
|
|
704
|
+
console.log(" \u2551Give your product and docs first-class agent visibility.\u2551");
|
|
705
|
+
console.log(" \u2551 \u2551");
|
|
706
|
+
console.log(" \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D");
|
|
707
|
+
console.log("");
|
|
708
|
+
}
|
|
709
|
+
function success(projectDir, projectName, dependenciesInstalled) {
|
|
710
|
+
console.log("");
|
|
711
|
+
console.log(" \u2705 Your Thally project is ready!");
|
|
712
|
+
console.log("");
|
|
713
|
+
console.log(` \u{1F4C2} ${projectDir}`);
|
|
714
|
+
console.log("");
|
|
715
|
+
console.log(" Next steps:");
|
|
716
|
+
console.log("");
|
|
717
|
+
console.log(` cd ${basename(projectDir)}`);
|
|
718
|
+
if (!dependenciesInstalled) {
|
|
719
|
+
console.log(" npm install");
|
|
720
|
+
}
|
|
721
|
+
console.log(" npm run dev");
|
|
722
|
+
console.log("");
|
|
723
|
+
console.log(` Your terminal will print the local URL for your ${projectName} docs.`);
|
|
724
|
+
console.log("");
|
|
725
|
+
console.log(" \u{1F4DD} Key files to edit:");
|
|
726
|
+
console.log(" \u2022 src/data/site.ts \u2014 name, links, branding");
|
|
727
|
+
console.log(" \u2022 docs.json \u2014 navigation structure");
|
|
728
|
+
console.log(" \u2022 src/content/*.mdx \u2014 your documentation");
|
|
729
|
+
console.log(" \u2022 openapi.yaml \u2014 API spec (optional)");
|
|
730
|
+
console.log("");
|
|
731
|
+
console.log(" Happy documenting! \u{1F680}");
|
|
732
|
+
console.log("");
|
|
733
|
+
}
|
|
734
|
+
|
|
735
|
+
// src/scaffold.ts
|
|
736
|
+
async function scaffold(options) {
|
|
737
|
+
const {
|
|
738
|
+
projectDir,
|
|
739
|
+
projectName,
|
|
740
|
+
description,
|
|
741
|
+
brandPreset,
|
|
742
|
+
repoUrl,
|
|
743
|
+
doInstall,
|
|
744
|
+
enableAiChat = true,
|
|
745
|
+
i18nLocales,
|
|
746
|
+
trackRepos
|
|
747
|
+
} = options;
|
|
748
|
+
const targetDir = resolve(projectDir);
|
|
749
|
+
if (existsSync2(targetDir) && readdirSync2(targetDir).length > 0) {
|
|
750
|
+
throw new Error(`Directory "${targetDir}" already exists and is not empty.`);
|
|
751
|
+
}
|
|
752
|
+
mkdirSync2(targetDir, { recursive: true });
|
|
753
|
+
const slug = slugify(projectName);
|
|
754
|
+
await downloadTemplate(targetDir, projectName);
|
|
755
|
+
resetTrackingConfig(targetDir);
|
|
756
|
+
if (trackRepos?.length) {
|
|
757
|
+
writeTrackingConfig(targetDir, trackRepos);
|
|
758
|
+
const list = trackRepos.map((r) => `${r.owner}/${r.repo}`).join(", ");
|
|
759
|
+
console.log(` \u2713 Thally Track enabled \u2014 watching ${list} (branch main, all files; refine in docs.json).`);
|
|
760
|
+
console.log(" To finish wiring it: `thally track setup` (pick a trigger) + `thally agent init`,");
|
|
761
|
+
console.log(" then add your ANTHROPIC_API_KEY. See /guides/thally-track.");
|
|
762
|
+
}
|
|
763
|
+
writeStarterContent(targetDir, projectName, enableAiChat, repoUrl, i18nLocales);
|
|
764
|
+
writeStarterReadme(targetDir, projectName);
|
|
765
|
+
writeStarterAgentGuide(targetDir, projectName);
|
|
766
|
+
updateSiteConfig(targetDir, projectName, description, brandPreset, repoUrl);
|
|
767
|
+
patchApiReferenceGuard(targetDir);
|
|
768
|
+
patchTopBarNavigation(targetDir);
|
|
769
|
+
patchOpenApiFetch(targetDir);
|
|
770
|
+
patchPackageJson(targetDir, slug);
|
|
771
|
+
patchGitignore(targetDir);
|
|
772
|
+
updateEnvExample(targetDir);
|
|
773
|
+
if (doInstall) {
|
|
774
|
+
installDeps(targetDir);
|
|
775
|
+
}
|
|
776
|
+
initGit(targetDir);
|
|
777
|
+
return { projectDir: targetDir };
|
|
778
|
+
}
|
|
779
|
+
|
|
780
|
+
export {
|
|
781
|
+
slugify,
|
|
782
|
+
initGit,
|
|
783
|
+
installDeps,
|
|
784
|
+
logo,
|
|
785
|
+
success,
|
|
786
|
+
readDocsJson,
|
|
787
|
+
writeDocsJson,
|
|
788
|
+
scaffold
|
|
789
|
+
};
|