@gitpagedocs/cli 0.0.1

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.
Files changed (91) hide show
  1. package/README.md +193 -0
  2. package/ai/application/ai-command.ts +24 -0
  3. package/ai/application/ai-provider-factory.ts +22 -0
  4. package/ai/application/docs-pattern.ts +72 -0
  5. package/ai/application/resolve-chat-credentials.ts +69 -0
  6. package/ai/application/run-ai-cli-command.ts +167 -0
  7. package/ai/config.ts +50 -0
  8. package/ai/core/chat-session.ts +44 -0
  9. package/ai/core/models/ai-cli-config.ts +33 -0
  10. package/ai/core/models/parse-ai-cli-config.ts +76 -0
  11. package/ai/core/ports/illm-provider.ts +32 -0
  12. package/ai/infrastructure/ai-config-file.ts +101 -0
  13. package/ai/infrastructure/file-system-adapter.ts +85 -0
  14. package/ai/infrastructure/llm/tools-llm-provider.ts +54 -0
  15. package/ai/infrastructure/version-docs-writer.ts +143 -0
  16. package/ai/presentation/ai-prompts.ts +239 -0
  17. package/application/config-only/handler.mjs +57 -0
  18. package/application/home/handler.mjs +87 -0
  19. package/application/ports/cli-runtime-ports.ts +93 -0
  20. package/application/report/config-only-reporter.mjs +68 -0
  21. package/application/use-cases/dispatch-mode.ts +18 -0
  22. package/builders/config-orchestrator.mjs +35 -0
  23. package/builders/language-bundles-builder.mjs +24 -0
  24. package/builders/project-links.mjs +50 -0
  25. package/builders/root-config-builder.d.mts +16 -0
  26. package/builders/root-config-builder.mjs +56 -0
  27. package/builders/route-builders.mjs +136 -0
  28. package/builders/theme-template.mjs +76 -0
  29. package/builders/version-config-builder.mjs +186 -0
  30. package/content/docs-en.mjs +556 -0
  31. package/content/docs-es.mjs +469 -0
  32. package/content/docs-pt.mjs +469 -0
  33. package/content/docs.mjs +9 -0
  34. package/contracts/doc-versions.mjs +3 -0
  35. package/contracts/index.mjs +11 -0
  36. package/contracts/langs-paths.mjs +28 -0
  37. package/contracts/languages.mjs +6 -0
  38. package/contracts/layouts-paths.d.mts +17 -0
  39. package/contracts/layouts-paths.mjs +68 -0
  40. package/contracts/path-segments.d.mts +2 -0
  41. package/contracts/path-segments.mjs +15 -0
  42. package/data/default-site-config.mjs +328 -0
  43. package/data/i18n-langmenu.mjs +350 -0
  44. package/data/i18n-translations.mjs +20 -0
  45. package/data/layouts.mjs +437 -0
  46. package/data/path-mappings.mjs +26 -0
  47. package/data/route-metas.mjs +93 -0
  48. package/data/theme-colors.mjs +444 -0
  49. package/data/urls.mjs +12 -0
  50. package/data/version-constants.mjs +3 -0
  51. package/domain/models/cli-options.ts +33 -0
  52. package/domain/services/layouts-migration.d.mts +15 -0
  53. package/domain/services/layouts-migration.mjs +74 -0
  54. package/domain/services/sanitize-segment.mjs +7 -0
  55. package/home/constants.mjs +4 -0
  56. package/home/home-file-writer.mjs +19 -0
  57. package/home/templates.mjs +51 -0
  58. package/index.mjs +38 -0
  59. package/infrastructure/config-only/runtime.mjs +17 -0
  60. package/infrastructure/gitpagedocs-config-file.ts +47 -0
  61. package/infrastructure/home/runtime.mjs +37 -0
  62. package/package.json +60 -0
  63. package/presentation/commands/ai-info.ts +57 -0
  64. package/presentation/commands/chat.ts +259 -0
  65. package/presentation/commands/config-clear.ts +23 -0
  66. package/presentation/commands/config-info.ts +72 -0
  67. package/presentation/commands/diagnostics.ts +174 -0
  68. package/presentation/commands/docs.ts +42 -0
  69. package/presentation/commands/mcp.ts +20 -0
  70. package/presentation/commands/pages.ts +103 -0
  71. package/presentation/commands/password.ts +62 -0
  72. package/presentation/commands/run-command.ts +72 -0
  73. package/presentation/index.ts +125 -0
  74. package/presentation/options/parser.ts +120 -0
  75. package/presentation/options/resolver.ts +46 -0
  76. package/presentation/options/schema.ts +14 -0
  77. package/presentation/ui/banner.ts +13 -0
  78. package/presentation/ui/clack.ts +91 -0
  79. package/presentation/ui/layouts-prompts.ts +124 -0
  80. package/presentation/ui/prompts.ts +147 -0
  81. package/presentation/ui/terminal-stream.ts +97 -0
  82. package/presentation/ui/tty.ts +37 -0
  83. package/runtime/doc-path-resolver.mjs +59 -0
  84. package/runtime/exec.mjs +168 -0
  85. package/runtime/git-ops.mjs +112 -0
  86. package/runtime/layouts-migrator.d.mts +11 -0
  87. package/runtime/layouts-migrator.mjs +117 -0
  88. package/runtime/output.mjs +201 -0
  89. package/runtime/workflow.mjs +131 -0
  90. package/start.mjs +14 -0
  91. package/ui/logger.mjs +9 -0
@@ -0,0 +1,556 @@
1
+ import { PACKAGE_VERSION } from "../contracts/doc-versions.mjs";
2
+
3
+ export const docsEn = {
4
+ index: `# Git Page Docs
5
+
6
+ Git Page Docs is a multilingual documentation runtime for repositories that ship a \`gitpagedocs/\` folder.
7
+
8
+ ## What this project delivers
9
+
10
+ - Multilingual markdown rendering (\`en\`, \`pt\`, \`es\`)
11
+ - Version-aware docs routing (\`/v/:version\`)
12
+ - Theme system with JSON templates
13
+ - Local and GitHub Pages execution modes
14
+ - Optional repository search + remote rendering
15
+
16
+ ## Folder contract
17
+
18
+ The runtime expects this structure:
19
+
20
+ - \`gitpagedocs/config.json\`
21
+ - \`gitpagedocs/docs/<lang>/*.md\`
22
+ - \`gitpagedocs/docs/versions/<version>/config.json\`
23
+ - \`gitpagedocs/docs/versions/<version>/<lang>/*.md\`
24
+ - \`gitpagelayouts/layoutsConfig.json\` (only with \`--layoutconfig\`)
25
+ - \`gitpagelayouts/templates/*.json\` (only with \`--layoutconfig\`)
26
+
27
+ ## Quick navigation
28
+
29
+ - Open **Getting Started** for local setup.
30
+ - Open **Configuration** for full \`config.json\` explanation.
31
+ - Open **Deployment** for local, server, and GitHub Pages behavior.
32
+ - Open **Architecture** for code map and data flow.
33
+ - Open **Themes and layouts** for template authoring details.
34
+ - Open **Authorized routes** for key, roles, and external auth setup.
35
+ - Open **FAQ** for troubleshooting.
36
+ `,
37
+ gettingStarted: `# Getting Started
38
+
39
+ This guide configures your repository from zero to running docs.
40
+
41
+ ## Prerequisites
42
+
43
+ - Node.js 20+
44
+ - npm 10+
45
+
46
+ ## Install and generate
47
+
48
+ 1. Install package:
49
+ - \`npm install @gitpagedocs/cli\`
50
+ 2. Generate docs config and versions:
51
+ - \`npx @gitpagedocs/cli\`
52
+ 3. Optional: generate local layouts/templates:
53
+ - \`npx @gitpagedocs/cli --layoutconfig\`
54
+
55
+ ## Local run
56
+
57
+ 1. Development:
58
+ - \`npm run dev\`
59
+ 2. Production locally:
60
+ - \`npm run build\`
61
+ - \`npm start\`
62
+
63
+ ## CLI behavior
64
+
65
+ \`npx @gitpagedocs/cli\` generates only artifacts in \`gitpagedocs/\`:
66
+
67
+ - JSON + markdown docs assets
68
+ - No \`index.html\`
69
+ - No \`index.js\`
70
+ - No install command execution
71
+
72
+ ## Repository search mode
73
+
74
+ Local repository search is controlled by:
75
+
76
+ - \`GITPAGEDOCS_REPOSITORY_SEARCH=true\`
77
+ - \`GITPAGEDOCS_REPOSITORY_SEARCH=false\`
78
+
79
+ On GitHub Pages builds (\`GITHUB_ACTIONS=true\`), repository-search home is enabled.
80
+ `,
81
+ projectOverview: `# Project Overview
82
+
83
+ Git Page Docs is a **pnpm + turborepo monorepo** that turns a repository's \`gitpagedocs/\` folder into a multilingual, versioned documentation site — with an integrated AI assistant and a Model Context Protocol (MCP) server.
84
+
85
+ ## Monorepo packages
86
+
87
+ - **frontend/** — Next.js 15 (App Router, React 19) documentation viewer, static-exported for GitHub Pages.
88
+ - **cli/** — the published \`@gitpagedocs/cli\` npm package (\`npm install -g @gitpagedocs/cli\`): scaffolds the docs contract, generates docs with AI, configures Pages, and runs the MCP server.
89
+ - **tools/** — \`@gitpagedocs/tools\`, the shared business-logic core: the 14-provider AI system, the encrypted credential vault, the config loader, caches, and the logger.
90
+ - **mcp/** — \`@gitpagedocs/mcp\`, a Model Context Protocol server (20 tools + 7 resources).
91
+ - **gitpagedocs/** — the user contract: \`config.json\`, versioned docs, and layouts.
92
+
93
+ ## Stack
94
+
95
+ - Next.js 15 (App Router) + React 19 + TypeScript; static export for GitHub Pages
96
+ - gray-matter + marked for Markdown; react-icons
97
+ - pnpm workspaces + turborepo; Vitest + Playwright; ESLint
98
+
99
+ ## Highlights
100
+
101
+ - Multilingual (\`en\`, \`pt\`, \`es\`) and version-aware routing (\`/v/:version\`)
102
+ - 14-provider AI system (OpenAI, Anthropic, Gemini, Ollama, Mistral, DeepSeek, Cohere, Groq, xAI, and more) with streaming
103
+ - AI API keys stored **encrypted at rest** (AES-256-GCM) behind a local password gate — never plaintext
104
+ - In-docs **AI chat drawer** plus a dedicated **\`/ai\` console**
105
+ - 36-theme layout system; local and GitHub Pages execution modes
106
+ `,
107
+ functionalities: `# Functionalities
108
+
109
+ Complete reference of CLI options, configuration keys, and runtime features.
110
+
111
+ ## CLI commands
112
+
113
+ | Command | Description |
114
+ |---------|--------------|
115
+ | \`gitpagedocs\` | Generate config and docs in \`gitpagedocs/\` |
116
+ | \`gitpagedocs --layoutconfig\` | Also generate local layouts/templates in \`gitpagelayouts/\` |
117
+ | \`gitpagedocs --home\` | Standalone distribution (\`gitpagedocshome/\`) |
118
+ | \`gitpagedocs --push --owner X --repo Y\` | Setup workflow, commit, push |
119
+ | \`gitpagedocs --interactive\` / \`-i\` | Interactive mode with prompts (the default in a terminal) |
120
+ | \`gitpagedocs --no-interactive\` / \`--yes\` / \`-y\` | Never prompt; use flags and defaults |
121
+ | \`gitpagedocs ai\` | Interactive AI documentation generator |
122
+ | \`gitpagedocs provider [id]\` / \`models [provider]\` | List AI providers / catalog models |
123
+ | \`gitpagedocs document[:repo\\|:file\\|:folder]\` | Generate documentation with AI |
124
+ | \`gitpagedocs deploy\` / \`pages [actions\\|deploy]\` | Configure GitHub Pages via Actions + push |
125
+ | \`gitpagedocs docs\` | Refresh README/CONTRIBUTING/SECURITY managed regions |
126
+ | \`gitpagedocs doctor\` / \`version\` / \`update\` | Diagnostics / version / registry update check |
127
+ | \`gitpagedocs mcp start\` | Start the MCP server over stdio |
128
+
129
+ Install globally with \`npm install -g @gitpagedocs/cli\`, or run one-off with \`npx @gitpagedocs/cli\`.
130
+
131
+ ## CLI options
132
+
133
+ | Option | Description |
134
+ |--------|-------------|
135
+ | \`--owner <user>\` | GitHub owner |
136
+ | \`--repo <repo>\` | GitHub repository |
137
+ | \`--path <subpath>\` | Docs subpath (e.g. \`docs\`); without it, base path = repo name for correct CSS/JS on project sites |
138
+ | \`--output <dir>\` | Output directory (default: \`gitpagedocs\`) |
139
+ | \`--search true|false\` | Enable/disable repository search (\`--home\`) |
140
+ | \`--layoutconfig\` | Generate local layouts in \`gitpagelayouts/\` |
141
+ | \`--layouts-dir <dir>\` | Folder for local layouts (default: \`gitpagelayouts\`) |
142
+ | \`--push\` | Create workflow, commit artifacts, push |
143
+ | \`--home\` | Generate \`gitpagedocshome/\` (static + .env + Dockerfile) |
144
+
145
+ ## Generated output
146
+
147
+ - \`gitpagedocs/config.json\` – root config
148
+ - \`gitpagedocs/icon.svg\` – default icon
149
+ - \`gitpagedocs/docs/versions/<ver>/config.json\` – per-version routes
150
+ - \`gitpagedocs/docs/versions/<ver>/{en,pt,es}/*.md\` – markdown docs
151
+ - \`gitpagelayouts/\` – only with \`--layoutconfig\` (folder configurable with \`--layouts-dir\`)
152
+
153
+ ## Content types
154
+
155
+ | Type | Config key | Description |
156
+ |------|------------|-------------|
157
+ | Markdown | \`routes-md\` | .md files with \`path\` per language |
158
+ | HTML | \`routes-html\` | local \`path\` or external \`url\` |
159
+ | Video | \`routes-video\` | \`video.pathVideo\`, \`video.videoType\` |
160
+ | Audio | \`routes-audio\` | \`audio.pathAudio\`, \`audio.audioType\` |
161
+
162
+ ## Source code viewer
163
+
164
+ The version config can render a **Source code** container through \`routes-source-viewer\` and \`menus-header-source-viewer\`. The viewer reads GitHub repository trees at runtime and applies the current documentation theme.
165
+
166
+ - Repository tree from \`source-viewer-path\`; branch defaults to \`main\`
167
+ - Folder navigation and file filtering
168
+ - GitHub-style directory listing
169
+ - Code rendering with line numbers
170
+ - Markdown preview/code toggle, including \`README.md\`
171
+ - Collapsible folders in the sidebar
172
+
173
+ ## Config keys (site)
174
+
175
+ - \`name\`, \`defaultLanguage\`
176
+ - \`docsVersion\`, \`rendering\`, \`ThemeDefault\`, \`ThemeModeDefault\`
177
+ - \`ProjectLink\`, \`layoutsConfigPathOficial\`, \`layoutsConfigPath\`
178
+ - Languages: \`site.languages\` (enable/disable each one); UI strings: \`gitpagedocs/langs/<lang>.json\`
179
+
180
+ ## Environment variables
181
+
182
+ - \`GITPAGEDOCS_REPOSITORY_SEARCH\` – repository search (local)
183
+ - \`GITHUB_ACTIONS\` – GitHub Pages build mode
184
+
185
+ ## AI assistant
186
+
187
+ The docs ship an AI assistant in two surfaces: an in-docs **chat drawer** (the AI chat button in the sidebar, enabled via \`site.AiChatEnabled\`) and a dedicated **\`/ai\` console** page.
188
+
189
+ - **14 providers** via one shared core: OpenAI, Anthropic, Gemini, OpenRouter, Ollama, Azure OpenAI, Mistral, DeepSeek, Cohere, Groq, xAI, Together, Fireworks, Perplexity.
190
+ - **Model selection** — pick from each provider's catalog (\`gitpagedocs models <provider>\`) or type a custom id.
191
+ - **Encrypted at rest** — your API key is sealed with AES-256-GCM behind a **local password** (one unlock per session) and is never stored in plaintext or logged. A legacy plaintext key is migrated and wiped on first unlock.
192
+ - **AI documentation generation** — \`gitpagedocs ai\` scans chosen paths and writes multilingual markdown (pt/en/es); reusable via \`.gitpagedocsconfig\`.
193
+
194
+ ## MCP server
195
+
196
+ \`gitpagedocs mcp start\` runs a Model Context Protocol server (stdio) exposing **20 tools** (filesystem, AI, doc generation/analysis) and **7 resources** (\`project://structure|docs|config|repository|readme|ai/providers|ai/models\`) for editors and AI agents.
197
+ `,
198
+ githubIssuesProjects: `# GitHub Issues and Projects
199
+
200
+ Learn how to use GitHub Issues and Projects to manage your work.
201
+
202
+ ## Issues
203
+
204
+ - Track bugs, features, and tasks
205
+ - Assignees, labels, milestones
206
+ - Discussions and linked PRs
207
+
208
+ ## Projects
209
+
210
+ - Kanban boards
211
+ - Tables and roadmaps
212
+ - Custom fields and automation
213
+ `,
214
+ gitIntroduction: `# Introduction to Git
215
+
216
+ Basic Git concepts for beginners.
217
+
218
+ ## Key concepts
219
+
220
+ - **Repository**: A project folder tracked by Git
221
+ - **Commit**: A snapshot of changes
222
+ - **Branch**: Alternative line of development
223
+ - **Remote**: Shared repository (e.g. on GitHub)
224
+
225
+ ## Common commands
226
+
227
+ - \`git init\` - Initialize a repo
228
+ - \`git add\` - Stage changes
229
+ - \`git commit\` - Create a snapshot
230
+ - \`git push\` - Send to remote
231
+ `,
232
+ authorizedRoutes: `# Authorized Routes
233
+
234
+ Protect routes by access key, required roles, and external authentication providers.
235
+
236
+ ## Version config location
237
+
238
+ Configure this at:
239
+
240
+ - \`gitpagedocs/docs/versions/<version>/config.json\`
241
+
242
+ ## Global auth section
243
+
244
+ Use top-level \`auth\` in version config:
245
+
246
+ - \`accessKeys\`: map of key ids to expected secrets
247
+ - \`rolesStorageKey\`: localStorage key for role bootstrap
248
+ - \`providers\`: external providers list (\`authjs\`, \`clerk\`, \`firebase\`, \`jwt\`)
249
+
250
+ ## Route-level authorization
251
+
252
+ Inside each route (\`routes-md\`, \`routes-html\`, \`routes-video\`):
253
+
254
+ - \`authorization.accessKeyId\`
255
+ - \`authorization.requiredRoles\`
256
+ - \`authorization.requireExternalAuth\`
257
+ - \`authorization.allowedProviders\`
258
+
259
+ ## Phases
260
+
261
+ ### Phase A - Access key
262
+
263
+ Set \`authorization.accessKeyId\` and define that key in \`auth.accessKeys\`.
264
+
265
+ ### Phase B - Roles
266
+
267
+ Set \`authorization.requiredRoles\` with one or more roles.
268
+
269
+ Roles can come from:
270
+
271
+ - query param \`?authRoles=admin,maintainer\`
272
+ - localStorage (\`rolesStorageKey\`)
273
+ - external provider claims
274
+
275
+ ### Phase C - External providers
276
+
277
+ Set \`authorization.requireExternalAuth=true\` and optionally \`allowedProviders\`.
278
+
279
+ Supported adapters:
280
+
281
+ - Auth.js (\`type: "authjs"\`)
282
+ - Clerk (\`type: "clerk"\`)
283
+ - Firebase Auth (\`type: "firebase"\`)
284
+ - Custom JWT (\`type: "jwt"\`)
285
+
286
+ ## Example
287
+
288
+ \`\`\`json
289
+ {
290
+ "auth": {
291
+ "accessKeys": {
292
+ "docs-key": "open-gitpagedocs-docs"
293
+ },
294
+ "providers": [
295
+ { "type": "authjs", "enabled": true, "sessionEndpoint": "/api/auth/session" },
296
+ { "type": "jwt", "enabled": true, "tokenStorageKey": "git-page-docs:jwt-token" }
297
+ ]
298
+ },
299
+ "routes-md": [
300
+ {
301
+ "id": 6,
302
+ "path": {
303
+ "en": "gitpagedocs/docs/versions/${PACKAGE_VERSION}/en/authorized-routes.md",
304
+ "pt": "gitpagedocs/docs/versions/${PACKAGE_VERSION}/pt/authorized-routes.md",
305
+ "es": "gitpagedocs/docs/versions/${PACKAGE_VERSION}/es/authorized-routes.md"
306
+ },
307
+ "authorization": {
308
+ "accessKeyId": "docs-key",
309
+ "requiredRoles": ["maintainer"],
310
+ "requireExternalAuth": true,
311
+ "allowedProviders": ["authjs", "jwt"]
312
+ }
313
+ }
314
+ ]
315
+ }
316
+ \`\`\`
317
+ `,
318
+ configuration: `# Configuration
319
+
320
+ Runtime configuration lives in \`gitpagedocs/config.json\`. UI text lives next to it, one file per language.
321
+
322
+ ## Languages (\`site.languages\` + \`langs/\`)
323
+
324
+ - \`site.languages\` in \`gitpagedocs/config.json\` switches each language on (\`true\`) or off (\`false\`), in menu order: \`{ "languages": { "en": true, "pt": true, "es": false } }\`. A language set to \`false\` disappears from the language selector and its strings are not loaded, even when its docs exist.
325
+ - \`gitpagedocs/langs/<lang>.json\` holds that language's strings: \`langmenu\` (header, search, source viewer, audio player, AI chat and docs-access labels) and \`translations\` (\`notFound\`, \`navigation\`, \`footer\`).
326
+ - To add a language, create \`langs/<lang>.json\` and add \`"<lang>": true\` to \`site.languages\`. There is no \`langs.json\` any more: a manifest left by release 1.1.68 is still read by configs without \`site.languages\`, and the generator removes it.
327
+ - Older \`config.json\` files that still inline \`site.langmenu\` / \`translations\` keep working; when both exist, the \`langs/\` files win and any missing key is backfilled from the current release.
328
+
329
+ ## \`site\` section
330
+
331
+ Important keys:
332
+
333
+ - \`name\`
334
+ - \`defaultLanguage\`
335
+ - \`docsVersion\`
336
+ - \`rendering\`
337
+ - \`ThemeDefault\`
338
+ - \`ThemeModeDefault\`
339
+ - \`ProjectLink\`
340
+
341
+ ## Layout source keys
342
+
343
+ - \`layoutsConfigPathOficial\`
344
+ - \`layoutsConfigPathOficialUrl\`
345
+ - \`layoutsConfigPathTemplatesOficial\`
346
+ - \`layoutsConfigPath\`
347
+ - \`layoutsConfigPathTemplates\`
348
+
349
+ Behavior:
350
+
351
+ - If \`layoutsConfigPathOficial=true\`, runtime prefers official layout/template sources.
352
+ - If \`layoutsConfigPathOficial=false\`, runtime prefers repository-local/custom layout sources.
353
+
354
+ ## \`VersionControl\` section
355
+
356
+ \`VersionControl.versions\` defines:
357
+
358
+ - \`id\`
359
+ - \`path\`
360
+ - optional metadata links (\`ProjectLink\`, \`branch\`, \`release\`, \`commit\`)
361
+ - optional source viewer metadata (\`source-viewer\`, \`source-viewer-path\`)
362
+
363
+ ## Navigation
364
+
365
+ - \`routes\`: markdown paths per language (legacy)
366
+ - \`menus-header\`: hierarchical menu model
367
+ - \`translations\`: UI labels
368
+
369
+ ## Authorization (version config)
370
+
371
+ - \`auth\`: global authorization runtime settings for that version
372
+ - \`auth.accessKeys\`: key map used by \`authorization.accessKeyId\`
373
+ - \`auth.rolesStorageKey\`: localStorage key for role bootstrap
374
+ - \`auth.providers\`: provider adapters (\`authjs\`, \`clerk\`, \`firebase\`, \`jwt\`)
375
+
376
+ ## Content types (version config)
377
+
378
+ Version configs support multiple content types:
379
+
380
+ - \`routes-md\`: Markdown routes with optional \`title\`, \`description\` (centered via \`titlePosition\`, \`descriptionPosition\`)
381
+ - \`routes-source-viewer\`: Source viewer containers with \`source-viewer: true\` and \`source-viewer-path\`
382
+ - \`routes-html\`: HTML page paths per language
383
+ - \`routes-video\`: Video config with \`video.videoType\` (youtube, vimeo, mp4, etc.) and \`video.pathVideo\`
384
+ - \`routes-audio\`: Audio config with \`audio.audioType\` (youtube, mp3, etc.) and \`audio.pathAudio\`
385
+ - \`authorization\` (md/html/video): route guard by access key, roles, and external auth
386
+ - \`menus-header-md\`, \`menus-header-source-viewer\`, \`menus-header-html\`, \`menus-header-video\`, \`menus-header-audio\`: menus per type
387
+ - \`hierarchyPage\`: container order on page \`{ md: 0, "source-viewer": 1, html: 2, video: 3, audio: 4 }\`
388
+ - \`hierarchyMenu\`: menu section order \`{ md: 0, "source-viewer": 1, html: 2, video: 3, audio: 4 }\`
389
+
390
+ Each route can include \`title\`, \`description\` (per language), \`titleCss\`, \`titlePosition: "center"\`, \`descriptionPosition: "center"\`, \`titleIsVisible\`, \`descriptionIsVisible\`.
391
+
392
+ ## Route-level variables (blockLink, container, url, browseAll)
393
+
394
+ Per-route options for \`routes-md\`, \`routes-html\`, \`routes-video\`, and \`routes-audio\`:
395
+
396
+ - **\`blockLink\`** (default: true) – For HTML: if true, links open in a new tab (\`target="_blank"\`); if false, links open in the same context.
397
+ - **\`container\`** – \`"full"\` = auto-extend height; number (e.g. \`500\`) = fixed height in px with overflow auto. Applies to md, html, video, and audio containers.
398
+ - **\`url\`** – For \`routes-html\` only: \`Record<LanguageCode, string>\` with external URLs. When set, the iframe uses \`src={url}\` instead of local HTML via \`srcDoc\`. Routes with \`url\` do not generate local HTML files.
399
+ - **\`browseAll\`** (default: false) – If true, the container shows Previous/Next buttons to browse all items of that type without changing the page.
400
+
401
+ ## Content types: path vs url (HTML)
402
+
403
+ - **Markdown (\`routes-md\`)**: always uses \`path\` pointing to local \`.md\` files.
404
+ - **HTML (\`routes-html\`)**: uses \`path\` for local HTML files (no \`.html\` extension in config) or \`url\` for external URLs. When \`url\` is set, the iframe loads the external page; no local file is generated.
405
+ - **Video (\`routes-video\`)**: uses \`video.pathVideo\` and \`video.videoType\` (youtube, vimeo, mp4, etc.).
406
+ - **Audio (\`routes-audio\`)**: uses \`audio.pathAudio\` and \`audio.audioType\` (youtube, mp3, etc.). No autoplay by default.
407
+
408
+ ## Environment variables
409
+
410
+ - \`GITPAGEDOCS_REPOSITORY_SEARCH\`: enable/disable remote repository search in local runtime
411
+ - \`GITHUB_ACTIONS\`: enables GitHub Pages specific runtime behavior
412
+ `,
413
+ deployment: `# Deployment
414
+
415
+ Git Page Docs supports two usage models:
416
+
417
+ 1. Use the official viewer site
418
+ 2. Self-host your own GitHub Pages runtime
419
+
420
+ ## Official viewer site
421
+
422
+ Use:
423
+
424
+ - \`https://vidigal-code.github.io/git-page-docs/\`
425
+
426
+ Provide owner + repository to load docs from repositories that contain \`gitpagedocs/\`.
427
+
428
+ ## Self-hosted GitHub Pages
429
+
430
+ 1. Generate docs:
431
+ - \`npx @gitpagedocs/cli\`
432
+ - or \`npx @gitpagedocs/cli --layoutconfig\` for local templates
433
+ 2. Set \`site.rendering\` in \`gitpagedocs/config.json\`:
434
+ - \`https://<your-user>.github.io/<your-repo>/\`
435
+ 3. Build and validate:
436
+ - \`npm run lint\`
437
+ - \`npm run build\`
438
+ 4. Deploy with GitHub Pages workflow.
439
+
440
+ When \`GITHUB_ACTIONS=true\`, runtime applies GitHub Pages behavior.
441
+
442
+ ## npm publish flows
443
+
444
+ Recommended: GitHub Release + CI publish.
445
+
446
+ Manual fallback:
447
+
448
+ 1. \`npm whoami\`
449
+ 2. \`npm run lint\`
450
+ 3. \`npm run build\`
451
+ 4. \`npm pack --ignore-scripts\`
452
+ 5. \`npm version patch\`
453
+ 6. \`npm publish --access public\`
454
+ `,
455
+ architecture: `# Architecture
456
+
457
+ A pnpm + turborepo monorepo where all business logic lives in one shared core (\`tools/\`); the frontend, CLI, and MCP server are thin consumers of it.
458
+
459
+ ## Packages
460
+
461
+ - **frontend/** — Next.js viewer (Feature-Sliced: \`app / widgets / features / entities / shared\`); static export.
462
+ - **cli/** — the published \`gitpagedocs\` bin (hexagonal: \`presentation / application / domain / infrastructure\`) + \`cli/ai/\` (the AI documentation CLI).
463
+ - **tools/** — \`@gitpagedocs/tools\`: \`ai/ security/ crypto/ cache/ config/ logger/ errors/ filesystem/ documentation/ i18n/ ports/\`.
464
+ - **mcp/** — \`@gitpagedocs/mcp\`: MCP tools + resources delegating to \`tools/\`.
465
+
466
+ ## Main runtime modules (frontend)
467
+
468
+ - \`frontend/src/app/[[...repo]]/page.tsx\` — route parser, static params, shell selection (docs vs repository-search).
469
+ - \`frontend/src/entities/docs/api/load-docs-data.ts\` — local/remote config loading, version resolution, markdown parse, layouts + themes.
470
+ - \`frontend/src/widgets/docs-shell/docs-shell.tsx\` — UI rendering, language/version/theme state, URL sync, AI chat drawer mount.
471
+
472
+ ## Security: encrypted AI credentials
473
+
474
+ The \`/ai\` console and the chat drawer gate access behind a local password that derives (PBKDF2) an AES-256-GCM key; keys live encrypted in \`localStorage\` and are decrypted only for the session (\`@gitpagedocs/tools/security\`).
475
+
476
+ ## Data flow
477
+
478
+ 1. Request route arrives (\`/owner/repo/v/x.y.z\` or local equivalent)
479
+ 2. Config is resolved (local or remote repo)
480
+ 3. Version config overrides base routes/menus
481
+ 4. Markdown is loaded and converted to HTML
482
+ 5. Layout template is resolved and CSS vars applied
483
+ 6. Shell renders content + controls
484
+
485
+ ## Reliability points
486
+
487
+ - fallback strategy for layout/template loading
488
+ - resilient markdown loading per language
489
+ - localStorage sync for user language/version/theme
490
+ `,
491
+ themes: `# Themes and Layouts
492
+
493
+ Themes are JSON templates mapped by \`layoutsConfig.json\`.
494
+
495
+ ## Strategy options
496
+
497
+ - Default mode (\`npx @gitpagedocs/cli\`): use official layouts/templates from the upstream repository.
498
+ - Local mode (\`npx @gitpagedocs/cli --layoutconfig\`): generate and use local templates from your repository.
499
+
500
+ ## Local layout files
501
+
502
+ - \`gitpagelayouts/layoutsConfig.json\`
503
+ - \`gitpagelayouts/layoutsFallbackConfig.json\`
504
+ - \`gitpagelayouts/templates/*.json\`
505
+
506
+ The legacy \`gitpagedocs/layouts/\` location is no longer generated. It is still read by the viewer, and the CLI offers to move it into the layouts home - only after you confirm.
507
+
508
+ ## Template model
509
+
510
+ Each template usually includes:
511
+
512
+ - \`id\`, \`name\`, \`author\`, \`version\`
513
+ - \`mode\` + dark/light pairing metadata
514
+ - \`colors\`
515
+ - \`typography\`
516
+ - \`components\`
517
+ - \`animations\`
518
+
519
+ ## Runtime behavior
520
+
521
+ - Active theme is resolved from config/user selection.
522
+ - Light/dark toggle resolves paired theme via reference.
523
+ - CSS variables are generated from template tokens.
524
+ - Runtime includes fallback behavior if a source is unavailable.
525
+ `,
526
+ faq: `# FAQ
527
+
528
+ ## Why are remote repositories not opening locally?
529
+
530
+ Check:
531
+
532
+ - \`GITPAGEDOCS_REPOSITORY_SEARCH=true\` in \`.env\`
533
+ - target repo contains \`gitpagedocs/config.json\`
534
+ - target repo markdown paths match its routes config
535
+
536
+ ## Why does a version path return wrong content?
537
+
538
+ Check:
539
+
540
+ - \`VersionControl.versions[*].path\` in \`gitpagedocs/config.json\`
541
+ - that version config has valid \`routes\` and \`menus-header\`
542
+ - markdown files exist for each language
543
+
544
+ ## Why does theme selection not apply correctly?
545
+
546
+ Check:
547
+
548
+ - \`layoutsConfig.json\` references valid template files
549
+ - template ids are unique
550
+ - selected theme exists in loaded themes map
551
+
552
+ ## Why can GitHub Pages behave differently from local?
553
+
554
+ Because GitHub Pages build mode enables repository-search home and static-export specific behavior.
555
+ `,
556
+ };