@gitpagedocs/cli 0.0.7 → 0.0.9

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 (15) hide show
  1. package/builders/route-builders.mjs +65 -74
  2. package/builders/version-config-builder.mjs +57 -16
  3. package/content/assets/gitpagedocs-project-guide.pdf +245 -0
  4. package/content/docs-en.mjs +652 -99
  5. package/content/docs-es.mjs +656 -78
  6. package/content/docs-pt.mjs +656 -78
  7. package/contracts/doc-versions.mjs +1 -1
  8. package/contracts/index.mjs +1 -0
  9. package/data/default-site-config.mjs +39 -0
  10. package/data/i18n-langmenu.mjs +81 -0
  11. package/data/path-mappings.mjs +13 -0
  12. package/data/route-metas.mjs +60 -1
  13. package/package.json +3 -3
  14. package/runtime/doc-path-resolver.mjs +22 -13
  15. package/runtime/output.mjs +16 -1
package/content/docs-en.mjs CHANGED
@@ -1,6 +1,84 @@
1
1
  import { PACKAGE_VERSION } from "../contracts/doc-versions.mjs";
2
2
 
3
3
  export const docsEn = {
4
+ pdf: `# PDF documents
5
+
6
+ PDF is a first-class content type alongside Markdown, HTML, source code, video and audio. The viewer uses the browser's native PDF preview. Download and open-in-new-tab actions remain independently configurable.
7
+
8
+ ## Included English project guide
9
+
10
+ The scaffold includes [GitPageDocs project guide (PDF, English)](https://github.com/Vidigal-code/git-page-docs/blob/main/cli/content/assets/gitpagedocs-project-guide.pdf). It explains the project, packages, configuration, icons, focus mode, narration, CLI, MCP and deployment. The PDF is in English; the reference page is translated into English, Portuguese and Spanish.
11
+
12
+ The CLI copies the bundled PDF bytes into \`gitpagedocs/docs/versions/<version>/en/gitpagedocs-project-guide.pdf\`. All three language paths in the example point to this English file. To provide translations, add the translated PDFs and change each language path.
13
+
14
+ ## Site defaults
15
+
16
+ Add this block inside \`site\` in \`gitpagedocs/config.json\`:
17
+
18
+ \`\`\`json
19
+ {
20
+ "pdf": {
21
+ "enabled": true,
22
+ "previewEnabled": true,
23
+ "downloadEnabled": true,
24
+ "openInNewTabEnabled": true
25
+ }
26
+ }
27
+ \`\`\`
28
+
29
+ \`enabled\` is the master switch for PDF content. The other fields control the preview, download button and new-tab link. Every field defaults to \`true\` when omitted, including older configurations.
30
+
31
+ Action precedence is \`route.pdf.<flag>\` > \`site.pdf.<flag>\` > \`true\`. An explicit route \`true\` enables that action even when its site default is \`false\`; \`site.pdf.enabled: false\` still disables PDF content everywhere. A missing path for the selected language makes the PDF unavailable; there is no automatic language fallback.
32
+
33
+ ## Route and menu example
34
+
35
+ In \`gitpagedocs/docs/versions/0.0.9/config.json\`, keep route and menu arrays at the top level:
36
+
37
+ \`\`\`json
38
+ {
39
+ "routes-pdf": [{
40
+ "id": 23,
41
+ "title": { "en": "Project guide (English)", "pt": "Guia do projeto (inglês)", "es": "Guía del proyecto (inglés)" },
42
+ "pdf": {
43
+ "pathPdf": {
44
+ "en": "gitpagedocs/docs/versions/0.0.9/en/gitpagedocs-project-guide.pdf",
45
+ "pt": "gitpagedocs/docs/versions/0.0.9/en/gitpagedocs-project-guide.pdf",
46
+ "es": "gitpagedocs/docs/versions/0.0.9/en/gitpagedocs-project-guide.pdf"
47
+ },
48
+ "previewEnabled": true,
49
+ "downloadEnabled": true,
50
+ "openInNewTabEnabled": true
51
+ }
52
+ }],
53
+ "menus-header-pdf": [{
54
+ "id": 23,
55
+ "en": { "title": "Project guide (English)", "path-click": "page:23" },
56
+ "pt": { "title": "Guia do projeto (inglês)", "path-click": "page:23" },
57
+ "es": { "title": "Guía del proyecto (inglés)", "path-click": "page:23" }
58
+ }]
59
+ }
60
+ \`\`\`
61
+
62
+ The \`pdf.pathPdf\` map selects the file for the current language. Use \`page:<id>\` in PDF menu destinations. The same recursive \`submenus\` structure used by other menus is supported. The scaffold reserves ID 23 for the PDF example and ID 24 for this Markdown reference; use unique IDs for additional pages.
63
+
64
+ The optional route flags live inside \`pdf\`. Shared presentation, \`container\`, \`RouteGuide\` and authorization options remain route-level fields. \`routeDefaults\` also applies to PDF routes. Add \`"pdf": 5\` to \`hierarchyPage\` and \`hierarchyMenu\` to position PDFs after audio; change the order values to suit your site.
65
+
66
+ ## Files and deployment
67
+
68
+ Repository-root paths beginning with \`gitpagedocs/\` are copied into the viewer's public assets when Next.js starts or builds. The URL respects the configured deployment subpath on GitHub Pages. Keep the PDF tracked in Git and publish it with the generated documentation. Assets outside \`gitpagedocs/\` must already be in the viewer's \`frontend/public/\` directory or be reachable through an HTTP(S) URL.
69
+
70
+ Use the binary PDF URL, not an HTML repository preview URL. For remote repositories, the configured path resolves against that repository. Both preview and download fetch the file bytes, so an external server must allow CORS for both operations. The viewer validates the PDF signature and creates a temporary \`application/pdf\` Blob URL for the native browser preview; it releases that URL when the document changes or closes. The origin server's framing policy and MIME/disposition headers do not control this Blob preview.
71
+
72
+ The new-tab link opens the original URL directly. Its behavior depends on the browser and the server's \`Content-Type\` and \`Content-Disposition\`; a raw repository URL can download instead of displaying inline. This direct link remains available when preview or download fails, unless its action is disabled.
73
+
74
+ ## Reading and troubleshooting
75
+
76
+ - Native PDF controls, keyboard support, zoom and page navigation depend on the browser's PDF viewer. Some mobile browsers open or download the file instead of embedding it.
77
+ - Preview does not convert the PDF to Markdown. Markdown focus mode, section navigation, copy-as-Markdown and narration operate on Markdown documents, not the embedded PDF.
78
+ - Disabling preview can keep the download and new-tab actions available. Turning off every PDF action leaves no interactive PDF control.
79
+ - A disabled button is not access control. Publicly hosted PDFs remain downloadable by URL. Use protected hosting for confidential documents.
80
+ - If a preview is blank, use the new-tab action, verify that the path returns a PDF, and check the host's response headers. If download fails, the page reports an error instead of silently succeeding.
81
+ `,
4
82
  index: `# Git Page Docs
5
83
 
6
84
  Git Page Docs is a multilingual documentation runtime for repositories that ship a \`gitpagedocs/\` folder.
@@ -33,50 +111,63 @@ The runtime expects this structure:
33
111
  - Open **Themes and layouts** for template authoring details.
34
112
  - Open **Authorized routes** for key, roles, and external auth setup.
35
113
  - Open **FAQ** for troubleshooting.
114
+
115
+ ## Detailed references
116
+
117
+ - **CLI reference**: installation, every command and compatibility flags.
118
+ - **MCP server**: client setup, all 20 tools, 7 resources and provider configuration.
119
+ - **Navigation and nested menus**: recursive trees, URLs and breadcrumb overrides.
120
+ - **Focus mode**: copy/download Markdown and section/document navigation.
121
+ - **Accessibility and narration**: browser voices, controls and media interaction.
122
+ - **PDF documents**: native previews, download/new-tab controls and the included English guide.
36
123
  `,
37
124
  gettingStarted: `# Getting Started
38
125
 
39
- This guide configures your repository from zero to running docs.
126
+ Git Page Docs separates the documentation files from the viewer. Install the CLI to create the files; use the official viewer, GitHub Pages or a checkout of the runtime to display them.
40
127
 
41
- ## Prerequisites
128
+ ## Requirements and installation
42
129
 
43
- - Node.js 20+
44
- - npm 10+
130
+ Use Node.js 20 or newer. Git is needed for publishing; GitHub CLI is needed when asking the CLI to configure Pages automatically.
45
131
 
46
- ## Install and generate
132
+ \`\`\`bash
133
+ npm install --save-dev @gitpagedocs/cli
134
+ npx gitpagedocs --no-interactive --owner YOUR_USER --repo YOUR_REPOSITORY
135
+ \`\`\`
136
+
137
+ For a one-off run, use \`npx --yes @gitpagedocs/cli --no-interactive --owner YOUR_USER --repo YOUR_REPOSITORY\`. For a global command, use \`npm install -g @gitpagedocs/cli\`, then \`gitpagedocs\`. Run from the repository root.
47
138
 
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\`
139
+ ## Generated contract
54
140
 
55
- ## Local run
141
+ - \`gitpagedocs/config.json\`: site options and version references.
142
+ - \`gitpagedocs/langs/{en,pt,es}.json\`: UI strings.
143
+ - \`gitpagedocs/docs/versions/<version>/config.json\`: routes and menus.
144
+ - \`gitpagedocs/docs/versions/<version>/{en,pt,es}/*.md\`: page content; filenames stay in English across languages.
145
+ - \`gitpagedocs/icon.svg\`: site icon.
146
+ - \`--layoutconfig\` additionally writes \`gitpagelayouts/\`; use \`--layouts-dir\` to change that directory.
56
147
 
57
- 1. Development:
58
- - \`npm run dev\`
59
- 2. Production locally:
60
- - \`npm run build\`
61
- - \`npm start\`
148
+ The generator writes configuration and content; it does not install a Next.js application into your repository. Rerunning it writes the scaffold files again: review the Git diff before keeping changes to hand-edited documentation.
62
149
 
63
- ## CLI behavior
150
+ ## Read and publish
64
151
 
65
- \`npx @gitpagedocs/cli\` generates only artifacts in \`gitpagedocs/\`:
152
+ Commit and push the generated folder, then open \`https://vidigal-code.github.io/git-page-docs/YOUR_USER/YOUR_REPOSITORY/\` for a public repository. To publish your own site, authenticate with \`gh auth login\`, then run \`npx gitpagedocs pages deploy --owner YOUR_USER --repo YOUR_REPOSITORY\`. This generates files, commits and pushes; inspect the resulting GitHub Actions run. See Deployment for the subpath and workflow contract.
66
153
 
67
- - JSON + markdown docs assets
68
- - No \`index.html\`
69
- - No \`index.js\`
70
- - No install command execution
154
+ ## Develop the viewer locally
71
155
 
72
- ## Repository search mode
156
+ The following commands belong to a checkout of Git Page Docs, not to a repository containing only generated files:
73
157
 
74
- Local repository search is controlled by:
158
+ \`\`\`bash
159
+ git clone https://github.com/Vidigal-code/git-page-docs.git
160
+ cd git-page-docs
161
+ corepack enable
162
+ pnpm install --frozen-lockfile
163
+ pnpm dev
164
+ \`\`\`
75
165
 
76
- - \`GITPAGEDOCS_REPOSITORY_SEARCH=true\`
77
- - \`GITPAGEDOCS_REPOSITORY_SEARCH=false\`
166
+ The repository pins pnpm in \`packageManager\`. \`pnpm dev\` enables repository search; \`pnpm dev:e2e\` uses the local documentation. For a production build, run \`pnpm build\` and \`pnpm start\`; the start script rebuilds before starting. Use \`PORT=3100\` in the process environment when port 3000 is occupied.
78
167
 
79
- On GitHub Pages builds (\`GITHUB_ACTIONS=true\`), repository-search home is enabled.
168
+ ## Next steps
169
+
170
+ Use Configuration for languages, icons, navigation, focus and narration; Functionalities for CLI and MCP; Themes and layouts for visual tokens; FAQ for diagnostics.
80
171
  `,
81
172
  projectOverview: `# Project Overview
82
173
 
@@ -102,53 +193,15 @@ Git Page Docs is a **pnpm + turborepo monorepo** that turns a repository's \`git
102
193
  - 14-provider AI system (OpenAI, Anthropic, Gemini, Ollama, Mistral, DeepSeek, Cohere, Groq, xAI, and more) with streaming
103
194
  - AI API keys stored **encrypted at rest** (AES-256-GCM) behind a local password gate — never plaintext
104
195
  - In-docs **AI chat drawer** plus a dedicated **\`/ai\` console**
105
- - 36-theme layout system; local and GitHub Pages execution modes
196
+ - 64-theme layout system (dark and light variants); local and GitHub Pages execution modes
106
197
  `,
107
198
  functionalities: `# Functionalities
108
199
 
109
200
  Complete reference of CLI options, configuration keys, and runtime features.
110
201
 
111
- ## CLI commands
202
+ ## Command line
112
203
 
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\`)
204
+ See **CLI reference** for all commands, flags, examples and compatibility behavior. See **MCP server** for editor integration.
152
205
 
153
206
  ## Content types
154
207
 
@@ -158,6 +211,7 @@ Install globally with \`npm install -g @gitpagedocs/cli\`, or run one-off with \
158
211
  | HTML | \`routes-html\` | local \`path\` or external \`url\` |
159
212
  | Video | \`routes-video\` | \`video.pathVideo\`, \`video.videoType\` |
160
213
  | Audio | \`routes-audio\` | \`audio.pathAudio\`, \`audio.audioType\` |
214
+ | PDF | \`routes-pdf\` | \`pdf.pathPdf\` per language; native preview and download |
161
215
 
162
216
  ## Source code viewer
163
217
 
@@ -177,6 +231,12 @@ The version config can render a **Source code** container through \`routes-sourc
177
231
  - \`ProjectLink\`, \`layoutsConfigPathOficial\`, \`layoutsConfigPath\`
178
232
  - Languages: \`site.languages\` (enable/disable each one); UI strings: \`gitpagedocs/langs/<lang>.json\`
179
233
 
234
+ ## Media playback (one sound at a time)
235
+
236
+ \`site.mediaExclusivePlayback\` (default \`true\`): playing a route video pauses the radio and the audio tracks, and playing the radio or an audio track pauses the video. It works with YouTube and Vimeo (through their player APIs), native files (\`mp4\`, \`webm\`, …) and any other embed.
237
+
238
+ To show a video without sound while the radio or an audio track explains it, set \`"muted": true\` in that route's \`video\` object: the video plays only the picture and stays out of the rule. \`"mediaExclusivePlayback": false\` turns the rule off for the whole site.
239
+
180
240
  ## Environment variables
181
241
 
182
242
  - \`GITPAGEDOCS_REPOSITORY_SEARCH\` – repository search (local)
@@ -353,6 +413,37 @@ Behavior:
353
413
  - If \`layoutsConfigPathOficial=true\`, runtime prefers official layout/template sources.
354
414
  - If \`layoutsConfigPathOficial=false\`, runtime prefers repository-local/custom layout sources.
355
415
 
416
+ ## Language, theme and focus controls
417
+
418
+ In \`gitpagedocs/config.json\`, merge these entries into \`site.icons\` to use React Icons for the language selector, theme selector and focus button:
419
+
420
+ \`\`\`json
421
+ {
422
+ "site": {
423
+ "icons": {
424
+ "LanguageSelector": {
425
+ "reactIcon": true, "tag": "FiGlobe", "size": "22px",
426
+ "colorDark": "currentColor", "colorLight": "currentColor"
427
+ },
428
+ "ThemeSelector": {
429
+ "reactIcon": true, "tag": "BsSunFill", "size": "22px",
430
+ "colorDark": "currentColor", "colorLight": "currentColor"
431
+ },
432
+ "FocusMode": {
433
+ "reactIcon": true, "tag": "MdFullscreen", "size": "22px",
434
+ "colorDark": "currentColor", "colorLight": "currentColor"
435
+ },
436
+ "QuickNavigation": {
437
+ "reactIcon": true, "tag": "FiSearch", "size": "22px",
438
+ "colorDark": "currentColor", "colorLight": "currentColor"
439
+ }
440
+ }
441
+ }
442
+ }
443
+ \`\`\`
444
+
445
+ Each control is independent: \`reactIcon: false\` preserves its current text appearance (the default); \`true\` shows its icon. Customize \`tag\`, \`size\`, \`colorDark\` and \`colorLight\` per control; \`currentColor\` follows the active theme. Icon selectors keep their menus and accessible names. \`site.FocusMode\` still controls whether focus mode is enabled; \`site.icons.FocusMode\` only changes the button's appearance.
446
+
356
447
  ## \`VersionControl\` section
357
448
 
358
449
  \`VersionControl.versions\` defines:
@@ -384,10 +475,11 @@ Version configs support multiple content types:
384
475
  - \`routes-html\`: HTML page paths per language
385
476
  - \`routes-video\`: Video config with \`video.videoType\` (youtube, vimeo, mp4, etc.) and \`video.pathVideo\`
386
477
  - \`routes-audio\`: Audio config with \`audio.audioType\` (youtube, mp3, etc.) and \`audio.pathAudio\`
478
+ - \`routes-pdf\`: PDF config with \`pdf.pathPdf\` per language; see PDF documents.
387
479
  - \`authorization\` (md/html/video): route guard by access key, roles, and external auth
388
- - \`menus-header-md\`, \`menus-header-source-viewer\`, \`menus-header-html\`, \`menus-header-video\`, \`menus-header-audio\`: menus per type
389
- - \`hierarchyPage\`: container order on page \`{ md: 0, "source-viewer": 1, html: 2, video: 3, audio: 4 }\`
390
- - \`hierarchyMenu\`: menu section order \`{ md: 0, "source-viewer": 1, html: 2, video: 3, audio: 4 }\`
480
+ - \`menus-header-md\`, \`menus-header-source-viewer\`, \`menus-header-html\`, \`menus-header-video\`, \`menus-header-audio\`, \`menus-header-pdf\`: menus per type
481
+ - \`hierarchyPage\`: container order on page \`{ md: 0, "source-viewer": 1, html: 2, video: 3, audio: 4, pdf: 5 }\`
482
+ - \`hierarchyMenu\`: menu section order \`{ md: 0, "source-viewer": 1, html: 2, video: 3, audio: 4, pdf: 5 }\`
391
483
 
392
484
  Each route can include \`title\`, \`description\` (per language), \`titleCss\`, \`titlePosition: "center"\`, \`descriptionPosition: "center"\`, \`titleIsVisible\`, \`descriptionIsVisible\`.
393
485
 
@@ -415,48 +507,84 @@ Per-route options for \`routes-md\`, \`routes-html\`, \`routes-video\`, and \`ro
415
507
 
416
508
  - \`GITPAGEDOCS_REPOSITORY_SEARCH\`: enable/disable remote repository search in local runtime
417
509
  - \`GITHUB_ACTIONS\`: enables GitHub Pages specific runtime behavior
510
+
511
+ ## Site behavior and defaults
512
+
513
+ | Key | Default / purpose |
514
+ | --- | --- |
515
+ | \`ActiveNavigation\` | true; ordinary previous/next controls |
516
+ | \`FocusMode / focusMode\` | Master switch (true) and independent copy, download, section and document controls; see Focus mode |
517
+ | \`pdf\` | PDF master switch, preview, download and new-tab defaults; all true |
518
+ | \`nestedMenusEnabled\` | true; recursive menu tree, or flat destinations when false |
519
+ | \`RouteGuide\` | true; breadcrumbs, overridable by version defaults and individual Markdown routes |
520
+ | \`accessibility\` | Enabled by default; narration settings are explained in Accessibility |
521
+ | \`HideThemeSelector\` | false; true hides the theme selector |
522
+ | \`FooterEnabled\` | true; show the footer |
523
+ | \`FooterLinkName / FooterLinkUrl\` | Footer link label and destination |
524
+ | \`FooterDateMode / FooterDateCustom\` | browser, year or custom; custom uses the configured text |
525
+ | \`SiteHeaderName / SiteIconPath\` | Header brand and site icon path |
526
+ | \`audioPlayerEnabled\` | true; background audio controls |
527
+ | \`audioAutoPlayOnLoad\` | false; autoplay remains subject to browser policy |
528
+ | \`audioLoopEnabled / audioSequentialPlayback\` | false; loop current track / advance native tracks |
529
+ | \`audioAllowUserChoice\` | Allow track selection when a playlist has multiple entries |
530
+ | \`audioTracks\` | Track objects: url, type and localized title |
531
+ | \`audioPopoverHideSource / audioPopoverShowMinutes\` | false / true; source label and native-track duration |
532
+ | \`audioPopoverSourceCustomLabel\` | Optional localized source label |
533
+ | \`mediaExclusivePlayback\` | true; only one audible source among narration, radio, audio and video |
534
+ | \`AiChatEnabled / AiChatAutoLockSeconds\` | true / 30; show the chat and lock after inactivity (0 disables the timer) |
535
+ | \`docsAccess\` | enabled and publicKey configure the documentation gate; public files remain public |
536
+ | \`RouteguideBrandPositionDefault / RouteguideBrandContainerTopDefault\` | center / false; heading-outline layout, distinct from breadcrumbs |
537
+ | \`TocScrollMaxHeightDesktop / TocScrollMaxHeightMobile\` | Heading-outline scroll limits; CSS lengths such as min(65vh, 400px) |
538
+
539
+ ## Adding a version or document
540
+
541
+ Create a version directory and its config, then register it in \`VersionControl.versions\` with \`id\` and \`path\`. Add a \`routes-md\` entry with a unique page ID and localized paths; add matching menu destinations. Keep \`routeDefaults\` for values shared by all routes; explicit route fields win. See Navigation for recursive menus and \`RouteGuide\` overrides.
542
+
543
+ Display settings are public configuration. Never store provider credentials or private keys in site JSON. The examples in Authorized routes demonstrate client-side controls, not server-side protection of downloadable files.
544
+
545
+ The \`QuickNavigation\` entry controls the Ctrl+K button's icon/text appearance. The keyboard shortcut and search panel remain available.
418
546
  `,
419
547
  deployment: `# Deployment
420
548
 
421
- Git Page Docs supports two usage models:
549
+ Choose the official viewer for a public repository, deploy a dedicated GitHub Pages site, or host a static export built from the runtime.
550
+
551
+ ## Official viewer
552
+
553
+ Commit the generated \`gitpagedocs/\` folder to your public repository. Open \`https://vidigal-code.github.io/git-page-docs/OWNER/REPOSITORY/\`; select a version and language. The viewer fetches the repository configuration and content. A private repository is not made public by using this URL.
422
554
 
423
- 1. Use the official viewer site
424
- 2. Self-host your own GitHub Pages runtime
555
+ ## Your GitHub Pages site
425
556
 
426
- ## Official viewer site
557
+ Prerequisites: Git repository, a GitHub origin, permission to push, and authenticated GitHub CLI (\`gh auth login\`) when configuring Pages through the CLI.
427
558
 
428
- Use:
559
+ \`\`\`bash
560
+ npx gitpagedocs pages deploy --owner OWNER --repo REPOSITORY
561
+ \`\`\`
562
+
563
+ This flow confirms the target, generates docs and \`.github/workflows/gitpagedocs-pages.yml\`, commits, pushes and requests GitHub Actions as the Pages source. To change only the source, use \`npx gitpagedocs pages actions\`. To publish under a subpath, pass \`--path docs\`.
429
564
 
430
- - \`https://vidigal-code.github.io/git-page-docs/\`
565
+ Watch the GitHub Actions run until deployment succeeds; the CLI's printed URL can appear before the remote build finishes. Project sites normally use \`https://OWNER.github.io/REPOSITORY/\`; user/organization sites use the root of their \`OWNER.github.io\` repository.
431
566
 
432
- Provide owner + repository to load docs from repositories that contain \`gitpagedocs/\`.
567
+ ## Build contract
433
568
 
434
- ## Self-hosted GitHub Pages
569
+ The workflow installs the pinned pnpm workspace dependencies, builds the viewer and uploads the static artifact with the official Pages actions. Its deploy job needs \`pages: write\`, \`id-token: write\` and the \`github-pages\` environment.
435
570
 
436
- 1. Generate docs:
437
- - \`npx @gitpagedocs/cli\`
438
- - or \`npx @gitpagedocs/cli --layoutconfig\` for local templates
439
- 2. Set \`site.rendering\` in \`gitpagedocs/config.json\`:
440
- - \`https://<your-user>.github.io/<your-repo>/\`
441
- 3. Build and validate:
442
- - \`npm run lint\`
443
- - \`npm run build\`
444
- 4. Deploy with GitHub Pages workflow.
571
+ - \`GITHUB_ACTIONS=true\` enables Next.js static export.
572
+ - \`GITHUB_REPOSITORY=OWNER/REPOSITORY\` supplies the repository base path.
573
+ - \`GITPAGEDOCS_REPOSITORY_SEARCH=true\` enables the search-home build.
574
+ - \`GITPAGEDOCS_BASE_PATH\` can explicitly override the base path; \`GITPAGEDOCS_PATH\` supplies the docs subpath.
575
+ - \`GITPAGEDOCS_DIST_DIR\` separates build/dev output when running two local servers.
445
576
 
446
- When \`GITHUB_ACTIONS=true\`, runtime applies GitHub Pages behavior.
577
+ A normal \`pnpm build\` without the Pages environment is a Next.js production build; it does not by itself prove the static export. Preserve \`.nojekyll\` when hosting the export on Pages.
447
578
 
448
- ## npm publish flows
579
+ ## Standalone export
449
580
 
450
- Recommended: GitHub Release + CI publish.
581
+ From a runtime checkout with installed dependencies, \`node cli/index.mjs --home --output gitpagedocshome --no-interactive\` builds \`frontend/\` and packages a static distribution. \`--search true\` enables its repository-search home. The output includes static files, a README, Dockerfile and environment example; its destination is recreated. A static web server serves the resulting files; changing a build-time environment option requires another build.
451
582
 
452
- Manual fallback:
583
+ ## npm releases for maintainers
453
584
 
454
- 1. \`npm whoami\`
455
- 2. \`npm run lint\`
456
- 3. \`npm run build\`
457
- 4. \`npm pack --ignore-scripts\`
458
- 5. \`npm version patch\`
459
- 6. \`npm publish --access public\`
585
+ The monorepo publishes \`@gitpagedocs/tools\`, \`@gitpagedocs/mcp\` and \`@gitpagedocs/cli\`; the workspace root and frontend are private. The current \`npm-publish.yml\` runs on pushes to \`main\` and skips a CLI version already on npm. It uses the repository's \`NPM_TOKEN\` secret and publishes workspaces in dependency order. Creating a GitHub release alone is not its trigger.
586
+
587
+ Synchronize package versions and internal dependencies, regenerate docs/baselines, run typecheck, lint, tests, smoke checks, build and Playwright, then review before pushing. Confirm all three package versions on npm and the Pages workflow result. The config-only CLI ignores \`prebuilt/\`; it is not required by this publishing workflow.
460
588
  `,
461
589
  architecture: `# Architecture
462
590
 
@@ -526,6 +654,411 @@ Each template usually includes:
526
654
  - Light/dark toggle resolves paired theme via reference.
527
655
  - CSS variables are generated from template tokens.
528
656
  - Runtime includes fallback behavior if a source is unavailable.
657
+
658
+ ## Choose and customize
659
+
660
+ Select an installed theme through the theme selector or configure \`site.ThemeDefault\` with its exact ID. \`ThemeModeDefault\` sets the initial light/dark mode. \`HideThemeSelector\` hides the selector; the selected theme still applies.
661
+
662
+ For your own repository, run the CLI with \`--layoutconfig\`, then edit the generated template and keep its ID consistent with \`layoutsConfig.json\`. A route's content and \`site.icons\` remain independent of the theme catalog. Use \`currentColor\` for icons that should inherit the active text color, or configure separate dark/light colors with sufficient contrast.
663
+
664
+ When contributing to Git Page Docs itself, the authoring source is \`gitpagelayouts/v2/base.json\` plus \`gitpagelayouts/v2/layouts/<id>.json\`. Run \`pnpm layouts:sync\` to regenerate templates and documentation. Direct edits to generated templates can be overwritten by that synchronization.
665
+ `,
666
+ mcp: `# MCP server
667
+
668
+ The Model Context Protocol server exposes 20 tools and 7 resources over **stdio**. It starts as a child process of your MCP client. It does not open an HTTP port or run a background daemon.
669
+
670
+ ## Install and connect
671
+
672
+ Use Node.js 20+. Install the CLI in the project with \`npm install --save-dev @gitpagedocs/cli\`; this includes the server and its TypeScript runtime. A global installation also supports \`gitpagedocs mcp start\`. For a one-off run, use \`npx --yes @gitpagedocs/cli mcp start\`.
673
+
674
+ In VS Code, create \`.vscode/mcp.json\` with the following configuration. The process working directory is the project root; the MCP command has no \`--root\` or \`--cwd\` flag.
675
+
676
+ \`\`\`json
677
+ {
678
+ "servers": {
679
+ "gitpagedocs": {
680
+ "type": "stdio",
681
+ "command": "node",
682
+ "args": [
683
+ "\${workspaceFolder}/node_modules/@gitpagedocs/cli/index.mjs",
684
+ "mcp",
685
+ "start"
686
+ ],
687
+ "cwd": "\${workspaceFolder}"
688
+ }
689
+ }
690
+ }
691
+ \`\`\`
692
+
693
+ Open the client's MCP server controls, start GitPageDocs and list its tools/resources. Test \`list_files\` with \`{"path":".","recursive":false}\` and read \`project://readme\`. These operations need no provider key. A terminal launched with \`mcp start\` waits for JSON-RPC; ordinary text typed into stdin is not a chat command. On a source checkout, the direct entry is \`node --import tsx mcp/src/bin.ts\`, not \`index.ts\`.
694
+
695
+ ## Configure a provider
696
+
697
+ Provider calls read credentials from the server process environment. MCP does not automatically load \`.env\` or the CLI's encrypted vault. Use the client's protected input/secret facility to inject environment values; never place real keys in a committed configuration. Restart the MCP process after changing its environment.
698
+
699
+ Select a provider using \`configure_ai_provider\` or \`.gitpagedocs-mcp.json\` at the project root:
700
+
701
+ \`\`\`json
702
+ {
703
+ "provider": "ollama",
704
+ "model": "llama3"
705
+ }
706
+ \`\`\`
707
+
708
+ | Provider | Environment |
709
+ | --- | --- |
710
+ | \`openai\` | \`OPENAI_API_KEY\` |
711
+ | \`anthropic\` | \`ANTHROPIC_API_KEY / CLAUDE_API_KEY\` |
712
+ | \`gemini\` | \`GEMINI_API_KEY / GOOGLE_API_KEY\` |
713
+ | \`openrouter\` | \`OPENROUTER_API_KEY\` |
714
+ | \`ollama\` | \`OLLAMA_BASE_URL\` |
715
+ | \`azure-openai\` | \`AZURE_OPENAI_API_KEY + AZURE_OPENAI_BASE_URL\` |
716
+ | \`mistral\` | \`MISTRAL_API_KEY\` |
717
+ | \`deepseek\` | \`DEEPSEEK_API_KEY\` |
718
+ | \`cohere\` | \`COHERE_API_KEY\` |
719
+ | \`groq\` | \`GROQ_API_KEY\` |
720
+ | \`xai\` | \`XAI_API_KEY\` |
721
+ | \`together\` | \`TOGETHER_API_KEY\` |
722
+ | \`fireworks\` | \`FIREWORKS_API_KEY\` |
723
+ | \`perplexity\` | \`PERPLEXITY_API_KEY\` |
724
+
725
+ With no valid selection, the default provider is OpenAI. Ollama does not require an API key; its local service and chosen model must be available. \`OLLAMA_BASE_URL\` is optional. Azure's base URL is the complete chat-operation URL, including deployment and API-version query when required. Model listings are the bundled catalog, not a live availability check.
726
+
727
+ ## Tool reference
728
+
729
+ \`?\` marks an optional argument. Paths and content are strings; \`recursive\` is boolean. Provider identifiers come from the provider catalog. Call tools through the MCP client's tool interface.
730
+
731
+ | Tool | Arguments | Behavior |
732
+ | --- | --- | --- |
733
+ | \`list_files\` | \`path?, recursive?\` | List files (defaults: current directory, non-recursive) |
734
+ | \`read_file\` | \`path\` | Read UTF-8 text |
735
+ | \`write_file\` | \`path, content\` | Write the entire file; create parent directories |
736
+ | \`search_project\` | \`query, extension?\` | Case-insensitive substring search |
737
+ | \`list_ai_providers\` | \`—\` | Read the provider catalog |
738
+ | \`list_ai_models\` | \`provider?\` | Read the local model catalog |
739
+ | \`configure_ai_provider\` | \`provider, model?\` | Save .gitpagedocs-mcp.json |
740
+ | \`ask_ai\` | \`prompt, provider?, model?, system?\` | Return one response, without conversation history |
741
+ | \`generate_documentation\` | \`path, provider?\` | Document one source file |
742
+ | \`generate_api_docs\` | \`path, provider?\` | Describe the API in one file |
743
+ | \`generate_database_docs\` | \`path, provider?\` | Describe data models in one file |
744
+ | \`analyze_source_code\` | \`path, provider?\` | Analyze one source file |
745
+ | \`generate_readme\` | \`provider?\` | Use the tree and package.json |
746
+ | \`generate_architecture_docs\` | \`provider?\` | Use the repository tree |
747
+ | \`analyze_repository\` | \`provider?\` | Analyze the repository tree |
748
+ | \`analyze_project\` | \`provider?\` | Analyze the tree and package.json |
749
+ | \`generate_changelog\` | \`provider?\` | Use up to 80 commits, falling back to the tree |
750
+ | \`generate_release_notes\` | \`provider?\` | Use the same context as the changelog |
751
+ | \`validate_docs\` | \`provider?\` | Ask the provider to review gathered Markdown |
752
+ | \`update_documentation\` | \`path, instructions?, provider?\` | Generate and write a managed region |
753
+
754
+ \`generate_*\`, \`analyze_*\`, \`ask_ai\` and \`validate_docs\` return text; they do not save it automatically. \`validate_docs\` is a provider review, not a deterministic link checker. Only \`write_file\`, \`configure_ai_provider\` and \`update_documentation\` write files. \`update_documentation\` preserves text outside \`<!-- gitpagedocs:start -->\` / \`<!-- gitpagedocs:end -->\`; it appends a region when a valid pair is absent. The server does not show its own confirmation prompt; configure permissions in the MCP client.
755
+
756
+ ## Resource reference
757
+
758
+ | URI | Content |
759
+ | --- | --- |
760
+ | \`project://structure\` | Repository tree |
761
+ | \`project://docs\` | Collected Markdown documents |
762
+ | \`project://config\` | Resolved configuration and sourcePath |
763
+ | \`project://repository\` | package.json content |
764
+ | \`project://readme\` | README.md |
765
+ | \`project://ai/providers\` | Provider catalog |
766
+ | \`project://ai/models\` | Model catalog by provider |
767
+
768
+ ## Example workflow
769
+
770
+ 1. Read \`project://structure\` and \`project://readme\`.
771
+ 2. Call \`list_ai_providers\` and \`list_ai_models\` to select a provider/model.
772
+ 3. Call \`generate_api_docs\` with \`{"path":"src/index.ts"}\` to review the returned draft.
773
+ 4. Save approved text with \`write_file\`, or use \`update_documentation\` with \`{"path":"docs/api.md","instructions":"Document the public API in English."}\` for a managed region.
774
+
775
+ The generation step sends selected project content to the configured provider.
776
+
777
+ ## Limits and troubleshooting
778
+
779
+ - File reads: up to 512,000 bytes. Listing: up to 2,000 entries; gathered project trees: 400 entries.
780
+ - Search: up to 5,000 entries, 200 matches, 240 characters per matching line.
781
+ - Documentation gathering: first 40 Markdown files among up to 2,000 entries; files over 40,000 bytes are skipped. Provider context is capped at 24,000 characters.
782
+ - Listing skips build/dependency directories such as \`node_modules\`, \`.git\`, \`.next\`, \`out\`, \`dist\`, \`prebuilt\`, \`.turbo\` and \`coverage\`. It does not interpret \`.gitignore\`; files such as \`.env\` are not automatically excluded. Run only in a trusted project and select the content to expose.
783
+ - Path checks use lexical containment; do not treat the process as an operating-system sandbox or assume symlink/junction isolation. Loading \`project://config\` can import JavaScript/TypeScript configuration.
784
+ - Tool failures include \`isError: true\`. Missing resources return \`Unavailable: ...\`. Check the client's stderr log for startup errors; stdout is reserved for JSON-RPC.
785
+ - If tools work but generation fails, verify provider selection, environment credentials, model availability and service connectivity.
786
+ `,
787
+ cli: `# CLI reference
788
+
789
+ ## CLI commands
790
+
791
+ | Command | Description |
792
+ |---------|--------------|
793
+ | \`gitpagedocs\` | Generate config and docs in \`gitpagedocs/\` |
794
+ | \`gitpagedocs --layoutconfig\` | Also generate local layouts/templates in \`gitpagelayouts/\` |
795
+ | \`gitpagedocs --home\` | Standalone distribution (\`gitpagedocshome/\`) |
796
+ | \`gitpagedocs --push --owner X --repo Y\` | Setup workflow, commit, push |
797
+ | \`gitpagedocs --interactive\` / \`-i\` | Interactive mode with prompts (the default in a terminal) |
798
+ | \`gitpagedocs --no-interactive\` / \`--yes\` / \`-y\` | Never prompt; use flags and defaults |
799
+ | \`gitpagedocs ai\` | Interactive AI documentation generator |
800
+ | \`gitpagedocs chat [question]\` | Streaming AI chat in the terminal (REPL on a TTY; one-shot with a question or piped stdin) |
801
+ | \`gitpagedocs provider [id]\` / \`models [provider]\` | List AI providers / catalog models |
802
+ | \`gitpagedocs document[:repo\\|:file\\|:folder]\` | Generate documentation with AI |
803
+ | \`gitpagedocs deploy\` / \`pages [actions\\|deploy]\` | Configure GitHub Pages via Actions + push |
804
+ | \`gitpagedocs docs\` | Refresh README/CONTRIBUTING/SECURITY managed regions |
805
+ | \`gitpagedocs password\` | Set a documentation access password (public key in \`site.docsAccess\`) |
806
+ | \`gitpagedocs config\` / \`config clear\` | Show the resolved config / delete the stored config and key vault |
807
+ | \`gitpagedocs doctor\` / \`version\` / \`update\` | Diagnostics / version / registry update check |
808
+ | \`gitpagedocs mcp start\` | Start the MCP server over stdio |
809
+
810
+ Install globally with \`npm install -g @gitpagedocs/cli\`, or run one-off with \`npx @gitpagedocs/cli\`.
811
+
812
+ ## CLI options
813
+
814
+ | Option | Description |
815
+ |--------|-------------|
816
+ | \`--owner <user>\` | GitHub owner |
817
+ | \`--repo <repo>\` | GitHub repository |
818
+ | \`--path <subpath>\` | Docs subpath (e.g. \`docs\`); without it, base path = repo name for correct CSS/JS on project sites |
819
+ | \`--output <dir>\` | Output directory (default: \`gitpagedocs\`) |
820
+ | \`--search <true-or-false>\` | Enable/disable repository search (\`--home\`) |
821
+ | \`--layoutconfig\` | Generate local layouts in \`gitpagelayouts/\` |
822
+ | \`--layouts-dir <dir>\` | Folder for local layouts (default: \`gitpagelayouts\`) |
823
+ | \`--push\` | Create workflow, commit artifacts, push |
824
+ | \`--pages-actions\` | Only switch GitHub Pages to GitHub Actions (same as \`pages actions\`) |
825
+ | \`--home\` | Generate \`gitpagedocshome/\` (static + .env + Dockerfile) |
826
+
827
+ ## Generated output
828
+
829
+ - \`gitpagedocs/config.json\` – root config
830
+ - \`gitpagedocs/icon.svg\` – default icon
831
+ - \`gitpagedocs/docs/versions/<ver>/config.json\` – per-version routes
832
+ - \`gitpagedocs/docs/versions/<ver>/{en,pt,es}/*.md\` – markdown docs
833
+ - \`gitpagelayouts/\` – only with \`--layoutconfig\` (folder configurable with \`--layouts-dir\`)
834
+
835
+ ## Examples and command boundaries
836
+
837
+ \`\`\`bash
838
+ npx gitpagedocs --no-interactive --owner octocat --repo handbook
839
+ npx gitpagedocs --layoutconfig --layouts-dir assets/layouts --no-interactive
840
+ npx gitpagedocs chat "Explain this project" --provider ollama --model llama3
841
+ npx gitpagedocs pages deploy --owner octocat --repo handbook --path docs
842
+ npx gitpagedocs mcp start
843
+ \`\`\`
844
+
845
+ - \`init\` is an alias of generation. \`providers\` aliases \`provider\`; \`--version\` and \`-v\` alias \`version\`.
846
+ - \`document\`, \`document:repo\`, \`document:file\`, \`document:folder\` and \`--ai\` select the interactive documentation workflow. Select directories in its prompts; these aliases do not implement a separate positional file/folder API.
847
+ - \`chat\` accepts \`--provider <id>\`, \`--model <id>\` and \`--system <prompt>\`. With a question or piped stdin it answers once; an interactive terminal without a question starts a conversation.
848
+ - \`--build\`, \`--serve\` and \`--full\` are compatibility flags: the ordinary scaffold remains config-only and they do not start a local server.
849
+ - \`--home\` builds \`frontend/\` from a runtime checkout and writes the static export plus supporting files. Its output directory is recreated when it is not \`.\`; keep your source documentation outside that destination. Installing the CLI alone does not supply \`frontend/\`.
850
+ - \`pages actions\` only configures the Pages source; \`pages deploy\` and \`--push\` generate, commit and push. A printed URL does not mean the remote build has finished: check GitHub Actions.
851
+ - \`update\` checks npm and prints an installation command; it does not silently upgrade the CLI.
852
+
853
+ ## Configuration and credentials
854
+
855
+ Site display settings are in \`gitpagedocs/config.json\`. The interactive generator/chat stores \`.gitpagedocsconfig\` and its encrypted \`.gitpagedocsvault\` in the per-user OS configuration directory: \`%APPDATA%/gitpagedocs\` on Windows, \`~/Library/Application Support/gitpagedocs\` on macOS, and the XDG config location on Linux. \`config clear\` removes those saved settings and the vault. MCP uses its own project-local \`.gitpagedocs-mcp.json\` plus process environment; see the MCP page.
856
+
857
+ \`gitpagedocs docs\` updates only marker-bounded regions of README.md, CONTRIBUTING.md and SECURITY.md, preserving surrounding prose. \`password\` configures the documentation access key pair; client-side presentation controls do not make public repository files confidential.
858
+ `,
859
+ navigation: `# Navigation and nested menus
860
+
861
+ Routes define page content; menus define how readers reach it. Configure them in \`gitpagedocs/docs/versions/<version>/config.json\`. Site-wide presentation options belong to \`gitpagedocs/config.json\`.
862
+
863
+ \`\`\`json
864
+ {
865
+ "site": {
866
+ "nestedMenusEnabled": true,
867
+ "RouteGuide": true
868
+ }
869
+ }
870
+ \`\`\`
871
+
872
+ ## Build a menu tree
873
+
874
+ Each \`menus-header-md\` entry has an \`id\` and localized \`pt\`, \`en\`, \`es\` objects with \`title\` and optional \`path-click\`. Add \`submenus\` containing more entries to nest the tree. A language object may also contain localized \`submenus\` with the same title/path structure. Use one form consistently to avoid listing the same child twice.
875
+
876
+ Groups without \`path-click\` organize children. For a Markdown destination, use its actual localized path from \`routes-md[].path\`. The \`page:<id>\` alias is registered by source-viewer, video, audio and PDF routes; do not use it for a Markdown-only page. The example below uses version \`0.0.8\`: replace that segment with the version you are editing and create the three chapter files.
877
+
878
+ \`\`\`json
879
+ {
880
+ "routeDefaults": {
881
+ "RouteGuide": false
882
+ },
883
+ "routes-md": [
884
+ {
885
+ "id": 101,
886
+ "RouteGuide": true,
887
+ "path": {
888
+ "pt": "gitpagedocs/docs/versions/0.0.8/pt/chapter.md",
889
+ "en": "gitpagedocs/docs/versions/0.0.8/en/chapter.md",
890
+ "es": "gitpagedocs/docs/versions/0.0.8/es/chapter.md"
891
+ }
892
+ }
893
+ ],
894
+ "menus-header-md": [
895
+ {
896
+ "id": 900,
897
+ "pt": {
898
+ "title": "Guia"
899
+ },
900
+ "en": {
901
+ "title": "Guide"
902
+ },
903
+ "es": {
904
+ "title": "Guía"
905
+ },
906
+ "submenus": [
907
+ {
908
+ "id": 901,
909
+ "pt": {
910
+ "title": "Capítulos"
911
+ },
912
+ "en": {
913
+ "title": "Chapters"
914
+ },
915
+ "es": {
916
+ "title": "Capítulos"
917
+ },
918
+ "submenus": [
919
+ {
920
+ "id": 101,
921
+ "pt": {
922
+ "title": "Primeiro capítulo",
923
+ "path-click": "gitpagedocs/docs/versions/0.0.8/pt/chapter.md"
924
+ },
925
+ "en": {
926
+ "title": "First chapter",
927
+ "path-click": "gitpagedocs/docs/versions/0.0.8/en/chapter.md"
928
+ },
929
+ "es": {
930
+ "title": "Primer capítulo",
931
+ "path-click": "gitpagedocs/docs/versions/0.0.8/es/chapter.md"
932
+ }
933
+ }
934
+ ]
935
+ }
936
+ ]
937
+ }
938
+ ]
939
+ }
940
+ \`\`\`
941
+
942
+ ## Nesting behavior
943
+
944
+ \`site.nestedMenusEnabled: true\` renders expandable recursive menus. You may add another \`submenus\` array at any node: there is no fixed application depth limit. The configuration must remain finite and practical for browser memory and usability. Setting it to \`false\` displays destinations as a flat list; it does not remove nested pages.
945
+
946
+ The tree supplies sidebar navigation, search labels, parent expansion and breadcrumb trails. Keep IDs stable and unambiguous; nodes pointing at a protected page follow its authorization rules. Apply the same structure to \`menus-header-source-viewer\`, \`menus-header-html\`, \`menus-header-video\` , \`menus-header-audio\` and \`menus-header-pdf\`. \`hierarchyMenu\` orders the type sections; \`hierarchyPage\` orders content containers that share a page ID.
947
+
948
+ ## Breadcrumbs: RouteGuide
949
+
950
+ \`RouteGuide\` controls the breadcrumb trail. Resolution order is the page's \`routes-md[].RouteGuide\`, then the version's \`routeDefaults.RouteGuide\`, then \`site.RouteGuide\`, with \`true\` as the fallback. The example disables breadcrumbs for the version and enables them for chapter 101. Existing version \`0.0.8\` files can use the same fields.
951
+
952
+ \`RouteguideBrand\` and \`RouteguideBrandPosition\` are separate settings for the document's heading outline/table of contents; they do not control breadcrumbs.
953
+
954
+ ## URLs and previous/next
955
+
956
+ Versioned URLs use \`/v/<version>/\`; \`?lang=pt\` selects a language and \`?id=101\` selects a page ID. \`?name=chapter\` selects the document slug. Keep \`VersionControl.versions[].path\` pointing at the matching version config. \`site.ActiveNavigation\` enables ordinary previous/next page controls; focus-mode document navigation has its own option. See Focus mode for its section and document controls.
957
+
958
+ Test a new menu from the sidebar, by direct URL and in each enabled language; verify the destination exists and is allowed for the current reader.
959
+ `,
960
+ focusMode: `# Focus mode
961
+
962
+ Focus mode opens the current Markdown document in a reading dialog. Enable it with \`site.FocusMode\`; the control is available only for a real Markdown page. \`site.icons.FocusMode\` changes its icon/text appearance and does not enable or disable the feature.
963
+
964
+ ## Configure the controls
965
+
966
+ Merge this fragment into \`gitpagedocs/config.json\`:
967
+
968
+ \`\`\`json
969
+ {
970
+ "site": {
971
+ "FocusMode": true,
972
+ "focusMode": {
973
+ "copyEnabled": true,
974
+ "downloadEnabled": true,
975
+ "sectionNavigationEnabled": true,
976
+ "documentNavigationEnabled": true
977
+ }
978
+ }
979
+ }
980
+ \`\`\`
981
+
982
+ Each option defaults to \`true\`; setting one to \`false\` hides its corresponding control. With \`sectionNavigationEnabled: false\`, focus mode displays the entire document without section pagination. Existing configurations without the new \`focusMode\` object keep the controls enabled.
983
+
984
+ ## Sections and documents
985
+
986
+ - Single-arrow previous/next controls move between sections of the same document.
987
+ - Double-arrow previous/next controls move between Markdown documents in menu order, including nested menus.
988
+ - Documents without a translation in the active language, non-Markdown destinations and inaccessible pages are skipped.
989
+ - Switching documents keeps the dialog open and starts at the first section. Section/document counters show the current position.
990
+ - \`site.ActiveNavigation\` controls the ordinary page-navigation interface; it does not disable focus-mode document navigation.
991
+
992
+ ## Copy and download
993
+
994
+ Copy and download use the **entire original Markdown document in the selected language**, including sections not currently visible. They do not export the rendered HTML or only the current reading section.
995
+
996
+ The download keeps the Markdown basename from the route's localized \`path\`; if unavailable, the filename is \`document.md\`. Clipboard access follows the browser's permission and secure-context rules. If copying fails, use download instead and check the displayed error.
997
+
998
+ ## Keyboard and reading
999
+
1000
+ The dialog has an accessible name, keyboard focus management and a close control. Use Tab to move through controls and Escape to close it. Keep icon-only controls accessible by retaining their translated names. Closing the dialog returns to the documentation view.
1001
+
1002
+ Narration is configured separately in Accessibility. Changing the active document or language cancels the previous narration so it cannot continue reading stale content.
1003
+ `,
1004
+ accessibility: `# Accessibility and narration
1005
+
1006
+ The accessibility controls include native browser narration for the current Markdown document. Narration uses the Web Speech API (\`speechSynthesis\`); it does not require an API key or an external GitPageDocs speech service.
1007
+
1008
+ ## Configuration
1009
+
1010
+ Merge the following settings into \`gitpagedocs/config.json\`:
1011
+
1012
+ \`\`\`json
1013
+ {
1014
+ "site": {
1015
+ "accessibility": {
1016
+ "enabled": true,
1017
+ "narration": {
1018
+ "enabled": true,
1019
+ "defaultRate": 1,
1020
+ "defaultVolume": 1
1021
+ }
1022
+ },
1023
+ "mediaExclusivePlayback": true
1024
+ }
1025
+ }
1026
+ \`\`\`
1027
+
1028
+ - \`site.accessibility.enabled\`: enable the accessibility interface.
1029
+ - \`site.accessibility.narration.enabled\`: enable document narration.
1030
+ - \`defaultRate\`: initial speed from \`0.5\` to \`2\`, in steps of \`0.25\`; the default is \`1\`.
1031
+ - \`defaultVolume\`: initial volume from \`0\` (silent) to \`1\` (full), in steps of \`0.1\`; the default is \`1\`.
1032
+ - All enable switches default to \`true\`; omitted settings use the shipped defaults.
1033
+
1034
+ ## Read a document aloud
1035
+
1036
+ 1. Open a Markdown page and the accessibility/narration controls.
1037
+ 2. Choose a voice and language from those exposed by your browser; adjust speed and volume.
1038
+ 3. Start reading. Pause temporarily, resume from the paused speech or stop the session.
1039
+ 4. To change reading settings predictably, stop, change the controls and start again.
1040
+
1041
+ Narration starts only after your action; there is no autoplay. Automatic voice selection follows the document language, while an explicit voice choice uses that voice's language. Narration does not translate the document.
1042
+
1043
+ The speech content is readable text extracted from the rendered Markdown. Scripts, styles, SVG content and elements marked hidden for assistive technology are excluded. Long documents are read completely in successive blocks. Changing the document or language, disabling narration or leaving the page cancels the previous speech.
1044
+
1045
+ The normal view and focus mode share voice, speed and volume preferences while the page remains mounted. These preferences are not stored across reloads. Non-numeric speed or volume settings use \`1\`; numeric settings outside the supported ranges are clamped to their nearest limit.
1046
+
1047
+ ## One audio source at a time
1048
+
1049
+ With \`site.mediaExclusivePlayback: true\` (default), starting or resuming narration pauses the radio, audio tracks and route videos. Starting those media stops narration. A muted video remains outside this sound rule. Use \`false\` only when simultaneous playback is intentional.
1050
+
1051
+ The setting is shared with existing media playback; there is no second narration-exclusivity flag. The page remains readable when narration is disabled.
1052
+
1053
+ ## Browser and voice availability
1054
+
1055
+ Speech support and voices depend on the browser, operating system and installed or remotely supplied voices. Voice lists can arrive after the page loads. A browser may expose a different set of languages than another device.
1056
+
1057
+ Unavailable speech support and playback errors are reported in the interface. Confirm that a usable voice exists, system audio is enabled and the page has received a user interaction. An empty voice list is not evidence that the document failed to load.
1058
+
1059
+ Do not assume every voice works offline: browser voices can be local or remote. This feature speaks text; it does not record microphone input. Browser narration complements keyboard navigation and screen readers; it does not replace them.
1060
+
1061
+ See the [Web Speech API reference](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis) for browser-level behavior.
529
1062
  `,
530
1063
  faq: `# FAQ
531
1064
 
@@ -556,5 +1089,25 @@ Check:
556
1089
  ## Why can GitHub Pages behave differently from local?
557
1090
 
558
1091
  Because GitHub Pages build mode enables repository-search home and static-export specific behavior.
1092
+
1093
+ ## Why does an icon still show text?
1094
+
1095
+ Set \`site.icons.<Control>.reactIcon\` to the boolean \`true\`, with an exact React Icons export name in \`tag\`. Supported controls include LanguageSelector, ThemeSelector, FocusMode and QuickNavigation. Flat \`Icon*ReactIcones\` fields take precedence if both formats are present. Check whether the feature itself is disabled, such as \`HideThemeSelector\` or \`FocusMode\`.
1096
+
1097
+ ## Why do menu children or breadcrumbs differ?
1098
+
1099
+ \`nestedMenusEnabled: false\` intentionally flattens destinations. Check \`submenus\`, language objects and \`path-click\`, then confirm that referenced pages exist and are accessible. Breadcrumbs use \`RouteGuide\` with route > version > site priority. \`RouteguideBrand\` controls the heading outline instead.
1100
+
1101
+ ## Why is narration silent or interrupted?
1102
+
1103
+ Check browser support, available voice, language, volume and system output. Voices can load asynchronously or require a remote service. With \`mediaExclusivePlayback: true\`, another audio/video source stops narration by design. Switching documents cancels the old speech. See Accessibility for setup.
1104
+
1105
+ ## Why does the MCP command wait or a tool fail?
1106
+
1107
+ \`mcp start\` waits for an MCP client over stdio; it is not a terminal chat prompt. Confirm the process cwd and use the published CLI entry or \`mcp/src/bin.ts\`. Filesystem/catalog tools need no provider, but generation requires credentials in the MCP process environment. The CLI vault and \`.env\` are not loaded automatically; inspect \`isError\` and the client's stderr log.
1108
+
1109
+ ## Why did regeneration change my pages?
1110
+
1111
+ Scaffolding writes generated routes, configs and documentation again. Review changes in Git and keep project-specific content in your chosen source files. In this repository, edit \`cli/content/docs-{en,pt,es}.mjs\` and route metadata before regeneration; do not edit generated copies as the only source.
559
1112
  `,
560
1113
  };