@gitpagedocs/cli 0.0.8 → 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 +13 -0
  2. package/builders/version-config-builder.mjs +17 -4
  3. package/content/assets/gitpagedocs-project-guide.pdf +245 -0
  4. package/content/docs-en.mjs +645 -102
  5. package/content/docs-es.mjs +649 -90
  6. package/content/docs-pt.mjs +649 -90
  7. package/contracts/doc-versions.mjs +1 -1
  8. package/contracts/index.mjs +1 -0
  9. package/data/default-site-config.mjs +38 -0
  10. package/data/i18n-langmenu.mjs +81 -0
  11. package/data/path-mappings.mjs +13 -0
  12. package/data/route-metas.mjs +59 -2
  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-es.mjs CHANGED
@@ -1,4 +1,82 @@
1
1
  export const docsEs = {
2
+ pdf: `# Documentos PDF
3
+
4
+ PDF es un tipo de contenido propio junto con Markdown, HTML, código fuente, vídeo y audio. La vista previa utiliza el visor nativo de PDF del navegador. Las acciones de descarga y apertura en una pestaña nueva se configuran de forma independiente.
5
+
6
+ ## Guía del proyecto en inglés
7
+
8
+ El scaffold incluye la [Guía del proyecto GitPageDocs (PDF, inglés)](https://github.com/Vidigal-code/git-page-docs/blob/main/cli/content/assets/gitpagedocs-project-guide.pdf). Explica el proyecto, paquetes, configuración, iconos, modo foco, narración, CLI, MCP y publicación. El PDF está en inglés; esta referencia está disponible en español, inglés y portugués.
9
+
10
+ La CLI copia los bytes del anexo a \`gitpagedocs/docs/versions/<versión>/en/gitpagedocs-project-guide.pdf\`. Los tres idiomas del ejemplo apuntan a ese archivo en inglés. Para ofrecer traducciones, añade los PDFs traducidos y cambia la ruta de cada idioma.
11
+
12
+ ## Valores predeterminados del sitio
13
+
14
+ Añade este bloque dentro de \`site\` en \`gitpagedocs/config.json\`:
15
+
16
+ \`\`\`json
17
+ {
18
+ "pdf": {
19
+ "enabled": true,
20
+ "previewEnabled": true,
21
+ "downloadEnabled": true,
22
+ "openInNewTabEnabled": true
23
+ }
24
+ }
25
+ \`\`\`
26
+
27
+ \`enabled\` es el interruptor general del contenido PDF. Los demás campos controlan la vista previa, el botón de descarga y el enlace de nueva pestaña. Cada campo omitido toma el valor \`true\`, también en configuraciones antiguas.
28
+
29
+ La precedencia de las acciones es \`ruta.pdf.<flag>\` > \`site.pdf.<flag>\` > \`true\`. Un \`true\` explícito en la ruta activa esa acción aunque el valor del sitio sea \`false\`; \`site.pdf.enabled: false\` sigue desactivando todos los PDFs. Si falta la ruta del idioma seleccionado, el PDF no está disponible; no hay cambio automático de idioma.
30
+
31
+ ## Ejemplo de ruta y menú
32
+
33
+ En \`gitpagedocs/docs/versions/0.0.9/config.json\`, conserva las listas de rutas y menús en el nivel principal:
34
+
35
+ \`\`\`json
36
+ {
37
+ "routes-pdf": [{
38
+ "id": 23,
39
+ "title": { "en": "Project guide (English)", "pt": "Guia do projeto (inglês)", "es": "Guía del proyecto (inglés)" },
40
+ "pdf": {
41
+ "pathPdf": {
42
+ "en": "gitpagedocs/docs/versions/0.0.9/en/gitpagedocs-project-guide.pdf",
43
+ "pt": "gitpagedocs/docs/versions/0.0.9/en/gitpagedocs-project-guide.pdf",
44
+ "es": "gitpagedocs/docs/versions/0.0.9/en/gitpagedocs-project-guide.pdf"
45
+ },
46
+ "previewEnabled": true,
47
+ "downloadEnabled": true,
48
+ "openInNewTabEnabled": true
49
+ }
50
+ }],
51
+ "menus-header-pdf": [{
52
+ "id": 23,
53
+ "en": { "title": "Project guide (English)", "path-click": "page:23" },
54
+ "pt": { "title": "Guia do projeto (inglês)", "path-click": "page:23" },
55
+ "es": { "title": "Guía del proyecto (inglés)", "path-click": "page:23" }
56
+ }]
57
+ }
58
+ \`\`\`
59
+
60
+ El mapa \`pdf.pathPdf\` selecciona el archivo del idioma actual. Usa \`page:<id>\` en los destinos del menú PDF. Se admite la misma estructura recursiva de \`submenus\` que en otros menús. El scaffold reserva el ID 23 para el ejemplo PDF y el ID 24 para esta referencia Markdown; utiliza IDs únicos para las páginas adicionales.
61
+
62
+ Las opciones de la ruta se colocan dentro de \`pdf\`. La presentación compartida, \`container\`, \`RouteGuide\` y la autorización permanecen en el nivel de la ruta. \`routeDefaults\` también se aplica a las rutas PDF. Añade \`"pdf": 5\` en \`hierarchyPage\` y \`hierarchyMenu\` para colocar los PDFs después del audio; ajusta los valores según el orden deseado.
63
+
64
+ ## Archivos y publicación
65
+
66
+ Las rutas relativas a la raíz del repositorio que empiezan por \`gitpagedocs/\` se copian a los assets públicos del visor al iniciar o compilar Next.js. La URL respeta el subdirectorio de publicación de GitHub Pages. Incluye el PDF en Git y publícalo junto con la documentación generada. Los archivos fuera de \`gitpagedocs/\` deben estar en \`frontend/public/\` del visor o ser accesibles mediante una URL HTTP(S).
67
+
68
+ Usa la URL del PDF binario, no una página HTML de vista previa del repositorio. Para repositorios remotos, la ruta se resuelve dentro de ese repositorio. Tanto la vista previa como la descarga obtienen los bytes del archivo, por lo que un servidor externo debe permitir CORS en ambas operaciones. El visor valida la firma PDF y crea una URL Blob temporal de tipo \`application/pdf\` para la vista previa nativa; libera esa URL al cambiar o cerrar el documento. La política de incorporación y las cabeceras de tipo/disposición del servidor de origen no controlan esta vista previa Blob.
69
+
70
+ El enlace de nueva pestaña abre directamente la URL original. Su comportamiento depende del navegador y de las cabeceras \`Content-Type\` y \`Content-Disposition\`; una URL raw puede descargar el archivo en vez de mostrarlo. El enlace directo sigue disponible si falla la vista previa o la descarga, salvo cuando esa acción está desactivada.
71
+
72
+ ## Lectura y diagnóstico
73
+
74
+ - Los controles nativos de PDF, teclado, zoom y navegación dependen del visor del navegador. Algunos navegadores móviles abren o descargan el archivo en vez de incorporarlo.
75
+ - La vista previa no convierte PDF en Markdown. El modo foco, la navegación por secciones, la copia de Markdown y la narración actúan sobre documentos Markdown, no sobre el PDF incorporado.
76
+ - Desactivar la vista previa puede conservar la descarga y la nueva pestaña. Desactivar todas las acciones deja el PDF sin controles interactivos.
77
+ - Ocultar un botón no controla el acceso. Los PDFs alojados públicamente siguen disponibles mediante su URL. Los documentos confidenciales necesitan alojamiento protegido.
78
+ - Si la vista previa está vacía, abre una pestaña nueva, comprueba que la ruta devuelve un PDF y revisa las cabeceras del servidor. Los fallos de descarga se muestran en la página.
79
+ `,
2
80
  index: `# Git Page Docs
3
81
 
4
82
  Git Page Docs es un runtime de documentacion multilenguaje para repositorios que incluyen la carpeta \`gitpagedocs/\`.
@@ -31,45 +109,63 @@ El runtime espera esta estructura:
31
109
  - Abre **Temas y layouts** para creacion de templates.
32
110
  - Abre **Rutas autorizadas** para configurar clave, roles y autenticacion externa.
33
111
  - Abre **FAQ** para troubleshooting.
112
+
113
+ ## Referencias detalladas
114
+
115
+ - **Referencia de la CLI**: instalación, todos los comandos y flags de compatibilidad.
116
+ - **Servidor MCP**: cliente, 20 tools, 7 resources y configuración de proveedores.
117
+ - **Navegación y submenús**: árboles recursivos, URLs y prioridad de breadcrumbs.
118
+ - **Modo foco**: copiar/descargar Markdown y navegar por sección/documento.
119
+ - **Accesibilidad y narración**: voces del navegador, controles e interacción con medios.
120
+ - **Documentos PDF**: vista previa nativa, descarga/nueva pestaña y la guía incluida en inglés.
34
121
  `,
35
122
  gettingStarted: `# Primeros pasos
36
123
 
37
- Esta guia lleva el proyecto desde cero hasta docs corriendo.
124
+ Git Page Docs separa los archivos de documentación del visor. Instala la CLI para crear los archivos; utiliza el visor oficial, GitHub Pages o un checkout del runtime para mostrarlos.
38
125
 
39
- ## Requisitos
126
+ ## Requisitos e instalación
40
127
 
41
- - Node.js 20+
42
- - npm 10+ (o pnpm)
128
+ Utiliza Node.js 20 o posterior. Git es necesario para publicar; GitHub CLI es necesario cuando la CLI configura Pages automáticamente.
43
129
 
44
- ## Setup local
130
+ \`\`\`bash
131
+ npm install --save-dev @gitpagedocs/cli
132
+ npx gitpagedocs --no-interactive --owner TU_USUARIO --repo TU_REPOSITORIO
133
+ \`\`\`
45
134
 
46
- 1. Instala dependencias:
47
- - \`npm install\`
48
- 2. Genera/actualiza artefactos de docs:
49
- - \`npm run gitpagedocs\`
50
- 3. Inicia desarrollo:
51
- - \`npm run dev\`
52
- 4. Build + ejecucion local de produccion:
53
- - \`npm run build\`
54
- - \`npm start\`
135
+ Para una ejecución sin instalación local, utiliza \`npx --yes @gitpagedocs/cli --no-interactive --owner TU_USUARIO --repo TU_REPOSITORIO\`. Para instalar globalmente, utiliza \`npm install -g @gitpagedocs/cli\` y después \`gitpagedocs\`. Ejecuta desde la raíz del repositorio.
55
136
 
56
- ## Comportamiento de la CLI
137
+ ## Contrato generado
57
138
 
58
- \`npx @gitpagedocs/cli\` (o \`npm run gitpagedocs\`) genera artefactos en la carpeta oficial \`gitpagedocs/\`.
139
+ - \`gitpagedocs/config.json\`: opciones del sitio y referencias de versiones.
140
+ - \`gitpagedocs/langs/{en,pt,es}.json\`: textos de la interfaz.
141
+ - \`gitpagedocs/docs/versions/<version>/config.json\`: rutas y menús.
142
+ - \`gitpagedocs/docs/versions/<version>/{en,pt,es}/*.md\`: contenido; los nombres de archivo permanecen en inglés en los tres idiomas.
143
+ - \`gitpagedocs/icon.svg\`: icono del sitio.
144
+ - \`--layoutconfig\` también escribe \`gitpagelayouts/\`; \`--layouts-dir\` cambia esa carpeta.
59
145
 
60
- - Genera solo markdown/json
61
- - No genera \`index.html\`
62
- - No genera \`index.js\`
63
- - No ejecuta comandos de instalacion
146
+ El generador escribe configuración y contenido; no instala una aplicación Next.js en tu repositorio. Ejecutarlo de nuevo vuelve a escribir los archivos del scaffold: revisa el diff de Git antes de conservar cambios en documentación editada manualmente.
64
147
 
65
- ## Modo de busqueda por repositorio
148
+ ## Leer y publicar
66
149
 
67
- En local, se controla por variable:
150
+ Haz commit y push de la carpeta generada y abre \`https://vidigal-code.github.io/git-page-docs/TU_USUARIO/TU_REPOSITORIO/\` para un repositorio público. Para publicar tu propio sitio, autentícate con \`gh auth login\` y ejecuta \`npx gitpagedocs pages deploy --owner TU_USUARIO --repo TU_REPOSITORIO\`. Esto genera archivos, hace commit y push; revisa la ejecución de GitHub Actions. Consulta Publicación para subrutas y el contrato del workflow.
68
151
 
69
- - \`GITPAGEDOCS_REPOSITORY_SEARCH=true\`
70
- - \`GITPAGEDOCS_REPOSITORY_SEARCH=false\`
152
+ ## Desarrollar el visor localmente
71
153
 
72
- En build de GitHub Pages (\`GITHUB_ACTIONS=true\`), la busqueda de repositorio siempre esta activa.
154
+ Los siguientes comandos pertenecen a un checkout de Git Page Docs, no a un repositorio que solo contiene archivos generados:
155
+
156
+ \`\`\`bash
157
+ git clone https://github.com/Vidigal-code/git-page-docs.git
158
+ cd git-page-docs
159
+ corepack enable
160
+ pnpm install --frozen-lockfile
161
+ pnpm dev
162
+ \`\`\`
163
+
164
+ El repositorio fija pnpm en \`packageManager\`. \`pnpm dev\` activa la búsqueda de repositorios; \`pnpm dev:e2e\` utiliza la documentación local. Para producción local, ejecuta \`pnpm build\` y \`pnpm start\`; el script start recompila antes de iniciar. Configura \`PORT=3100\` en el entorno del proceso cuando el puerto 3000 esté ocupado.
165
+
166
+ ## Siguientes pasos
167
+
168
+ Usa Configuración para idiomas, iconos, navegación, foco y narración; Funcionalidades para CLI y MCP; Temas y diseños para tokens visuales; Preguntas frecuentes para diagnóstico.
73
169
  `,
74
170
  projectOverview: `# Vision general del proyecto
75
171
 
@@ -101,51 +197,9 @@ Git Page Docs es un monorepo pnpm + turborepo que convierte la carpeta \`gitpage
101
197
 
102
198
  Referencia completa de opciones CLI, claves de configuracion y funciones del runtime.
103
199
 
104
- ## Comandos CLI
200
+ ## Línea de comandos
105
201
 
106
- | Comando | Descripcion |
107
- |---------|-------------|
108
- | \`npx @gitpagedocs/cli\` | Genera config y docs en \`gitpagedocs/\` |
109
- | \`npx @gitpagedocs/cli --layoutconfig\` | Tambien genera layouts/templates locales en \`gitpagelayouts/\` |
110
- | \`npx @gitpagedocs/cli --home\` | Distribucion standalone (\`gitpagedocshome/\`) |
111
- | \`npx @gitpagedocs/cli --push --owner X --repo Y\` | Configura workflow, commit, push |
112
- | \`npx @gitpagedocs/cli --interactive\` / \`-i\` | Modo interactivo con prompts (por defecto en una terminal) |
113
- | \`npx @gitpagedocs/cli --no-interactive\` / \`--yes\` / \`-y\` | Nunca pregunta; usa flags y valores por defecto |
114
- | \`gitpagedocs ai\` | Generador interactivo de documentacion con IA |
115
- | \`gitpagedocs chat [pregunta]\` | Chat de IA con streaming en la terminal (REPL en TTY; respuesta unica con pregunta o stdin) |
116
- | \`gitpagedocs provider [id]\` / \`models [provider]\` | Lista proveedores de IA / modelos del catalogo |
117
- | \`gitpagedocs document[:repo\\|:file\\|:folder]\` | Genera documentacion con IA |
118
- | \`gitpagedocs deploy\` / \`pages [actions\\|deploy]\` | Configura GitHub Pages via Actions + push |
119
- | \`gitpagedocs docs\` | Actualiza las regiones gestionadas de README/CONTRIBUTING/SECURITY |
120
- | \`gitpagedocs password\` | Define la contrasena de acceso a la documentacion (clave publica en \`site.docsAccess\`) |
121
- | \`gitpagedocs config\` / \`config clear\` | Muestra la config resuelta / borra la config guardada y la boveda de claves |
122
- | \`gitpagedocs doctor\` / \`version\` / \`update\` | Diagnostico / version / comprobacion de actualizacion en el registro |
123
- | \`gitpagedocs mcp start\` | Inicia el servidor MCP por stdio |
124
-
125
- Instala globalmente con \`npm install -g @gitpagedocs/cli\` o ejecuta sin instalar con \`npx @gitpagedocs/cli\`.
126
-
127
- ## Opciones CLI
128
-
129
- | Opcion | Descripcion |
130
- |--------|-------------|
131
- | \`--owner <user>\` | Owner de GitHub |
132
- | \`--repo <repo>\` | Repositorio GitHub |
133
- | \`--path <subpath>\` | Subruta de docs (ej: \`docs\`); sin ella, base path = nombre del repo para CSS/JS en project sites |
134
- | \`--output <dir>\` | Directorio de salida (default: \`gitpagedocs\`) |
135
- | \`--search true|false\` | Habilita/deshabilita busqueda de repositorio (\`--home\`) |
136
- | \`--layoutconfig\` | Genera layouts locales en \`gitpagelayouts/\` |
137
- | \`--layouts-dir <dir>\` | Carpeta de layouts locales (por defecto: \`gitpagelayouts\`) |
138
- | \`--push\` | Crea workflow, commit de artefactos, push |
139
- | \`--pages-actions\` | Solo cambia la fuente de GitHub Pages a GitHub Actions (igual que \`pages actions\`) |
140
- | \`--home\` | Genera \`gitpagedocshome/\` (estatico + .env + Dockerfile) |
141
-
142
- ## Salida generada
143
-
144
- - \`gitpagedocs/config.json\` – config raiz
145
- - \`gitpagedocs/icon.svg\` – icono por defecto
146
- - \`gitpagedocs/docs/versions/<ver>/config.json\` – rutas por version
147
- - \`gitpagedocs/docs/versions/<ver>/{en,pt,es}/*.md\` – docs en markdown
148
- - \`gitpagelayouts/\` – solo con \`--layoutconfig\` (carpeta configurable con \`--layouts-dir\`)
202
+ Consulta **Referencia de la CLI** para comandos, flags, ejemplos y compatibilidad. Consulta **Servidor MCP** para integración con editores.
149
203
 
150
204
  ## Tipos de contenido
151
205
 
@@ -155,6 +209,7 @@ Instala globalmente con \`npm install -g @gitpagedocs/cli\` o ejecuta sin instal
155
209
  | HTML | \`routes-html\` | \`path\` local o \`url\` externa |
156
210
  | Video | \`routes-video\` | \`video.pathVideo\`, \`video.videoType\` |
157
211
  | Audio | \`routes-audio\` | \`audio.pathAudio\`, \`audio.audioType\` |
212
+ | PDF | \`routes-pdf\` | \`pdf.pathPdf\` por idioma; vista previa nativa y descarga |
158
213
 
159
214
  ## Visor de codigo fuente
160
215
 
@@ -238,6 +293,37 @@ Claves principales:
238
293
  - \`layoutsConfigPath\`: fallback remoto de layouts
239
294
  - \`rendering\`: URL canonica publicada
240
295
 
296
+ ## Controles de idioma, tema y foco
297
+
298
+ En \`gitpagedocs/config.json\`, agrega estas entradas a \`site.icons\` para usar React Icons en el selector de idioma, el selector de tema y el boton de foco:
299
+
300
+ \`\`\`json
301
+ {
302
+ "site": {
303
+ "icons": {
304
+ "LanguageSelector": {
305
+ "reactIcon": true, "tag": "FiGlobe", "size": "22px",
306
+ "colorDark": "currentColor", "colorLight": "currentColor"
307
+ },
308
+ "ThemeSelector": {
309
+ "reactIcon": true, "tag": "BsSunFill", "size": "22px",
310
+ "colorDark": "currentColor", "colorLight": "currentColor"
311
+ },
312
+ "FocusMode": {
313
+ "reactIcon": true, "tag": "MdFullscreen", "size": "22px",
314
+ "colorDark": "currentColor", "colorLight": "currentColor"
315
+ },
316
+ "QuickNavigation": {
317
+ "reactIcon": true, "tag": "FiSearch", "size": "22px",
318
+ "colorDark": "currentColor", "colorLight": "currentColor"
319
+ }
320
+ }
321
+ }
322
+ }
323
+ \`\`\`
324
+
325
+ Cada control es independiente: \`reactIcon: false\` conserva la apariencia actual con texto (por defecto); \`true\` muestra el icono. Personaliza \`tag\`, \`size\`, \`colorDark\` y \`colorLight\` por control; \`currentColor\` sigue el tema activo. Los selectores con iconos mantienen sus menus y nombres accesibles. \`site.FocusMode\` sigue controlando si el modo foco esta habilitado; \`site.icons.FocusMode\` solo cambia la apariencia del boton.
326
+
241
327
  ## Seccion \`VersionControl\`
242
328
 
243
329
  \`VersionControl.versions\` define:
@@ -269,10 +355,11 @@ Los configs de version soportan multiples tipos:
269
355
  - \`routes-html\`: Rutas de paginas HTML por idioma
270
356
  - \`routes-video\`: Config de video con \`video.videoType\` (youtube, vimeo, mp4, etc.) y \`video.pathVideo\`
271
357
  - \`routes-audio\`: Config de audio con \`audio.audioType\` (youtube, mp3, etc.) y \`audio.pathAudio\`
358
+ - \`routes-pdf\`: PDF con \`pdf.pathPdf\` por idioma; consulta Documentos PDF.
272
359
  - \`authorization\` (md/html/video): guardia de acceso por clave, roles y autenticacion externa
273
- - \`menus-header-md\`, \`menus-header-source-viewer\`, \`menus-header-html\`, \`menus-header-video\`, \`menus-header-audio\`: menus por tipo
274
- - \`hierarchyPage\`: orden de contenedores en la pagina \`{ md: 0, "source-viewer": 1, html: 2, video: 3, audio: 4 }\`
275
- - \`hierarchyMenu\`: orden de secciones del menu \`{ md: 0, "source-viewer": 1, html: 2, video: 3, audio: 4 }\`
360
+ - \`menus-header-md\`, \`menus-header-source-viewer\`, \`menus-header-html\`, \`menus-header-video\`, \`menus-header-audio\`, \`menus-header-pdf\`: menus por tipo
361
+ - \`hierarchyPage\`: orden de contenedores en la pagina \`{ md: 0, "source-viewer": 1, html: 2, video: 3, audio: 4, pdf: 5 }\`
362
+ - \`hierarchyMenu\`: orden de secciones del menu \`{ md: 0, "source-viewer": 1, html: 2, video: 3, audio: 4, pdf: 5 }\`
276
363
 
277
364
  Cada ruta puede incluir \`title\`, \`description\` (por idioma), \`titleCss\`, \`titlePosition: "center"\`, \`descriptionPosition: "center"\`, \`titleIsVisible\`, \`descriptionIsVisible\`.
278
365
 
@@ -297,37 +384,84 @@ Opciones por ruta en \`routes-md\`, \`routes-html\` y \`routes-video\`:
297
384
 
298
385
  - \`GITPAGEDOCS_REPOSITORY_SEARCH\`: activa/desactiva busqueda remota en local
299
386
  - \`GITHUB_ACTIONS\`: habilita comportamiento especifico de GitHub Pages
387
+
388
+ ## Comportamiento del sitio y valores predeterminados
389
+
390
+ | Clave | Valor / finalidad |
391
+ | --- | --- |
392
+ | \`ActiveNavigation\` | true; controles habituales anterior/siguiente |
393
+ | \`FocusMode / focusMode\` | Activación general (true) y controles independientes de copia, descarga, sección y documento; consulta Modo foco |
394
+ | \`pdf\` | Activación general, vista previa, descarga y nueva pestaña; todos true |
395
+ | \`nestedMenusEnabled\` | true; árbol recursivo, o destinos planos con false |
396
+ | \`RouteGuide\` | true; breadcrumbs, con prioridad para valores de versión y ruta Markdown |
397
+ | \`accessibility\` | Activado por defecto; opciones de narración en Accesibilidad |
398
+ | \`HideThemeSelector\` | false; true oculta el selector de tema |
399
+ | \`FooterEnabled\` | true; muestra el pie de página |
400
+ | \`FooterLinkName / FooterLinkUrl\` | Texto y destino del enlace del pie |
401
+ | \`FooterDateMode / FooterDateCustom\` | browser, year o custom; custom utiliza el texto configurado |
402
+ | \`SiteHeaderName / SiteIconPath\` | Marca de cabecera y ruta del icono del sitio |
403
+ | \`audioPlayerEnabled\` | true; controles de audio de fondo |
404
+ | \`audioAutoPlayOnLoad\` | false; autoplay depende de la política del navegador |
405
+ | \`audioLoopEnabled / audioSequentialPlayback\` | false; repetir pista / avanzar pistas nativas |
406
+ | \`audioAllowUserChoice\` | Permite elegir pista cuando la lista tiene varias entradas |
407
+ | \`audioTracks\` | Objetos con url, type y title por idioma |
408
+ | \`audioPopoverHideSource / audioPopoverShowMinutes\` | false / true; origen y duración de pistas nativas |
409
+ | \`audioPopoverSourceCustomLabel\` | Texto opcional del origen por idioma |
410
+ | \`mediaExclusivePlayback\` | true; un audio entre narración, radio, pistas y vídeo |
411
+ | \`AiChatEnabled / AiChatAutoLockSeconds\` | true / 30; muestra chat y bloquea por inactividad (0 desactiva el temporizador) |
412
+ | \`docsAccess\` | enabled y publicKey configuran el acceso a documentación; los archivos públicos siguen siendo públicos |
413
+ | \`RouteguideBrandPositionDefault / RouteguideBrandContainerTopDefault\` | center / false; posición del índice de títulos, separado de breadcrumbs |
414
+ | \`TocScrollMaxHeightDesktop / TocScrollMaxHeightMobile\` | Límites de desplazamiento del índice; longitudes CSS como min(65vh, 400px) |
415
+
416
+ ## Añadir una versión o documento
417
+
418
+ Crea la carpeta de versión con su config y regístrala en \`VersionControl.versions\` con \`id\` y \`path\`. Añade una entrada \`routes-md\` con ID único y rutas por idioma; añade destinos correspondientes en el menú. Usa \`routeDefaults\` para valores compartidos por las rutas; los campos explícitos de la ruta tienen prioridad. Consulta Navegación para submenús y valores de \`RouteGuide\`.
419
+
420
+ Las opciones visuales son configuración pública. Nunca guardes credenciales de proveedor o claves privadas en el JSON del sitio. Los ejemplos de Rutas autorizadas muestran controles del cliente, no protección del servidor para archivos descargables.
421
+
422
+ La entrada \`QuickNavigation\` controla la apariencia de icono/texto del botón Ctrl+K. El atajo de teclado y el panel de búsqueda siguen disponibles.
300
423
  `,
301
- deployment: `# Publicacion
424
+ deployment: `# Publicación
425
+
426
+ Elige el visor oficial para un repositorio público, publica tu propio GitHub Pages o aloja un export estático compilado desde el runtime.
302
427
 
303
- Git Page Docs corre como app Next.js con dos objetivos: servidor local y GitHub Pages.
428
+ ## Visor oficial
304
429
 
305
- ## Publicacion local
430
+ Haz commit de la carpeta \`gitpagedocs/\` generada en tu repositorio público. Abre \`https://vidigal-code.github.io/git-page-docs/OWNER/REPOSITORY/\` y elige versión e idioma. El visor obtiene configuración y contenido del repositorio. Esta URL no convierte un repositorio privado en público.
306
431
 
307
- Usa:
432
+ ## Tu sitio en GitHub Pages
308
433
 
309
- 1. \`npm run build\`
310
- 2. \`npm start\`
434
+ Requisitos: repositorio Git, origin GitHub, permiso de push y GitHub CLI autenticado (\`gh auth login\`) cuando la CLI configura Pages.
311
435
 
312
- Esto inicia runtime Node + Next.js usando \`gitpagedocs/\` local.
436
+ \`\`\`bash
437
+ npx gitpagedocs pages deploy --owner OWNER --repo REPOSITORY
438
+ \`\`\`
313
439
 
314
- ## Publicacion en GitHub Pages
440
+ El flujo confirma el destino, genera docs y \`.github/workflows/gitpagedocs-pages.yml\`, hace commit y push y solicita GitHub Actions como fuente de Pages. Para cambiar solo la fuente, utiliza \`npx gitpagedocs pages actions\`. Para publicar en una subruta, pasa \`--path docs\`.
315
441
 
316
- En build de GitHub Actions:
442
+ Revisa GitHub Actions hasta que termine el despliegue; la URL impresa por la CLI puede aparecer antes de finalizar el build remoto. Los sitios de proyecto normalmente utilizan \`https://OWNER.github.io/REPOSITORY/\`; los sitios de usuario/organización utilizan la raíz del repositorio \`OWNER.github.io\`.
317
443
 
318
- - \`GITHUB_ACTIONS=true\`
319
- - el comportamiento de export estatico se habilita por configuracion
320
- - la pagina inicial de busqueda de repositorios queda activa
444
+ ## Contrato del build
321
445
 
322
- ## Flujo de publish del paquete
446
+ El workflow instala las dependencias del workspace con pnpm fijado, compila el visor y sube el artefacto estático mediante las actions oficiales de Pages. El job de despliegue necesita \`pages: write\`, \`id-token: write\` y el entorno \`github-pages\`.
323
447
 
324
- Para publicar en npm:
448
+ - \`GITHUB_ACTIONS=true\` activa el export estático de Next.js.
449
+ - \`GITHUB_REPOSITORY=OWNER/REPOSITORY\` determina la base del repositorio.
450
+ - \`GITPAGEDOCS_REPOSITORY_SEARCH=true\` activa el build de búsqueda inicial.
451
+ - \`GITPAGEDOCS_BASE_PATH\` sobrescribe explícitamente la base; \`GITPAGEDOCS_PATH\` define la subruta de docs.
452
+ - \`GITPAGEDOCS_DIST_DIR\` separa las salidas de build/dev para dos servidores locales.
325
453
 
326
- - actualiza version en \`package.json\`
327
- - ejecuta \`npm publish --access public\`
328
- - valida autenticacion con \`npm whoami\`
454
+ \`pnpm build\` sin el entorno de Pages produce un build de producción Next.js; por sí solo no verifica un export estático. Conserva \`.nojekyll\` al alojar el export en Pages.
329
455
 
330
- Si \`build:prebuilt\` se omite en Windows, usa CI para generar artefactos prebuilt.
456
+ ## Export independiente
457
+
458
+ En un checkout del runtime con dependencias instaladas, \`node cli/index.mjs --home --output gitpagedocshome --no-interactive\` compila \`frontend/\` y empaqueta una distribución estática. \`--search true\` activa la búsqueda inicial de repositorios. La salida incluye archivos estáticos, README, Dockerfile y ejemplo de entorno; la carpeta de destino se recrea. Un servidor estático sirve los archivos; cambiar una opción de entorno utilizada en el build requiere compilar de nuevo.
459
+
460
+ ## Releases npm para mantenedores
461
+
462
+ El monorepo publica \`@gitpagedocs/tools\`, \`@gitpagedocs/mcp\` y \`@gitpagedocs/cli\`; raíz y frontend son privados. El \`npm-publish.yml\` actual se ejecuta en pushes a \`main\` y omite una versión de CLI ya publicada. Utiliza el secret \`NPM_TOKEN\` del repositorio y publica workspaces en orden de dependencia. Crear solo una release de GitHub no es su disparador.
463
+
464
+ Sincroniza versiones y dependencias internas, regenera docs/baselines, ejecuta typecheck, lint, pruebas, smoke, build y Playwright y revisa antes del push. Confirma las tres versiones en npm y el resultado de Pages. La CLI de configuración ignora \`prebuilt/\`; el workflow de publicación no requiere esa carpeta.
331
465
  `,
332
466
  architecture: `# Arquitectura
333
467
 
@@ -472,6 +606,411 @@ Cada template normalmente incluye:
472
606
  - mantener contraste accesible
473
607
  - mantener escala consistente de espacios y bordes
474
608
  - ofrecer variantes dark y light cuando sea posible
609
+
610
+ ## Elegir y personalizar
611
+
612
+ Elige un tema mediante el selector o configura \`site.ThemeDefault\` con su ID exacto. \`ThemeModeDefault\` define el modo inicial claro/oscuro. \`HideThemeSelector\` oculta el selector; el tema seleccionado sigue aplicado.
613
+
614
+ En tu repositorio, ejecuta la CLI con \`--layoutconfig\`, edita la plantilla generada y conserva el ID coherente con \`layoutsConfig.json\`. El contenido de ruta y \`site.icons\` son independientes del catálogo de temas. Usa \`currentColor\` para iconos que heredan el color de texto o configura colores claros/oscuros con contraste suficiente.
615
+
616
+ Al contribuir en Git Page Docs, la fuente es \`gitpagelayouts/v2/base.json\` junto con \`gitpagelayouts/v2/layouts/<id>.json\`. Ejecuta \`pnpm layouts:sync\` para generar plantillas y documentación. La sincronización puede sobrescribir las ediciones directas de plantillas generadas.
617
+ `,
618
+ mcp: `# Servidor MCP
619
+
620
+ El servidor Model Context Protocol expone 20 tools y 7 resources mediante **stdio**. Se inicia como proceso hijo del cliente MCP. No abre un puerto HTTP ni ejecuta un daemon en segundo plano.
621
+
622
+ ## Instalar y conectar
623
+
624
+ Utiliza Node.js 20+. Instala la CLI en el proyecto con \`npm install --save-dev @gitpagedocs/cli\`; incluye el servidor y el runtime TypeScript. Una instalación global también permite \`gitpagedocs mcp start\`. Para una ejecución puntual, utiliza \`npx --yes @gitpagedocs/cli mcp start\`.
625
+
626
+ En VS Code, crea \`.vscode/mcp.json\` con la siguiente configuración. El directorio de trabajo del proceso es la raíz del proyecto; el comando MCP no tiene flags \`--root\` o \`--cwd\`.
627
+
628
+ \`\`\`json
629
+ {
630
+ "servers": {
631
+ "gitpagedocs": {
632
+ "type": "stdio",
633
+ "command": "node",
634
+ "args": [
635
+ "\${workspaceFolder}/node_modules/@gitpagedocs/cli/index.mjs",
636
+ "mcp",
637
+ "start"
638
+ ],
639
+ "cwd": "\${workspaceFolder}"
640
+ }
641
+ }
642
+ }
643
+ \`\`\`
644
+
645
+ Abre los controles del servidor MCP del cliente, inicia GitPageDocs y lista sus tools/resources. Prueba \`list_files\` con \`{"path":".","recursive":false}\` y lee \`project://readme\`. Estas operaciones no necesitan una clave de proveedor. Un terminal iniciado con \`mcp start\` espera JSON-RPC; el texto común en stdin no es un comando de chat. En un checkout del código, la entrada directa es \`node --import tsx mcp/src/bin.ts\`, no \`index.ts\`.
646
+
647
+ ## Configurar un proveedor
648
+
649
+ Las llamadas al proveedor leen credenciales del entorno del proceso MCP. MCP no carga \`.env\` ni la bóveda cifrada de la CLI automáticamente. Utiliza la función de entrada protegida/secretos del cliente para inyectar variables; nunca guardes claves reales en configuración versionada. Reinicia el proceso MCP después de cambiar su entorno.
650
+
651
+ Selecciona el proveedor con \`configure_ai_provider\` o con \`.gitpagedocs-mcp.json\` en la raíz del proyecto:
652
+
653
+ \`\`\`json
654
+ {
655
+ "provider": "ollama",
656
+ "model": "llama3"
657
+ }
658
+ \`\`\`
659
+
660
+ | Provider | Environment |
661
+ | --- | --- |
662
+ | \`openai\` | \`OPENAI_API_KEY\` |
663
+ | \`anthropic\` | \`ANTHROPIC_API_KEY / CLAUDE_API_KEY\` |
664
+ | \`gemini\` | \`GEMINI_API_KEY / GOOGLE_API_KEY\` |
665
+ | \`openrouter\` | \`OPENROUTER_API_KEY\` |
666
+ | \`ollama\` | \`OLLAMA_BASE_URL\` |
667
+ | \`azure-openai\` | \`AZURE_OPENAI_API_KEY + AZURE_OPENAI_BASE_URL\` |
668
+ | \`mistral\` | \`MISTRAL_API_KEY\` |
669
+ | \`deepseek\` | \`DEEPSEEK_API_KEY\` |
670
+ | \`cohere\` | \`COHERE_API_KEY\` |
671
+ | \`groq\` | \`GROQ_API_KEY\` |
672
+ | \`xai\` | \`XAI_API_KEY\` |
673
+ | \`together\` | \`TOGETHER_API_KEY\` |
674
+ | \`fireworks\` | \`FIREWORKS_API_KEY\` |
675
+ | \`perplexity\` | \`PERPLEXITY_API_KEY\` |
676
+
677
+ Sin una selección válida, el proveedor predeterminado es OpenAI. Ollama no requiere clave de API; el servicio local y el modelo elegido deben estar disponibles. \`OLLAMA_BASE_URL\` es opcional. La URL base de Azure es la URL completa de la operación de chat, incluido deployment y versión de API cuando sean necesarios. La lista de modelos es un catálogo distribuido, no una comprobación en tiempo real.
678
+
679
+ ## Referencia de tools
680
+
681
+ \`?\` indica un argumento opcional. Rutas y contenido son strings; \`recursive\` es booleano. Los identificadores de proveedor proceden del catálogo. Ejecuta las tools mediante la interfaz de herramientas del cliente MCP.
682
+
683
+ | Tool | Argumentos | Comportamiento |
684
+ | --- | --- | --- |
685
+ | \`list_files\` | \`path?, recursive?\` | Lista archivos (por defecto: directorio actual, sin recursión) |
686
+ | \`read_file\` | \`path\` | Lee texto UTF-8 |
687
+ | \`write_file\` | \`path, content\` | Escribe todo el archivo; crea carpetas necesarias |
688
+ | \`search_project\` | \`query, extension?\` | Busca por fragmento sin distinguir mayúsculas |
689
+ | \`list_ai_providers\` | \`—\` | Consulta el catálogo de proveedores |
690
+ | \`list_ai_models\` | \`provider?\` | Consulta el catálogo local de modelos |
691
+ | \`configure_ai_provider\` | \`provider, model?\` | Guarda .gitpagedocs-mcp.json |
692
+ | \`ask_ai\` | \`prompt, provider?, model?, system?\` | Devuelve una respuesta, sin historial de conversación |
693
+ | \`generate_documentation\` | \`path, provider?\` | Documenta un archivo fuente |
694
+ | \`generate_api_docs\` | \`path, provider?\` | Describe la API de un archivo |
695
+ | \`generate_database_docs\` | \`path, provider?\` | Describe modelos de datos de un archivo |
696
+ | \`analyze_source_code\` | \`path, provider?\` | Analiza un archivo fuente |
697
+ | \`generate_readme\` | \`provider?\` | Utiliza el árbol y package.json |
698
+ | \`generate_architecture_docs\` | \`provider?\` | Utiliza el árbol del repositorio |
699
+ | \`analyze_repository\` | \`provider?\` | Analiza el árbol del repositorio |
700
+ | \`analyze_project\` | \`provider?\` | Analiza el árbol y package.json |
701
+ | \`generate_changelog\` | \`provider?\` | Utiliza hasta 80 commits; utiliza el árbol si no están disponibles |
702
+ | \`generate_release_notes\` | \`provider?\` | Utiliza el mismo contexto del changelog |
703
+ | \`validate_docs\` | \`provider?\` | Solicita al proveedor una revisión del Markdown recopilado |
704
+ | \`update_documentation\` | \`path, instructions?, provider?\` | Genera y escribe una región administrada |
705
+
706
+ \`generate_*\`, \`analyze_*\`, \`ask_ai\` y \`validate_docs\` devuelven texto; no lo guardan automáticamente. \`validate_docs\` es una revisión del proveedor, no un verificador determinista de enlaces. Solo \`write_file\`, \`configure_ai_provider\` y \`update_documentation\` escriben archivos. \`update_documentation\` conserva texto fuera de \`<!-- gitpagedocs:start -->\` / \`<!-- gitpagedocs:end -->\`; agrega una región si no existe el par válido. El servidor no muestra confirmación propia; configura los permisos en el cliente MCP.
707
+
708
+ ## Referencia de resources
709
+
710
+ | URI | Contenido |
711
+ | --- | --- |
712
+ | \`project://structure\` | Árbol del repositorio |
713
+ | \`project://docs\` | Documentos Markdown recopilados |
714
+ | \`project://config\` | Configuración resuelta y sourcePath |
715
+ | \`project://repository\` | Contenido de package.json |
716
+ | \`project://readme\` | README.md |
717
+ | \`project://ai/providers\` | Catálogo de proveedores |
718
+ | \`project://ai/models\` | Catálogo de modelos por proveedor |
719
+
720
+ ## Ejemplo de uso
721
+
722
+ 1. Lee \`project://structure\` y \`project://readme\`.
723
+ 2. Ejecuta \`list_ai_providers\` y \`list_ai_models\` para elegir proveedor/modelo.
724
+ 3. Ejecuta \`generate_api_docs\` con \`{"path":"src/index.ts"}\` y revisa el texto devuelto.
725
+ 4. Guarda el texto aprobado con \`write_file\`, o utiliza \`update_documentation\` con \`{"path":"docs/api.md","instructions":"Documenta la API pública en español."}\` para una región administrada.
726
+
727
+ La generación envía el contenido seleccionado del proyecto al proveedor configurado.
728
+
729
+ ## Límites y diagnóstico
730
+
731
+ - Lectura de archivos: hasta 512.000 bytes. Listado: hasta 2.000 entradas; árboles recopilados del proyecto: 400 entradas.
732
+ - Búsqueda: hasta 5.000 entradas, 200 resultados y 240 caracteres por línea encontrada.
733
+ - Recopilación de documentación: primeros 40 archivos Markdown entre hasta 2.000 entradas; se omiten archivos superiores a 40.000 bytes. El contexto del proveedor se limita a 24.000 caracteres.
734
+ - El listado omite carpetas de dependencias/build como \`node_modules\`, \`.git\`, \`.next\`, \`out\`, \`dist\`, \`prebuilt\`, \`.turbo\` y \`coverage\`. No interpreta \`.gitignore\`; archivos como \`.env\` no se excluyen automáticamente. Ejecuta solo en proyectos de confianza y selecciona el contenido que se expondrá.
735
+ - La verificación de rutas es léxica; el proceso no es un sandbox del sistema operativo ni garantiza aislamiento de symlinks/junctions. Leer \`project://config\` puede importar configuración JavaScript/TypeScript.
736
+ - Los fallos de tools incluyen \`isError: true\`. Los resources ausentes devuelven \`Unavailable: ...\`. Revisa stderr en el cliente para errores de inicio; stdout está reservado para JSON-RPC.
737
+ - Si las tools funcionan pero la generación falla, comprueba selección del proveedor, credenciales del entorno, modelo y conectividad.
738
+ `,
739
+ cli: `# Referencia de la CLI
740
+
741
+ ## Comandos CLI
742
+
743
+ | Comando | Descripcion |
744
+ |---------|-------------|
745
+ | \`npx @gitpagedocs/cli\` | Genera config y docs en \`gitpagedocs/\` |
746
+ | \`npx @gitpagedocs/cli --layoutconfig\` | Tambien genera layouts/templates locales en \`gitpagelayouts/\` |
747
+ | \`npx @gitpagedocs/cli --home\` | Distribucion standalone (\`gitpagedocshome/\`) |
748
+ | \`npx @gitpagedocs/cli --push --owner X --repo Y\` | Configura workflow, commit, push |
749
+ | \`npx @gitpagedocs/cli --interactive\` / \`-i\` | Modo interactivo con prompts (por defecto en una terminal) |
750
+ | \`npx @gitpagedocs/cli --no-interactive\` / \`--yes\` / \`-y\` | Nunca pregunta; usa flags y valores por defecto |
751
+ | \`gitpagedocs ai\` | Generador interactivo de documentacion con IA |
752
+ | \`gitpagedocs chat [pregunta]\` | Chat de IA con streaming en la terminal (REPL en TTY; respuesta unica con pregunta o stdin) |
753
+ | \`gitpagedocs provider [id]\` / \`models [provider]\` | Lista proveedores de IA / modelos del catalogo |
754
+ | \`gitpagedocs document[:repo\\|:file\\|:folder]\` | Genera documentacion con IA |
755
+ | \`gitpagedocs deploy\` / \`pages [actions\\|deploy]\` | Configura GitHub Pages via Actions + push |
756
+ | \`gitpagedocs docs\` | Actualiza las regiones gestionadas de README/CONTRIBUTING/SECURITY |
757
+ | \`gitpagedocs password\` | Define la contrasena de acceso a la documentacion (clave publica en \`site.docsAccess\`) |
758
+ | \`gitpagedocs config\` / \`config clear\` | Muestra la config resuelta / borra la config guardada y la boveda de claves |
759
+ | \`gitpagedocs doctor\` / \`version\` / \`update\` | Diagnostico / version / comprobacion de actualizacion en el registro |
760
+ | \`gitpagedocs mcp start\` | Inicia el servidor MCP por stdio |
761
+
762
+ Instala globalmente con \`npm install -g @gitpagedocs/cli\` o ejecuta sin instalar con \`npx @gitpagedocs/cli\`.
763
+
764
+ ## Opciones CLI
765
+
766
+ | Opcion | Descripcion |
767
+ |--------|-------------|
768
+ | \`--owner <user>\` | Owner de GitHub |
769
+ | \`--repo <repo>\` | Repositorio GitHub |
770
+ | \`--path <subpath>\` | Subruta de docs (ej: \`docs\`); sin ella, base path = nombre del repo para CSS/JS en project sites |
771
+ | \`--output <dir>\` | Directorio de salida (default: \`gitpagedocs\`) |
772
+ | \`--search <true-or-false>\` | Habilita/deshabilita busqueda de repositorio (\`--home\`) |
773
+ | \`--layoutconfig\` | Genera layouts locales en \`gitpagelayouts/\` |
774
+ | \`--layouts-dir <dir>\` | Carpeta de layouts locales (por defecto: \`gitpagelayouts\`) |
775
+ | \`--push\` | Crea workflow, commit de artefactos, push |
776
+ | \`--pages-actions\` | Solo cambia la fuente de GitHub Pages a GitHub Actions (igual que \`pages actions\`) |
777
+ | \`--home\` | Genera \`gitpagedocshome/\` (estatico + .env + Dockerfile) |
778
+
779
+ ## Salida generada
780
+
781
+ - \`gitpagedocs/config.json\` – config raiz
782
+ - \`gitpagedocs/icon.svg\` – icono por defecto
783
+ - \`gitpagedocs/docs/versions/<ver>/config.json\` – rutas por version
784
+ - \`gitpagedocs/docs/versions/<ver>/{en,pt,es}/*.md\` – docs en markdown
785
+ - \`gitpagelayouts/\` – solo con \`--layoutconfig\` (carpeta configurable con \`--layouts-dir\`)
786
+
787
+ ## Ejemplos y límites de los comandos
788
+
789
+ \`\`\`bash
790
+ npx gitpagedocs --no-interactive --owner octocat --repo handbook
791
+ npx gitpagedocs --layoutconfig --layouts-dir assets/layouts --no-interactive
792
+ npx gitpagedocs chat "Explica este proyecto" --provider ollama --model llama3
793
+ npx gitpagedocs pages deploy --owner octocat --repo handbook --path docs
794
+ npx gitpagedocs mcp start
795
+ \`\`\`
796
+
797
+ - \`init\` es un alias de generación. \`providers\` equivale a \`provider\`; \`--version\` y \`-v\` equivalen a \`version\`.
798
+ - \`document\`, \`document:repo\`, \`document:file\`, \`document:folder\` y \`--ai\` seleccionan el flujo interactivo de documentación. Elige directorios en sus preguntas; estos alias no implementan una API separada de archivo/carpeta mediante argumento posicional.
799
+ - \`chat\` acepta \`--provider <id>\`, \`--model <id>\` y \`--system <prompt>\`. Con una pregunta o stdin responde una vez; un terminal interactivo sin pregunta inicia una conversación.
800
+ - \`--build\`, \`--serve\` y \`--full\` son flags de compatibilidad: el scaffold habitual sigue siendo solo configuración y no inician un servidor local.
801
+ - \`--home\` compila \`frontend/\` desde un checkout del runtime y escribe el export estático con archivos auxiliares. La carpeta de salida se recrea cuando no es \`.\`; conserva la documentación fuente fuera de ella. Instalar solo la CLI no proporciona \`frontend/\`.
802
+ - \`pages actions\` solo configura la fuente de Pages; \`pages deploy\` y \`--push\` generan, hacen commit y push. Una URL impresa no significa que el build remoto haya terminado: revisa GitHub Actions.
803
+ - \`update\` consulta npm e imprime un comando de instalación; no actualiza la CLI silenciosamente.
804
+
805
+ ## Configuración y credenciales
806
+
807
+ Las opciones visuales están en \`gitpagedocs/config.json\`. El generador interactivo/chat guarda \`.gitpagedocsconfig\` y su bóveda cifrada \`.gitpagedocsvault\` en la carpeta de configuración del usuario: \`%APPDATA%/gitpagedocs\` en Windows, \`~/Library/Application Support/gitpagedocs\` en macOS y la carpeta XDG en Linux. \`config clear\` elimina esa configuración y la bóveda. MCP utiliza \`.gitpagedocs-mcp.json\` en la raíz del proyecto y el entorno del proceso; consulta la página MCP.
808
+
809
+ \`gitpagedocs docs\` actualiza solo regiones delimitadas por marcadores en README.md, CONTRIBUTING.md y SECURITY.md, conservando el texto alrededor. \`password\` configura el par de claves de acceso a la documentación; los controles de presentación del cliente no vuelven confidenciales los archivos de un repositorio público.
810
+ `,
811
+ navigation: `# Navegación y submenús
812
+
813
+ Las rutas definen el contenido; los menús definen cómo encontrarlo. Configúralos en \`gitpagedocs/docs/versions/<version>/config.json\`. Las opciones visuales globales están en \`gitpagedocs/config.json\`.
814
+
815
+ \`\`\`json
816
+ {
817
+ "site": {
818
+ "nestedMenusEnabled": true,
819
+ "RouteGuide": true
820
+ }
821
+ }
822
+ \`\`\`
823
+
824
+ ## Crear el árbol de menús
825
+
826
+ Cada entrada de \`menus-header-md\` tiene \`id\` y objetos \`pt\`, \`en\`, \`es\` con \`title\` y \`path-click\` opcional. Añade \`submenus\` con nuevas entradas para anidar el árbol. El objeto de un idioma también acepta \`submenus\` localizados con título/ruta. Utiliza una forma de manera consistente para no listar el mismo hijo dos veces.
827
+
828
+ Los grupos sin \`path-click\` organizan sus hijos. Para un destino Markdown, utiliza su ruta localizada real de \`routes-md[].path\`. El alias \`page:<id>\` lo registran rutas source-viewer, vídeo, audio y PDF; no lo uses en una página que solo contiene Markdown. El ejemplo utiliza la versión \`0.0.8\`: sustituye ese segmento por la versión editada y crea los tres archivos chapter.
829
+
830
+ \`\`\`json
831
+ {
832
+ "routeDefaults": {
833
+ "RouteGuide": false
834
+ },
835
+ "routes-md": [
836
+ {
837
+ "id": 101,
838
+ "RouteGuide": true,
839
+ "path": {
840
+ "pt": "gitpagedocs/docs/versions/0.0.8/pt/chapter.md",
841
+ "en": "gitpagedocs/docs/versions/0.0.8/en/chapter.md",
842
+ "es": "gitpagedocs/docs/versions/0.0.8/es/chapter.md"
843
+ }
844
+ }
845
+ ],
846
+ "menus-header-md": [
847
+ {
848
+ "id": 900,
849
+ "pt": {
850
+ "title": "Guia"
851
+ },
852
+ "en": {
853
+ "title": "Guide"
854
+ },
855
+ "es": {
856
+ "title": "Guía"
857
+ },
858
+ "submenus": [
859
+ {
860
+ "id": 901,
861
+ "pt": {
862
+ "title": "Capítulos"
863
+ },
864
+ "en": {
865
+ "title": "Chapters"
866
+ },
867
+ "es": {
868
+ "title": "Capítulos"
869
+ },
870
+ "submenus": [
871
+ {
872
+ "id": 101,
873
+ "pt": {
874
+ "title": "Primeiro capítulo",
875
+ "path-click": "gitpagedocs/docs/versions/0.0.8/pt/chapter.md"
876
+ },
877
+ "en": {
878
+ "title": "First chapter",
879
+ "path-click": "gitpagedocs/docs/versions/0.0.8/en/chapter.md"
880
+ },
881
+ "es": {
882
+ "title": "Primer capítulo",
883
+ "path-click": "gitpagedocs/docs/versions/0.0.8/es/chapter.md"
884
+ }
885
+ }
886
+ ]
887
+ }
888
+ ]
889
+ }
890
+ ]
891
+ }
892
+ \`\`\`
893
+
894
+ ## Comportamiento del anidamiento
895
+
896
+ \`site.nestedMenusEnabled: true\` muestra menús recursivos expandibles. Puedes añadir \`submenus\` en cualquier nodo: no existe un límite fijo de profundidad en la aplicación. La configuración debe ser finita y adecuada para la memoria del navegador y la usabilidad. Con \`false\`, los destinos aparecen en una lista plana; las páginas anidadas no se eliminan.
897
+
898
+ El árbol sirve para navegación lateral, etiquetas de búsqueda, expansión de padres y rutas de navegación. Mantén IDs estables y sin ambigüedad; los destinos protegidos siguen las reglas de autorización de su página. La misma estructura se aplica a \`menus-header-source-viewer\`, \`menus-header-html\`, \`menus-header-video\`, \`menus-header-audio\` y \`menus-header-pdf\`. \`hierarchyMenu\` ordena las secciones por tipo; \`hierarchyPage\` ordena los contenedores que comparten el ID de página.
899
+
900
+ ## Ruta de navegación: RouteGuide
901
+
902
+ \`RouteGuide\` controla los breadcrumbs. La prioridad es \`routes-md[].RouteGuide\` de la página, después \`routeDefaults.RouteGuide\` de la versión, después \`site.RouteGuide\`, con \`true\` como valor final por defecto. El ejemplo desactiva la ruta de navegación para la versión y la activa en el capítulo 101. Los archivos existentes de la versión \`0.0.8\` aceptan los mismos campos.
903
+
904
+ \`RouteguideBrand\` y \`RouteguideBrandPosition\` son opciones separadas del índice de títulos del documento; no controlan los breadcrumbs.
905
+
906
+ ## URLs y anterior/siguiente
907
+
908
+ Las URLs versionadas utilizan \`/v/<version>/\`; \`?lang=pt\` elige el idioma y \`?id=101\` elige la página. \`?name=chapter\` selecciona el slug del documento. Mantén \`VersionControl.versions[].path\` apuntando al config de la versión correspondiente. \`site.ActiveNavigation\` activa anterior/siguiente habitual; la navegación entre documentos en modo foco tiene su propia opción. Consulta Modo foco para controles de sección y documento.
909
+
910
+ Prueba un menú nuevo desde la barra lateral, por URL directa y en cada idioma habilitado; confirma que el destino existe y está permitido para el lector actual.
911
+ `,
912
+ focusMode: `# Modo foco
913
+
914
+ El modo foco abre el documento Markdown actual en un diálogo de lectura. Actívalo con \`site.FocusMode\`; el control solo está disponible para una página Markdown real. \`site.icons.FocusMode\` cambia la apariencia de icono/texto y no activa ni desactiva la función.
915
+
916
+ ## Configurar los controles
917
+
918
+ Combina este fragmento con \`gitpagedocs/config.json\`:
919
+
920
+ \`\`\`json
921
+ {
922
+ "site": {
923
+ "FocusMode": true,
924
+ "focusMode": {
925
+ "copyEnabled": true,
926
+ "downloadEnabled": true,
927
+ "sectionNavigationEnabled": true,
928
+ "documentNavigationEnabled": true
929
+ }
930
+ }
931
+ }
932
+ \`\`\`
933
+
934
+ Cada opción tiene valor predeterminado \`true\`; \`false\` oculta su control correspondiente. Con \`sectionNavigationEnabled: false\`, el modo foco muestra el documento completo sin paginación por secciones. Las configuraciones existentes sin el nuevo objeto \`focusMode\` mantienen los controles activados.
935
+
936
+ ## Secciones y documentos
937
+
938
+ - Los controles anterior/siguiente de flecha simple cambian de sección en el mismo documento.
939
+ - Los controles anterior/siguiente de flecha doble cambian de documento Markdown en orden de menú, incluidos los submenús.
940
+ - Se omiten documentos sin traducción en el idioma activo, destinos que no son Markdown y páginas sin permiso.
941
+ - Cambiar de documento mantiene abierto el diálogo y vuelve a la primera sección. Los contadores de sección/documento muestran la posición actual.
942
+ - \`site.ActiveNavigation\` controla la navegación habitual de la página; no desactiva la navegación de documentos en modo foco.
943
+
944
+ ## Copiar y descargar
945
+
946
+ Copiar y descargar utilizan el **Markdown original completo en el idioma seleccionado**, incluidas las secciones que no están visibles. No exportan el HTML renderizado ni solo la sección actual.
947
+
948
+ La descarga conserva el nombre base Markdown del \`path\` localizado de la ruta; si no está disponible, el nombre del archivo es \`document.md\`. El portapapeles sigue las reglas de permisos y contexto seguro del navegador. Si la copia falla, utiliza la descarga y consulta el error mostrado.
949
+
950
+ ## Teclado y lectura
951
+
952
+ El diálogo tiene nombre accesible, gestión de foco del teclado y control de cierre. Usa Tab para recorrer controles y Escape para cerrar. Los controles de solo icono conservan nombres traducidos accesibles. Cerrar el diálogo vuelve a la documentación.
953
+
954
+ La narración se configura por separado en Accesibilidad. Cambiar de documento o idioma cancela la narración anterior para que no siga leyendo contenido antiguo.
955
+ `,
956
+ accessibility: `# Accesibilidad y narración
957
+
958
+ Los controles de accesibilidad incluyen narración nativa del navegador para el documento Markdown actual. La narración utiliza Web Speech API (\`speechSynthesis\`); no necesita clave de API ni un servicio externo de voz de GitPageDocs.
959
+
960
+ ## Configuración
961
+
962
+ Combina estas opciones con \`gitpagedocs/config.json\`:
963
+
964
+ \`\`\`json
965
+ {
966
+ "site": {
967
+ "accessibility": {
968
+ "enabled": true,
969
+ "narration": {
970
+ "enabled": true,
971
+ "defaultRate": 1,
972
+ "defaultVolume": 1
973
+ }
974
+ },
975
+ "mediaExclusivePlayback": true
976
+ }
977
+ }
978
+ \`\`\`
979
+
980
+ - \`site.accessibility.enabled\`: activa la interfaz de accesibilidad.
981
+ - \`site.accessibility.narration.enabled\`: activa la narración del documento.
982
+ - \`defaultRate\`: velocidad inicial de \`0.5\` a \`2\`, en pasos de \`0.25\`; el valor predeterminado es \`1\`.
983
+ - \`defaultVolume\`: volumen inicial de \`0\` (silencio) a \`1\` (máximo), en pasos de \`0.1\`; el valor predeterminado es \`1\`.
984
+ - Todos los controles de activación tienen valor predeterminado \`true\`; las opciones ausentes usan los valores distribuidos.
985
+
986
+ ## Leer un documento en voz alta
987
+
988
+ 1. Abre una página Markdown y los controles de accesibilidad/narración.
989
+ 2. Elige voz e idioma entre los que ofrece el navegador; ajusta velocidad y volumen.
990
+ 3. Inicia la lectura. Pausa temporalmente, reanuda la voz pausada o detén la sesión.
991
+ 4. Para cambiar opciones de lectura de manera previsible, detén, ajusta los controles e inicia de nuevo.
992
+
993
+ La narración empieza solo después de tu acción; no hay reproducción automática. La selección automática de voz sigue el idioma del documento; elegir una voz explícitamente utiliza el idioma de esa voz. La narración no traduce el documento.
994
+
995
+ La voz utiliza texto legible extraído del Markdown renderizado. Se excluyen scripts, estilos, contenido SVG y elementos ocultos para tecnologías de asistencia. Los documentos largos se leen completos en bloques sucesivos. Cambiar de documento o idioma, desactivar la narración o salir de la página cancela la voz anterior.
996
+
997
+ La vista habitual y el modo foco comparten preferencias de voz, velocidad y volumen mientras la página permanece montada. Las preferencias no se guardan entre recargas. Los valores no numéricos de velocidad o volumen usan \`1\`; los valores numéricos fuera de los rangos admitidos se limitan al extremo más cercano.
998
+
999
+ ## Un audio a la vez
1000
+
1001
+ Con \`site.mediaExclusivePlayback: true\` (por defecto), iniciar o reanudar la narración pausa radio, pistas de audio y vídeos de ruta. Iniciar esos medios detiene la narración. Los vídeos silenciados quedan fuera de la regla. Utiliza \`false\` cuando la reproducción simultánea sea intencional.
1002
+
1003
+ La configuración se comparte con la reproducción de medios existente; no hay una segunda flag de exclusividad para narración. La página sigue siendo legible con la narración desactivada.
1004
+
1005
+ ## Disponibilidad del navegador y las voces
1006
+
1007
+ El soporte de voz y las voces dependen del navegador, sistema operativo y voces instaladas o proporcionadas remotamente. La lista puede llegar después de cargar la página. Distintos navegadores y dispositivos pueden ofrecer idiomas diferentes.
1008
+
1009
+ La falta de soporte y los errores de reproducción se muestran en la interfaz. Comprueba que haya una voz utilizable, que el audio del sistema esté activo y que exista una interacción del usuario con la página. Una lista vacía de voces no indica que el documento no se haya cargado.
1010
+
1011
+ No supongas que todas las voces funcionan sin conexión: pueden ser locales o remotas. Esta función habla texto; no graba el micrófono. La narración complementa la navegación por teclado y los lectores de pantalla, sin sustituirlos.
1012
+
1013
+ Consulta la [referencia de Web Speech API](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis) para el comportamiento del navegador.
475
1014
  `,
476
1015
  faq: `# FAQ
477
1016
 
@@ -502,5 +1041,25 @@ Verifica:
502
1041
  ## Por que GitHub Pages puede comportarse distinto a local?
503
1042
 
504
1043
  Porque el build de GitHub Pages habilita la pagina inicial de busqueda y comportamiento especifico de exportacion.
1044
+
1045
+ ## ¿Por qué el icono sigue mostrando texto?
1046
+
1047
+ Define \`site.icons.<Control>.reactIcon\` como booleano \`true\`, con el nombre exacto exportado por React Icons en \`tag\`. Los controles incluyen LanguageSelector, ThemeSelector, FocusMode y QuickNavigation. Los campos planos \`Icon*ReactIcones\` tienen prioridad si existen ambos formatos. Comprueba si la propia función está desactivada mediante \`HideThemeSelector\` o \`FocusMode\`.
1048
+
1049
+ ## ¿Por qué los hijos del menú o breadcrumbs son diferentes?
1050
+
1051
+ \`nestedMenusEnabled: false\` aplana los destinos intencionalmente. Revisa \`submenus\`, objetos de idioma y \`path-click\`; confirma que las páginas existan y sean accesibles. Los breadcrumbs utilizan \`RouteGuide\`, con prioridad ruta > versión > sitio. \`RouteguideBrand\` controla el índice de títulos.
1052
+
1053
+ ## ¿Por qué la narración está muda o se interrumpe?
1054
+
1055
+ Comprueba soporte del navegador, voz disponible, idioma, volumen y salida de audio. Las voces pueden cargar después o requerir un servicio remoto. Con \`mediaExclusivePlayback: true\`, otra fuente de audio/vídeo detiene la narración por diseño. Cambiar de documento cancela la voz anterior. Consulta Accesibilidad.
1056
+
1057
+ ## ¿Por qué MCP espera o falla una tool?
1058
+
1059
+ \`mcp start\` espera un cliente MCP por stdio; no es un chat de terminal. Comprueba cwd y utiliza la entrada de CLI publicada o \`mcp/src/bin.ts\`. Las tools de archivos/catálogo no necesitan proveedor; la generación requiere credenciales en el entorno del proceso MCP. La bóveda de CLI y \`.env\` no se cargan automáticamente; revisa \`isError\` y stderr del cliente.
1060
+
1061
+ ## ¿Por qué regenerar cambió mis páginas?
1062
+
1063
+ El scaffold vuelve a escribir rutas, configs y documentación generada. Revisa Git y conserva el contenido específico en sus fuentes. En este repositorio, edita \`cli/content/docs-{en,pt,es}.mjs\` y los metadatos de rutas antes de regenerar; no uses las copias generadas como única fuente.
505
1064
  `,
506
1065
  };