Skip to content

Commit e500c00

Browse files
Vidigal-codeVidigal-code
committed
chore(release): 0.0.10 - reading controls and HTML examples
Use configurable icons for header, PDF and document navigation controls. Keep native narration synchronized and improve narrow-screen layouts. Add eight focus navigation actions and preserve Unicode document headings. Document nested menus and ship a localized HTML DOOM example with a keyboard-friendly player, complete HTML route examples and expanded guides. Validate types, lint, unit tests, browser flows, CLI/MCP smoke tests, package contents, static export and per-file code analysis.
1 parent 7dd3bf6 commit e500c00

392 files changed

Lines changed: 25409 additions & 1487 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CONTRIBUTING.md‎

Lines changed: 40 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -34,12 +34,18 @@ This is a pnpm + turbo monorepo: `frontend/` (Next.js viewer), `cli/` (the publi
3434

3535
### User references
3636

37-
The generated versioned documentation includes dedicated pages for configuration, CLI, MCP, recursive navigation, focus mode, accessibility/narration, PDF documents, deployment, architecture, themes and troubleshooting. Each page is available in English, Portuguese and Spanish; Markdown filenames stay in English across languages.
37+
The generated documentation includes 23 Markdown pages per language: focused references plus complete configuration recipes, migration/compatibility, troubleshooting, contributing/testing and HTML-container guides. All pages are available in English, Portuguese and Spanish; Markdown filenames stay in English while titles and content preserve UTF-8 accents and special characters.
3838

39-
Configure language, theme, focus and Ctrl+K control icons through `gitpagedocs/config.json` → `site.icons`. Set `reactIcon` independently on `LanguageSelector`, `ThemeSelector`, `FocusMode` and `QuickNavigation`; `false` keeps the text controls. Customize `tag`, `size`, `colorDark` and `colorLight` per entry.
39+
The scaffold has real nested sections: Guides → Configure your site / Read and explore / Automate and integrate → documents, plus Operations and development and Git/GitHub groups. Getting Started and Project overview remain the first destinations. Recursive `submenus` can extend the hierarchy without a fixed depth limit; `site.nestedMenusEnabled: false` keeps every destination in a flat presentation.
40+
41+
Configure controls through `gitpagedocs/config.json` → `site.icons`. `LanguageSelector`, `ThemeSelector`, `FocusMode`, `QuickNavigation`, `PdfDownload`, `PdfOpenInNewTab`, `DocumentPrevious` and `DocumentNext` use icons by default. Set `reactIcon: false` independently to display text; `true` displays the icon. Customize `tag`, `size`, `colorDark` and `colorLight` per entry. Compact configs inherit omitted values from `icons.defaults`, so an omitted per-control `reactIcon` does not mean text mode. The Ctrl+K shortcut and accessible control names remain available.
4042

4143
`site.nestedMenusEnabled` selects recursive or flat navigation. Breadcrumbs use `RouteGuide` with route > version defaults > site precedence. `site.FocusMode` enables reading mode; `site.focusMode` controls copy, download, section navigation and document navigation independently.
4244

45+
Focus mode provides eight navigation buttons: first, previous, next and last document, plus first, previous, next and last section. Each navigation flag controls its group of four; document changes keep the reader open and restart at the first section.
46+
47+
Document-footer controls use `DocumentPrevious` (`FiChevronLeft`) and `DocumentNext` (`FiChevronRight`); either can use its translated text with `reactIcon: false`. The footer appears for multiple available menu destinations and disables unavailable directions. `site.ActiveNavigation` controls quick navigation and Ctrl+K separately.
48+
4349
`site.accessibility.narration` configures native browser reading. Voices and offline availability depend on the browser and operating system. `site.mediaExclusivePlayback` coordinates narration, radio, audio and video so only one audible source plays by default.
4450

4551
See [the MCP reference](mcp/README.md) for installation, client configuration, all 20 tools, all 7 resources, provider variables and limits. Start with `gitpagedocs mcp start` from the target project; on a source checkout the direct entry is `node --import tsx mcp/src/bin.ts`.
@@ -51,8 +57,38 @@ Read or download the [GitPageDocs project guide (PDF, English)](cli/content/asse
5157
Configure `site.pdf` with `enabled`, `previewEnabled`, `downloadEnabled` and `openInNewTabEnabled` (all default to `true`). The version config uses `routes-pdf`, `pdf.pathPdf` per language and `menus-header-pdf` with `page:23` for the bundled example. Route-level preview/download/new-tab options go inside `pdf`; `hierarchyPage.pdf` and `hierarchyMenu.pdf` order the content and menu sections.
5258

5359
```json
54-
{ "id": 23, "pdf": { "pathPdf": { "en": "gitpagedocs/docs/versions/0.0.9/en/gitpagedocs-project-guide.pdf", "pt": "gitpagedocs/docs/versions/0.0.9/en/gitpagedocs-project-guide.pdf", "es": "gitpagedocs/docs/versions/0.0.9/en/gitpagedocs-project-guide.pdf" }, "previewEnabled": true, "downloadEnabled": true, "openInNewTabEnabled": true } }
60+
{ "id": 23, "pdf": { "pathPdf": { "en": "gitpagedocs/docs/versions/0.0.10/en/gitpagedocs-project-guide.pdf", "pt": "gitpagedocs/docs/versions/0.0.10/en/gitpagedocs-project-guide.pdf", "es": "gitpagedocs/docs/versions/0.0.10/en/gitpagedocs-project-guide.pdf" }, "previewEnabled": true, "downloadEnabled": true, "openInNewTabEnabled": true } }
61+
```
62+
63+
The native browser viewer handles PDF previews and new tabs through validated `application/pdf` Blob URLs. Preview, download and new-tab actions all require CORS permission for external files. Opening a new tab does not navigate to the raw repository URL, so that server's Content-Type/Content-Disposition does not force a download. Browser PDF support and user preferences still apply. With preview disabled, the first download or new-tab action loads the PDF; cached bytes are reused. File/network errors and blocked pop-ups are reported without silently falling back to the raw URL.
64+
65+
PDF action icons are independent: `site.icons.PdfDownload` defaults to `FiDownload`, and `site.icons.PdfOpenInNewTab` defaults to `FiExternalLink`. For example, `"PdfDownload": { "reactIcon": false }` shows download text while the new-tab control remains an icon. The `site.pdf` and route `pdf` action flags control availability separately from appearance.
66+
67+
Next.js dev/build stages repository PDFs from `gitpagedocs/` into public assets and respects the Pages subpath; other local files must be in `frontend/public/`. See the generated PDF documents page for complete site, route, menu and icon examples.
68+
69+
### HTML containers and the DOOM example
70+
71+
The scaffold includes a local HTML demonstration with a title, description and an explicit load button for the externally hosted DOOM player. Game assets are not bundled. The wrapper is generated as `docs/versions/<version>/{en,pt,es}/doom.html`; the HTML containers guide explains sizing, external URLs and browser restrictions.
72+
73+
Keep both `routes-html` and `menus-header-html` in the version configuration. Menu paths must match the localized HTML paths; local HTML does not use a `page:29` alias. Merge this example with existing arrays:
74+
75+
```json
76+
{
77+
"routes-html": [{
78+
"id": 29,
79+
"title": { "en": "DOOM: HTML example", "pt": "DOOM: exemplo HTML", "es": "DOOM: ejemplo HTML" },
80+
"description": { "en": "Load an interactive HTML demo", "pt": "Carregue uma demonstração HTML interativa", "es": "Carga una demostración HTML interactiva" },
81+
"titleIsVisible": true, "descriptionIsVisible": true, "container": "full",
82+
"path": { "en": "gitpagedocs/docs/versions/0.0.10/en/doom.html", "pt": "gitpagedocs/docs/versions/0.0.10/pt/doom.html", "es": "gitpagedocs/docs/versions/0.0.10/es/doom.html" }
83+
}],
84+
"menus-header-html": [{
85+
"id": 29,
86+
"en": { "title": "DOOM: HTML example", "path-click": "gitpagedocs/docs/versions/0.0.10/en/doom.html" },
87+
"pt": { "title": "DOOM: exemplo HTML", "path-click": "gitpagedocs/docs/versions/0.0.10/pt/doom.html" },
88+
"es": { "title": "DOOM: ejemplo HTML", "path-click": "gitpagedocs/docs/versions/0.0.10/es/doom.html" }
89+
}]
90+
}
5591
```
5692

57-
The native browser viewer handles PDF previews through temporary Blob URLs after the file signature is validated. Both preview and download require CORS permission when the file comes from another origin. The new-tab link opens the original URL directly, where browser support and the server's Content-Type/Content-Disposition can cause a download instead of inline display. Next.js dev/build stages repository PDFs from `gitpagedocs/` into public assets and respects the Pages subpath; other local files must be in `frontend/public/`. See the generated PDF documents page for complete site, route and menu examples.
93+
Select the HTML menu entry and press its load button, then use the player's controls. Internet access and a compatible browser are required. The direct provider link remains available if embedding fails. Only publish trusted HTML: the existing iframe permits scripts and same-origin content. Test keyboard access, mobile layout and the actual deployed Pages URL; external availability and framing policies remain controlled by the provider.
5894
<!-- gitpagedocs:end -->

‎README.md‎

Lines changed: 41 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -392,7 +392,7 @@ All routes for accessing documentation files on the official site or self-hosted
392392
| `id` | route id (e.g. `1`, `2`) | Navigate to page by route id |
393393
| `name` | slug (e.g. `getting-started`) | Navigate to page by filename slug |
394394
| `mdfull` | `en`, `pt`, `es` | Markdown fullscreen mode |
395-
| `htmlfull` | `en`, `pt`, `es` | HTML fullscreen mode (needs a `routes-html` entry in the version config; this repository defines none) |
395+
| `htmlfull` | `en`, `pt`, `es` | HTML fullscreen mode for a `routes-html` entry; the scaffold includes the localized DOOM example (route 29) |
396396
| `file` | path (with `mdfull` or `htmlfull`) | File to show in fullscreen |
397397
| `videofull` | `en`, `pt`, `es` | Video fullscreen mode |
398398
| `audiofull` | `en`, `pt`, `es` | Audio fullscreen mode |
@@ -886,12 +886,18 @@ ISC. See [repository](https://github.com/Vidigal-code/git-page-docs) for details
886886

887887
### User references
888888

889-
The generated versioned documentation includes dedicated pages for configuration, CLI, MCP, recursive navigation, focus mode, accessibility/narration, PDF documents, deployment, architecture, themes and troubleshooting. Each page is available in English, Portuguese and Spanish; Markdown filenames stay in English across languages.
889+
The generated documentation includes 23 Markdown pages per language: focused references plus complete configuration recipes, migration/compatibility, troubleshooting, contributing/testing and HTML-container guides. All pages are available in English, Portuguese and Spanish; Markdown filenames stay in English while titles and content preserve UTF-8 accents and special characters.
890890

891-
Configure language, theme, focus and Ctrl+K control icons through `gitpagedocs/config.json` → `site.icons`. Set `reactIcon` independently on `LanguageSelector`, `ThemeSelector`, `FocusMode` and `QuickNavigation`; `false` keeps the text controls. Customize `tag`, `size`, `colorDark` and `colorLight` per entry.
891+
The scaffold has real nested sections: Guides → Configure your site / Read and explore / Automate and integrate → documents, plus Operations and development and Git/GitHub groups. Getting Started and Project overview remain the first destinations. Recursive `submenus` can extend the hierarchy without a fixed depth limit; `site.nestedMenusEnabled: false` keeps every destination in a flat presentation.
892+
893+
Configure controls through `gitpagedocs/config.json` → `site.icons`. `LanguageSelector`, `ThemeSelector`, `FocusMode`, `QuickNavigation`, `PdfDownload`, `PdfOpenInNewTab`, `DocumentPrevious` and `DocumentNext` use icons by default. Set `reactIcon: false` independently to display text; `true` displays the icon. Customize `tag`, `size`, `colorDark` and `colorLight` per entry. Compact configs inherit omitted values from `icons.defaults`, so an omitted per-control `reactIcon` does not mean text mode. The Ctrl+K shortcut and accessible control names remain available.
892894

893895
`site.nestedMenusEnabled` selects recursive or flat navigation. Breadcrumbs use `RouteGuide` with route > version defaults > site precedence. `site.FocusMode` enables reading mode; `site.focusMode` controls copy, download, section navigation and document navigation independently.
894896

897+
Focus mode provides eight navigation buttons: first, previous, next and last document, plus first, previous, next and last section. Each navigation flag controls its group of four; document changes keep the reader open and restart at the first section.
898+
899+
Document-footer controls use `DocumentPrevious` (`FiChevronLeft`) and `DocumentNext` (`FiChevronRight`); either can use its translated text with `reactIcon: false`. The footer appears for multiple available menu destinations and disables unavailable directions. `site.ActiveNavigation` controls quick navigation and Ctrl+K separately.
900+
895901
`site.accessibility.narration` configures native browser reading. Voices and offline availability depend on the browser and operating system. `site.mediaExclusivePlayback` coordinates narration, radio, audio and video so only one audible source plays by default.
896902

897903
See [the MCP reference](mcp/README.md) for installation, client configuration, all 20 tools, all 7 resources, provider variables and limits. Start with `gitpagedocs mcp start` from the target project; on a source checkout the direct entry is `node --import tsx mcp/src/bin.ts`.
@@ -903,8 +909,38 @@ Read or download the [GitPageDocs project guide (PDF, English)](cli/content/asse
903909
Configure `site.pdf` with `enabled`, `previewEnabled`, `downloadEnabled` and `openInNewTabEnabled` (all default to `true`). The version config uses `routes-pdf`, `pdf.pathPdf` per language and `menus-header-pdf` with `page:23` for the bundled example. Route-level preview/download/new-tab options go inside `pdf`; `hierarchyPage.pdf` and `hierarchyMenu.pdf` order the content and menu sections.
904910

905911
```json
906-
{ "id": 23, "pdf": { "pathPdf": { "en": "gitpagedocs/docs/versions/0.0.9/en/gitpagedocs-project-guide.pdf", "pt": "gitpagedocs/docs/versions/0.0.9/en/gitpagedocs-project-guide.pdf", "es": "gitpagedocs/docs/versions/0.0.9/en/gitpagedocs-project-guide.pdf" }, "previewEnabled": true, "downloadEnabled": true, "openInNewTabEnabled": true } }
912+
{ "id": 23, "pdf": { "pathPdf": { "en": "gitpagedocs/docs/versions/0.0.10/en/gitpagedocs-project-guide.pdf", "pt": "gitpagedocs/docs/versions/0.0.10/en/gitpagedocs-project-guide.pdf", "es": "gitpagedocs/docs/versions/0.0.10/en/gitpagedocs-project-guide.pdf" }, "previewEnabled": true, "downloadEnabled": true, "openInNewTabEnabled": true } }
913+
```
914+
915+
The native browser viewer handles PDF previews and new tabs through validated `application/pdf` Blob URLs. Preview, download and new-tab actions all require CORS permission for external files. Opening a new tab does not navigate to the raw repository URL, so that server's Content-Type/Content-Disposition does not force a download. Browser PDF support and user preferences still apply. With preview disabled, the first download or new-tab action loads the PDF; cached bytes are reused. File/network errors and blocked pop-ups are reported without silently falling back to the raw URL.
916+
917+
PDF action icons are independent: `site.icons.PdfDownload` defaults to `FiDownload`, and `site.icons.PdfOpenInNewTab` defaults to `FiExternalLink`. For example, `"PdfDownload": { "reactIcon": false }` shows download text while the new-tab control remains an icon. The `site.pdf` and route `pdf` action flags control availability separately from appearance.
918+
919+
Next.js dev/build stages repository PDFs from `gitpagedocs/` into public assets and respects the Pages subpath; other local files must be in `frontend/public/`. See the generated PDF documents page for complete site, route, menu and icon examples.
920+
921+
### HTML containers and the DOOM example
922+
923+
The scaffold includes a local HTML demonstration with a title, description and an explicit load button for the externally hosted DOOM player. Game assets are not bundled. The wrapper is generated as `docs/versions/<version>/{en,pt,es}/doom.html`; the HTML containers guide explains sizing, external URLs and browser restrictions.
924+
925+
Keep both `routes-html` and `menus-header-html` in the version configuration. Menu paths must match the localized HTML paths; local HTML does not use a `page:29` alias. Merge this example with existing arrays:
926+
927+
```json
928+
{
929+
"routes-html": [{
930+
"id": 29,
931+
"title": { "en": "DOOM: HTML example", "pt": "DOOM: exemplo HTML", "es": "DOOM: ejemplo HTML" },
932+
"description": { "en": "Load an interactive HTML demo", "pt": "Carregue uma demonstração HTML interativa", "es": "Carga una demostración HTML interactiva" },
933+
"titleIsVisible": true, "descriptionIsVisible": true, "container": "full",
934+
"path": { "en": "gitpagedocs/docs/versions/0.0.10/en/doom.html", "pt": "gitpagedocs/docs/versions/0.0.10/pt/doom.html", "es": "gitpagedocs/docs/versions/0.0.10/es/doom.html" }
935+
}],
936+
"menus-header-html": [{
937+
"id": 29,
938+
"en": { "title": "DOOM: HTML example", "path-click": "gitpagedocs/docs/versions/0.0.10/en/doom.html" },
939+
"pt": { "title": "DOOM: exemplo HTML", "path-click": "gitpagedocs/docs/versions/0.0.10/pt/doom.html" },
940+
"es": { "title": "DOOM: ejemplo HTML", "path-click": "gitpagedocs/docs/versions/0.0.10/es/doom.html" }
941+
}]
942+
}
907943
```
908944

909-
The native browser viewer handles PDF previews through temporary Blob URLs after the file signature is validated. Both preview and download require CORS permission when the file comes from another origin. The new-tab link opens the original URL directly, where browser support and the server's Content-Type/Content-Disposition can cause a download instead of inline display. Next.js dev/build stages repository PDFs from `gitpagedocs/` into public assets and respects the Pages subpath; other local files must be in `frontend/public/`. See the generated PDF documents page for complete site, route and menu examples.
945+
Select the HTML menu entry and press its load button, then use the player's controls. Internet access and a compatible browser are required. The direct provider link remains available if embedding fails. Only publish trusted HTML: the existing iframe permits scripts and same-origin content. Test keyboard access, mobile layout and the actual deployed Pages URL; external availability and framing policies remain controlled by the provider.
910946
<!-- gitpagedocs:end -->

‎cli/builders/config-orchestrator.mjs‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
import { LAYOUTS, FALLBACK_LAYOUTS } from "../data/layouts.mjs";
44
import { DOCS } from "../content/docs.mjs";
5+
import { HTML_DOOM } from "../content/html-doom.mjs";
56
import { DOC_VERSIONS } from "../data/version-constants.mjs";
67
import { buildRootConfig } from "./root-config-builder.mjs";
78
import { buildVersionConfig } from "./version-config-builder.mjs";
@@ -29,7 +30,7 @@ export function buildConfigArtifacts(options = {}) {
2930
layoutsConfig,
3031
fallbackLayoutsConfig,
3132
docs: DOCS,
32-
docsHtml: {},
33+
docsHtml: { doom: HTML_DOOM },
3334
versionConfigs,
3435
};
3536
}

0 commit comments

Comments
 (0)