feat(config): compact gitpagedocs config without repeated values

- config.json stores the header icons as site.icons (defaults + one entry per
  icon with its tag and differences) instead of 279 flat Icon* keys
  (16 KB -> 5.4 KB); version configs keep the settings every route shares in
  routeDefaults (26.5 KB -> 18.5 KB).
- New browser-safe @gitpagedocs/tools/config-format with inverse pairs
  compactSiteIcons/expandSiteIcons and factorRouteDefaults/applyRouteDefaults.
  The generator compacts on write; the viewer expands in withConfigDefaults and
  in both version-config readers (shared browser-safe expandVersionConfig); the
  site baseline stays flat.
- Flat 0.0.x configs keep working; a flat key or a value on a route wins over
  the compact form. Input that is not an object is returned as is.
- Round-trip tests over the generated files, viewer tests for both formats,
  docs templates (en/pt/es), README and CHANGELOG describe the format.

Author: Vidigal-code

CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to Git Page Docs are documented here. Versions follow semver
 
 ## Unreleased
 
+### Compact gitpagedocs config (no repeated values)
+
+- `gitpagedocs/config.json` stores the header icons as `site.icons` (`defaults` + one entry per icon
+  with its `tag` and differences) instead of 279 flat `Icon*` keys: 16 KB -> 5.4 KB.
+- Version configs store the settings every route shares once in `routeDefaults`: 26.5 KB -> 18.5 KB
+  for the shipped version.
+- New browser-safe `@gitpagedocs/tools/config-format` (`compactSiteIcons` / `expandSiteIcons`,
+  `factorRouteDefaults` / `applyRouteDefaults`): the generator compacts on write, the viewer expands in
+  `withConfigDefaults` and in both version-config readers, and the site baseline stays flat. Flat
+  0.0.x configs keep working; a flat key or a value on a route wins over the compact form. Round-trip
+  tests guard that expanding a compacted config gives back exactly the original.
+
 ### Introduction guide motion
 
 - `/introduction-guide` gains scroll motion built with Motion for React (`motion` 13, `LazyMotion` +

README.md

@@ -289,6 +289,28 @@ Behavior:
 - If `layoutsConfigPathOficial=true`, runtime prefers official layout/template sources.
 - If `layoutsConfigPathOficial=false`, runtime prefers your repository layout/template sources (`gitpagelayouts/**` or your custom paths).
 
+## Compact config format
+
+`gitpagedocs/config.json` and each version config store every shared value once:
+
+- `site.icons` replaces the 279 flat `Icon*` keys: `defaults` holds what all header icons share
+  (`reactIcon`, `colorDark`, `colorLight`, `size`, `imgDark`, `imgLight`, `imgWidth`, `imgHeight`),
+  and each icon entry sets its `tag` plus any difference (`null` removes a field):
+
+  ```json
+  "icons": {
+    "defaults": { "reactIcon": true, "colorDark": "White", "colorLight": "black", "size": "25px" },
+    "NavMenuOpen": { "tag": "FaBars", "size": "22px" }
+  }
+  ```
+
+- `routeDefaults` (version config) holds the route settings every route shares (title/description
+  CSS, positions, visibility, margins, `blockLink`, `browseAll`); routes keep only their own values.
+
+The viewer expands both forms when it loads a config (`@gitpagedocs/tools/config-format`), so the
+flat keys still work: 0.0.x configs load unchanged, and a flat key or a value written on a route wins
+over the compact form.
+
 ## Version selector visibility
 
 In the docs shell, the **version** dropdown is hidden when `VersionControl.versions` resolves to **at most one unique** `id`:

cli/content/docs-en.mjs

@@ -391,6 +391,10 @@ Version configs support multiple content types:
 
 Each route can include \`title\`, \`description\` (per language), \`titleCss\`, \`titlePosition: "center"\`, \`descriptionPosition: "center"\`, \`titleIsVisible\`, \`descriptionIsVisible\`.
 
+Settings every route shares are written once in \`routeDefaults\` at the top of the version config; each route keeps only its own values, and a value written on a route wins over \`routeDefaults\`.
+
+Header icons live in \`site.icons\`: \`defaults\` holds what all icons share (\`reactIcon\`, \`colorDark\`, \`colorLight\`, \`size\`, \`imgDark\`, \`imgLight\`, \`imgWidth\`, \`imgHeight\`) and each icon entry sets its \`tag\` plus any difference (\`null\` removes a field). The older flat keys (\`IconNavMenuOpenReactIconesTag\`, …) still work and win when both are present.
+
 ## Route-level variables (blockLink, container, url, browseAll)
 
 Per-route options for \`routes-md\`, \`routes-html\`, \`routes-video\`, and \`routes-audio\`:

cli/content/docs-es.mjs

@@ -205,6 +205,7 @@ Claves principales:
 - \`docsVersion\`: version seleccionada por defecto
 - \`ActiveNavigation\`: habilita anterior/siguiente
 - \`FocusMode\`: habilita modo foco/lectura
+- \`icons\`: iconos de la cabecera. \`icons.defaults\` guarda lo que todos comparten (\`reactIcon\`, \`colorDark\`, \`colorLight\`, \`size\`, \`imgDark\`, \`imgLight\`, \`imgWidth\`, \`imgHeight\`) y cada icono define su \`tag\` y lo que cambia (\`null\` quita un campo). Las claves planas de abajo siguen valiendo y ganan cuando existen ambas formas.
 - \`IconImageMenuHeaderImgWidth\`, \`IconImageMenuHeaderImgHeight\`: tamano del icono principal
 - \`IconImageMenuHeaderLightImg\`, \`IconImageMenuHeaderDarkImg\`: icono principal (light/dark)
 - \`IconProjectLinkImgWidth\`, \`IconProjectLinkImgHeight\`: tamano del icono enlace del proyecto
@@ -256,6 +257,8 @@ Los configs de version soportan multiples tipos:
 
 Cada ruta puede incluir \`title\`, \`description\` (por idioma), \`titleCss\`, \`titlePosition: "center"\`, \`descriptionPosition: "center"\`, \`titleIsVisible\`, \`descriptionIsVisible\`.
 
+Los ajustes que comparten todas las rutas se escriben una sola vez en \`routeDefaults\`, al inicio del config de la version; cada ruta guarda solo sus propios valores, y un valor escrito en la ruta gana sobre \`routeDefaults\`.
+
 ## Variables por ruta (blockLink, container, url, browseAll)
 
 Opciones por ruta en \`routes-md\`, \`routes-html\` y \`routes-video\`:

cli/content/docs-pt.mjs

@@ -205,6 +205,7 @@ Principais chaves:
 - \`docsVersion\`: versao inicial selecionada
 - \`ActiveNavigation\`: habilita comportamento de anterior/proximo
 - \`FocusMode\`: habilita modo foco/leitura
+- \`icons\`: icones do cabecalho. \`icons.defaults\` guarda o que todos compartilham (\`reactIcon\`, \`colorDark\`, \`colorLight\`, \`size\`, \`imgDark\`, \`imgLight\`, \`imgWidth\`, \`imgHeight\`) e cada icone define seu \`tag\` e o que muda (\`null\` remove um campo). As chaves planas abaixo continuam valendo e vencem quando as duas formas existem.
 - \`IconImageMenuHeaderImgWidth\`, \`IconImageMenuHeaderImgHeight\`: tamanho do icone principal
 - \`IconImageMenuHeaderLightImg\`, \`IconImageMenuHeaderDarkImg\`: icone principal (light/dark)
 - \`IconProjectLinkImgWidth\`, \`IconProjectLinkImgHeight\`: tamanho do icone link do projeto
@@ -256,6 +257,8 @@ Configs de versao suportam multiplos tipos:
 
 Cada rota pode incluir \`title\`, \`description\` (por idioma), \`titleCss\`, \`titlePosition: "center"\`, \`descriptionPosition: "center"\`, \`titleIsVisible\`, \`descriptionIsVisible\`.
 
+Configuracoes que todas as rotas compartilham ficam uma unica vez em \`routeDefaults\`, no topo do config da versao; cada rota guarda so os proprios valores, e um valor escrito na rota vence o \`routeDefaults\`.
+
 ## Variaveis por rota (blockLink, container, url, browseAll)
 
 Opcoes por rota em \`routes-md\`, \`routes-html\` e \`routes-video\`:

cli/runtime/output.mjs

@@ -11,6 +11,7 @@ import {
 import { layoutsArtifactPaths } from "../contracts/layouts-paths.mjs";
 import { languageArtifactPaths } from "../contracts/langs-paths.mjs";
 import { SUPPORTED_LANGUAGES } from "../contracts/languages.mjs";
+import { compactSiteIcons, factorRouteDefaults } from "@gitpagedocs/tools/config-format";
 
 const DEFAULT_ICON_SVG = `<?xml version="1.0" encoding="utf-8"?>
 <svg width="800px" height="800px" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
@@ -65,7 +66,7 @@ async function writeLanguageArtifacts(root, outputDir, artifacts) {
 
 async function writeVersionConfigs(root, outputDir, versionConfigs) {
   for (const [versionId, versionConfig] of Object.entries(versionConfigs)) {
-    await writeJson(root, `${outputDir}/docs/versions/${versionId}/config.json`, versionConfig);
+    await writeJson(root, `${outputDir}/docs/versions/${versionId}/config.json`, factorRouteDefaults(versionConfig));
   }
 }
 
@@ -143,7 +144,8 @@ export async function writeConfigOnlyOutput(options) {
     createThemeTemplate,
   } = options;
 
-  await writeJson(root, `${outputDir}/config.json`, artifacts.rootConfig);
+  // Stored compact: shared icon values and route settings are written once.
+  await writeJson(root, `${outputDir}/config.json`, { ...artifacts.rootConfig, site: compactSiteIcons(artifacts.rootConfig.site) });
   await writeLanguageArtifacts(root, outputDir, artifacts);
   await writeText(root, `${outputDir}/icon.svg`, DEFAULT_ICON_SVG);
   await writeLayoutArtifacts({

cli/tests/core/output.test.ts

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync
 import os from "node:os";
 import path from "node:path";
 // @ts-expect-error .mjs runtime module is type-less in this package.
+import { applyRouteDefaults, expandSiteIcons } from "@gitpagedocs/tools/config-format";
 import * as output from "../../runtime/output.mjs";
 // @ts-expect-error .mjs runtime module is type-less in this package.
 import * as orchestrator from "../../builders/config-orchestrator.mjs";
@@ -114,7 +115,10 @@ describe("writeConfigOnlyOutput with the real artifacts", { timeout: 30_000 }, (
 
     const rootConfigText = readFileSync(at(root, "gitpagedocs/config.json"), "utf8");
     expect(rootConfigText.endsWith("\n")).toBe(true);
-    expect(JSON.parse(rootConfigText)).toEqual(artifacts.rootConfig);
+    // Stored compact (icons written once); expanding it gives back the generated config.
+    const storedRoot = JSON.parse(rootConfigText);
+    expect(storedRoot.site.icons).toBeDefined();
+    expect({ ...storedRoot, site: expandSiteIcons(storedRoot.site) }).toEqual(artifacts.rootConfig);
     expect(readFileSync(at(root, "gitpagedocs/icon.svg"), "utf8").startsWith("<?xml")).toBe(true);
 
     for (const language of SUPPORTED_LANGUAGES) {
@@ -128,7 +132,7 @@ describe("writeConfigOnlyOutput with the real artifacts", { timeout: 30_000 }, (
     }
 
     for (const id of DOC_VERSIONS) {
-      expect(readJson(root, `gitpagedocs/docs/versions/${id}/config.json`)).toEqual(artifacts.versionConfigs[id]);
+      expect(applyRouteDefaults(readJson(root, `gitpagedocs/docs/versions/${id}/config.json`))).toEqual(artifacts.versionConfigs[id]);
       for (const language of SUPPORTED_LANGUAGES) {
         const badge = `${BADGES[language]}${id}`;
         const gettingStarted = readFileSync(at(root, `gitpagedocs/docs/versions/${id}/${language}/getting-started.md`), "utf8");
@@ -221,7 +225,7 @@ describe("writeConfigOnlyOutput with synthetic artifacts", () => {
 
     expect(readJson(root, "out/config.json")).toEqual(artifacts.rootConfig);
     expect(readJson(root, "out/langs/en.json")).toEqual(artifacts.languageBundles.en);
-    expect(readJson(root, `out/docs/versions/${versionId}/config.json`)).toEqual(artifacts.versionConfigs[versionId]);
+    expect(applyRouteDefaults(readJson(root, `out/docs/versions/${versionId}/config.json`))).toEqual(artifacts.versionConfigs[versionId]);
     expect(readJson(root, "out/docs/versions/0.0.1/config.json")).toEqual({});
 
     // Already tagged content is written unchanged; unknown keys and languages are skipped.

frontend/src/entities/docs/api/load-remote-docs-data-client.ts

@@ -32,6 +32,7 @@ import {
   fetchUrlJson,
 } from "@/shared/api/fetch-client";
 import { withConfigDefaults } from "../lib/with-config-defaults";
+import { expandVersionConfig } from "../lib/expand-version-config";
 import { localizeConfig } from "./config/localize-config";
 import { applyLanguageToggles } from "./utils/route-utils";
 import { markdownToHtml } from "./utils/markdown";
@@ -221,7 +222,8 @@ async function loadVersionConfig(owner: string, repo: string, versionEntry: Vers
   }
 
   if (/^https?:\/\//i.test(versionPath)) {
-    return await fetchUrlJson<VersionConfig>(versionPath);
+    const fetched = await fetchUrlJson<VersionConfig>(versionPath);
+    return fetched ? expandVersionConfig(fetched) : null;
   }
 
   const normalizedPathCandidates = Array.from(
@@ -230,7 +232,7 @@ async function loadVersionConfig(owner: string, repo: string, versionEntry: Vers
   for (const pathCandidate of normalizedPathCandidates) {
     const candidateConfig = await fetchRepoJson<VersionConfig>(owner, repo, pathCandidate);
     if (candidateConfig) {
-      return candidateConfig;
+      return expandVersionConfig(candidateConfig);
     }
   }
 

frontend/src/entities/docs/api/version/resolve-version.ts

@@ -1,3 +1,4 @@
+import { expandVersionConfig } from "../../lib/expand-version-config";
 import type {
   AuthConfig,
   ContentTypeRouteConfig,
@@ -133,6 +134,7 @@ export async function loadVersionConfig(options: LoadVersionConfigOptions): Prom
     return undefined;
   }
 
-  const versionConfig = await readVersionConfig(versionPath, options);
+  const stored = await readVersionConfig(versionPath, options);
+  const versionConfig = stored ? expandVersionConfig(stored) : null;
   return versionConfig && hasVersionContent(versionConfig) ? versionConfig : undefined;
 }

frontend/src/entities/docs/lib/expand-version-config.ts

@@ -0,0 +1,10 @@
+import { applyRouteDefaults } from "@gitpagedocs/tools/config-format";
+
+/**
+ * Version configs are stored with the settings every route shares in
+ * `routeDefaults`; readers get complete routes. Browser-safe, so both the
+ * local (fs) and the remote (fetch) version readers use it.
+ */
+export function expandVersionConfig<T extends object>(stored: T): T {
+  return applyRouteDefaults(stored as Record<string, unknown>) as T;
+}