Skip to content

About

Powered by Next.js 15, React 19, TypeScript, and Node.js, this project builds multilingual documentation for GitHub Pages. It uses static export, ESLint, react-icons, gray-matter, and marked to render Markdown, apply customizable themes, and keep code quality strong, while environment variables control local and remote gitpagedocs loading behavior.

vidigal-code.github.io/git-page-docs/introduction-guide?theme=carbon-dark&modetheme=dark

Resources

Readme

Contributing

Contributing

Security policy

Security policy
Activity

Stars

4 stars

Watchers

0 watching

Forks

1 fork
Report repository
BranchesTags

Latest commit

 

History

349 Commits

Folders and files

Repository files navigation

Git Page Docs

gitpagedocs is a CLI and runtime contract for repository documentation.

It generates and maintains a gitpagedocs/ folder with config and versioned markdown files. It does not generate index.html or index.js.

Table of Contents

Project Architecture (Monorepo)

git-page-docs is a pnpm + turborepo monorepo. All business logic lives in one shared core (tools/); the frontend, CLI, and MCP server are thin consumers of it.

git-page-docs/
|-- frontend/     # Next.js 15 docs viewer (static export) — see frontend/README.md
|-- cli/          # Hexagonal CLI, published as the `gitpagedocs` npm bin
|-- mcp/          # Model Context Protocol server (@gitpagedocs/mcp)
|-- tools/        # @gitpagedocs/tools — the ONLY home for shared business logic
|-- gitpagedocs/  # User contract: config + versioned docs (kept stable)
|-- gitpagelayouts/ # Canonical layouts home: JSON + generated per-layout docs (layouts:sync)
|-- e2e/          # Playwright end-to-end specs
`-- tsconfig.base.json · turbo.json · pnpm-workspace.yaml · vitest.config.ts
Area Package Responsibility
frontend/ root pkg Next.js App Router docs viewer: multi-version / multi-language docs, 64 layout themes (dark and light variants), the in-docs AI chat drawer, and the /ai console. Built via next build frontend and static-exported to out/ for GitHub Pages.
cli/ gitpagedocs (bin) Hexagonal CLI (@clack/prompts) that scaffolds gitpagedocs/, generates docs with AI, configures GitHub Pages, and launches the MCP server.
mcp/ @gitpagedocs/mcp MCP server (SDK 1.29): 20 tools + 7 resources for repository analysis and AI doc generation, all delegating to tools/.
tools/ @gitpagedocs/tools Shared core: 14-provider AI system (registry/factory, no switch chains), encrypted credential vault (AES-256-GCM) + password gate, logger with secret redaction, caches, config loader, filesystem + documentation services. Browser-safe subpath exports (./ai, ./crypto/web, ./security/web, …).
gitpagedocs/ — The user-facing contract: config.{json,js,ts} and docs/versions/**. Never broken by refactors.

Security: encrypted AI credentials

API keys are never stored in plaintext, neither on the site nor by the CLI:

  • Site (/ai console and chat drawer) — a local password derives (PBKDF2-HMAC-SHA-256) an AES-256-GCM key; keys are encrypted at rest in localStorage and decrypted only for the session. The chat drawer also locks itself after site.AiChatAutoLockSeconds idle seconds (default 30) and asks for the password again — see AI chat drawer (auto-lock).
  • CLI (gitpagedocs ai / gitpagedocs chat) — the key never sits in .gitpagedocsconfig: it is sealed in the encrypted vault file .gitpagedocsvault next to it, with a vault password created on first use and asked on every run (GITPAGEDOCS_VAULT_PASSWORD for non-interactive runs). The config only records "apiKeyEncrypted": true — see Manual config.

Tooling

  • pnpm workspaces + turborepo for builds/tests across packages
  • Shared tsconfig.base.json; pnpm run typecheck covers cli / frontend / tools / mcp
  • Vitest unit + integration (coverage on tools/src) and Playwright E2E (e2e/)
  • A smoke + byte-baseline harness (pnpm run smoke:all) guards every legacy CLI contract
  • GitHub Actions: CI (ci.yml), GitHub Pages deploy (gitpagedocs-pages.yml), npm publish on version bump (npm-publish.yml) and deprecation of the retired 1.1.x line (npm-deprecate.yml)

The sections below document the published gitpagedocs CLI and its runtime contract. For frontend-specific development (the Next.js viewer), see frontend/README.md.

UI Icon Policy

Frontend controls, navigation actions, status buttons, and visual affordances use react-icons. Do not hardcode emojis or decorative Unicode symbols in React components, CLI output, or generated docs references.

Use the existing icon resolver flow where configuration is supported:

  • ReactIconByTag for configurable frontend icon tags.
  • ResolvedNavMenuIconConfig and related resolvers for menu, sidebar, lock, audio, and chat controls.
  • Direct react-icons imports only for local, typed fallback icons.

When an icon-only button already exposes its accessible name through aria-label or title, mark the rendered icon with aria-hidden.

Prerequisites

  • Node.js 20+ (engines.node is >=20 in every package)
  • npm / npx to install or run the published CLI
  • pnpm 10 (packageManager: pnpm@10.33.2) to develop this monorepo

Quick Start

Install the CLI globally, or run it one-off:

npm install -g @gitpagedocs/cli   # global install
gitpagedocs                       # then run anywhere (the bin is `gitpagedocs`)

# or, no install:
npx @gitpagedocs/cli

gitpagedocs is published from the cli/ package of this monorepo. Generating docs is config-only — it never writes index.html/index.js.

Generate docs config and versioned files (recommended default):

npx @gitpagedocs/cli

Generate docs plus local layout templates:

npx @gitpagedocs/cli --layoutconfig

Generate docs, configure GitHub Pages URL, create workflow, and push:

npx @gitpagedocs/cli --push --owner your-user --repo your-repository

Docs deploy at the repository root, e.g. https://your-user.github.io/your-repository/v/0.0.8/?lang=en.

Optional --path to serve docs in a subpath (e.g. docs or git-page-docs):

npx @gitpagedocs/cli --push --owner your-user --repo your-repository --path docs

Then docs are at https://your-user.github.io/your-repository/docs/v/0.0.8/?lang=en.

Shortcut syntax also supported:

npx @gitpagedocs/cli --push --your-user --your-repository

Standalone home distribution (npx @gitpagedocs/cli --home)

Generates a self-contained gitpagedocshome/ folder with:

  • Static export of the docs (ready for npx serve .)
  • Pre-configured .env
  • Dockerfile for container deployment
  • README.md with usage instructions
npx @gitpagedocs/cli --home
cd gitpagedocshome
npx serve .

Or with Docker:

cd gitpagedocshome
docker build -t gitpagedocshome .
docker run -p 3000:80 gitpagedocshome

Layout Strategy

gitpagedocs supports two layout strategies:

1) Default mode (npx @gitpagedocs/cli)

  • gitpagedocs/config.json (or config.js / config.ts) is generated with official layout source enabled.
  • Layouts/templates are loaded from the official repository URLs (the documented gitpagelayouts/ home):
    • https://github.com/Vidigal-code/git-page-docs/tree/main/gitpagelayouts
    • Repositories generated with --layoutconfig keep their own local layouts folder and it is still resolved first.
  • Every official layout is documented (palette, typography, usage) in gitpagelayouts/README.md.
  • Best option if you want to focus only on writing docs.

2) Local layout mode (npx @gitpagedocs/cli --layoutconfig)

  • Generates local files in gitpagelayouts/** (change the folder with --layouts-dir <dir>):
    • layoutsConfig.json
    • layoutsFallbackConfig.json
    • templates/*.json
  • The generated gitpagedocs/config.json references that folder through layoutsConfigPath and layoutsConfigPathTemplates, so the viewer resolves it directly instead of probing.
  • Official layout URLs are disabled in generated config.
  • Best option if you want to create and maintain your own templates in your own repository.

Fallback behavior

  • Runtime keeps resilient fallback behavior if a layout/template source is unavailable.
  • In local layout mode, the runtime prioritizes local repository layout sources and does not force official template URLs by default.

Use Official Site or Your Own GitHub Pages

You can choose either:

  1. Official viewer site https://vidigal-code.github.io/git-page-docs/
  2. Self-hosted viewer in your own GitHub repository using GitHub Pages.

This means your docs can run independently from the official domain when you publish your own site.

Self-Hosted GitHub Pages Setup

1) Prepare your repository

npm install
npx @gitpagedocs/cli

Or, if you want local templates:

npx @gitpagedocs/cli --layoutconfig

2) Configure runtime URL (site.rendering)

Set gitpagedocs/config.json (or config.js / config.ts) site.rendering to your GitHub Pages URL:

https://<your-user>.github.io/<your-repository>/

Example:

https://octocat.github.io/my-docs/

3) Build and validate locally

pnpm run lint
pnpm run build
pnpm start

4) Publish with GitHub Pages

  • Push your repository to GitHub.
  • Enable Pages for your repository (Settings -> Pages).
  • Use the repository workflow to build/deploy static output.
  • Optional one-command bootstrap:
    • npx @gitpagedocs/cli --push --owner your-user --repo your-repository — docs served at https://<owner>.github.io/<repo>/ (base path uses the repo name so CSS/JS load correctly)
    • npx @gitpagedocs/cli --push --owner your-user --repo your-repository --path docs — docs at https://<owner>.github.io/<repo>/docs/; the site root redirects there
    • This creates .github/workflows/gitpagedocs-pages.yml, sets site.rendering, commits generated artifacts, and pushes to origin.
    • The generated workflow clones the official git-page-docs runtime in CI, injects your gitpagedocs/ folder, builds, and deploys to your GitHub Pages URL.
    • The workflow trigger uses your current git branch automatically.
    • After push, CLI also attempts to switch repository Pages source to GitHub Actions using gh api (if GitHub CLI is available and authenticated).

When built with GITHUB_ACTIONS=true, the runtime enables GitHub Pages behavior.

Generated Structure

Default mode:

gitpagedocs/
  config.json           # site.languages: { "en": true, "pt": true, "es": true } (enable/disable each language)
  langs/{en,pt,es}.json # UI strings per language (langmenu + translations)
  icon.svg
  docs/
    versions/
      0.0.8/config.json
      0.0.8/{en,pt,es}/*.md

Local layout mode adds (at the repository root, next to gitpagedocs/):

gitpagelayouts/
  layoutsConfig.json
  layoutsFallbackConfig.json
  templates/*.json

Configuration Keys (Layout Source)

Main layout source keys in gitpagedocs/config.json (or config.js / config.ts):

  • layoutsConfigPathOficial
  • layoutsConfigPathOficialUrl
  • layoutsConfigPathTemplatesOficial
  • layoutsConfigPath
  • layoutsConfigPathTemplates

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):

    "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:

  • One entry, or multiple entries with the same id, shows no version selector (duplicate id rows are deduplicated; the first wins).
  • Two or more distinct id values show the version selector.
  • Language and theme selectors are separate and are not affected by version count.

Repository Search Behavior

Repository search is controlled by environment/runtime context:

  • GitHub Pages builds (GITHUB_ACTIONS=true): repository-search home enabled.
  • Local runtime: controlled by GITPAGEDOCS_REPOSITORY_SEARCH=true|false.

Recommended for local testing:

GITPAGEDOCS_REPOSITORY_SEARCH=true

Version configs can render a GitHub-style source browser inside the docs through routes-source-viewer and menus-header-source-viewer. Each source viewer route uses source-viewer: true and source-viewer-path, for example https://github.com/Vidigal-code/git-page-docs/tree/main.

Scripts

Run from the repository root with pnpm run <script> (npm run works too). They mirror the root package.json:

Script What it does
gitpagedocs node cli/index.mjs — generate gitpagedocs/ (config.json, langs/<lang>.json, versioned docs, icon.svg)
gitpagedocs:home node cli/index.mjs --home — standalone gitpagedocshome/ distribution (static site + .env + Dockerfile)
dev next dev frontend with the repository-search home (GITPAGEDOCS_REPOSITORY_SEARCH=true; predev copies icon.svg)
dev:e2e next dev frontend opening the local docs directly — what Playwright runs against
dev:e2e:guide next dev frontend in repository-search mode (build folder frontend/.next-guide) — the second Playwright server, for the introduction guide
build generate gitpagedocs/ + copy icon.svg to frontend/public/ + next build frontend (static export in frontend/out/)
build:prebuilt build, then copy the export to cli/prebuilt/
start node cli/start.mjs serves the build (prestart runs build first)
lint / lint:src eslint . / frontend sources only
typecheck / typecheck:strict-unused tsc --noEmit for root, frontend, tools and mcp / plus unused-symbol checks
test:unit / test:cov Vitest suite / with coverage
test:e2e Playwright E2E on two dev servers, PORT and PORT + 1 (PORT=3100 pnpm run test:e2e when 3000 is busy)
smoke:cli · smoke:commands · smoke:flags · smoke:core · smoke:ai · smoke:secweb · smoke:mcp · smoke:docs self-tests of the CLI artifacts, command verbs, flag contract, tools core, AI providers, web security, MCP server and docs automation
smoke:all / test / test:ci every smoke suite (smoke:all and test also run baseline:check)
baseline:create / baseline:check recreate / verify the byte-stable snapshot of the generated config.json + langs/*.json (and site-baseline.json)
layouts:sync regenerate gitpagelayouts/ (layout JSON + per-layout docs)
turbo:build · turbo:lint · turbo:typecheck · turbo:test the same tasks through turborepo
publish:all pnpm -r publish --access public --no-git-checks
clean remove frontend/.next/

URL Routes and Query Parameters

All routes for accessing documentation files on the official site or self-hosted GitHub Pages.

Path structure

Pattern Description
/ Repository search home (when repositorySearchHome=true)
/{owner}/{repo}/ Docs for owner/repo, default version
/{owner}/{repo}/v/{version}/ Docs for owner/repo, specific version
/v/{version}/ Docs for the project’s own repo, specific version

Base URL (official site): https://vidigal-code.github.io/git-page-docs/

Query parameters

Parameter Values Description
lang en, pt, es UI and content language
theme layout id (e.g. aurora-dark, aurora-light) Active theme; always reflected in URL
modetheme dark, light Theme mode (legacy; theme takes precedence)
version e.g. 0.0.8 Version (alternative to path)
menu en, pt, es Language for path resolution (use with id or name)
id route id (e.g. 1, 2) Navigate to page by route id
name slug (e.g. getting-started) Navigate to page by filename slug
mdfull en, pt, es Markdown fullscreen mode
htmlfull en, pt, es HTML fullscreen mode (needs a routes-html entry in the version config; this repository defines none)
file path (with mdfull or htmlfull) File to show in fullscreen
videofull en, pt, es Video fullscreen mode
audiofull en, pt, es Audio fullscreen mode
slug video/audio slug (with videofull or audiofull) Video/audio identifier
#heading-id anchor Scroll to heading in markdown

Example URLs (git-page-docs, English)

Base URL used below:

https://vidigal-code.github.io/git-page-docs

Base docs paths

Markdown pages by route id

Markdown pages by slug (name)

Source viewer

Video pages (id=8 to id=10 require sign-in; id=11 is open to every visitor, see Video routes)

Audio pages

Fullscreen modes

Theme and heading selection

Standalone app routes

Video routes

Video pages come from routes-video in the version config. Each route sets video.videoType (youtube, vimeo, mp4, …) and video.pathVideo per language; for YouTube, pathVideo is the video id. The viewer renders the route inside the docs shell, and ?videofull=<lang>&id=<route id> (or &slug=<video id>) opens it fullscreen.

The video routes of this repository are GitHub channel videos. Routes id=8 to id=10 carry the demo authorization (requireExternalAuth) and stay hidden from the sidebar until the visitor signs in with a configured provider. Route id=11 has no authorization, so the Video menu section and its video container are always visible. Videos are played only by the video container; markdown pages do not embed them.

A video route that shares its id with a markdown route is shown on the same page. The Introduction to Git page (id=5) uses this to show the test video in a video container above its markdown: the version config has a routes-video entry with "id": 5 (no menu entry of its own) and the markdown route sets a page order that puts the video first:

{ "id": 5, "hierarchyPage": { "video": 0, "md": 1, "source-viewer": 2, "html": 3, "audio": 4 } }

Test video (GitHub channel, A brief introduction to Git for beginners):

A brief introduction to Git for beginners | GitHub

Route definition in gitpagedocs/docs/versions/0.0.8/config.json:

{
  "routes-video": [
    {
      "id": 11,
      "title": { "en": "A brief introduction to Git for beginners | GitHub" },
      "fullscreenEnabled": true,
      "video": {
        "videoType": { "en": "youtube", "pt": "youtube", "es": "youtube" },
        "pathVideo": { "en": "r8jQ9hVA2qs", "pt": "r8jQ9hVA2qs", "es": "r8jQ9hVA2qs" }
      }
    }
  ],
  "menus-header-video": [
    { "id": 11, "en": { "title": "A brief introduction to Git for beginner...", "path-click": "page:11" } }
  ]
}

Media playback

Only one sound plays at a time. With site.mediaExclusivePlayback (default true in gitpagedocs/config.json):

Starts playing Is paused
a route video the header radio and the audio tracks
the header radio the route video and the audio tracks
an audio track the route video and the header radio

How each video source is followed and paused:

Source (video.videoType) Detects play Pauses
youtube official YouTube IFrame Player API (enablejsapi=1, state PLAYING) pauseVideo()
vimeo Vimeo player postMessage protocol (play event) pause method
mp4, webm, ogg, … (native) the element's play event pause()
any other embed (tiktok, instagram, …) focus moving into the player reloads the embed

Customizing:

  • Video with the picture only — set "muted": true in a route's video object. The video starts without sound (YouTube mute=1, Vimeo muted=1, native muted) and stays out of the rule, so it can run while the radio or an audio track explains it:

    {
  "id": 5,
  "video": {
    "videoType": { "en": "youtube" },
    "pathVideo": { "en": "r8jQ9hVA2qs" },
    "muted": true
  }
}

  • No rule at all — "mediaExclusivePlayback": false in site lets every player run freely (the radio and the audio tracks still pause each other, as before).

Authorized Routes

Route authorization is configured per version in:

  • gitpagedocs/docs/versions/<version>/config.json

Use the top-level auth section plus route-level authorization:

  • auth.accessKeys: key ids and expected secrets
  • auth.rolesStorageKey: localStorage key used to bootstrap roles
  • auth.providers: external providers (authjs, clerk, firebase, jwt)
  • authorization.accessKeyId: requires a configured key
  • authorization.requiredRoles: requires matching roles
  • authorization.requireExternalAuth: requires authenticated external provider
  • authorization.allowedProviders: optional provider allow-list per route

Example:

{
  "auth": {
    "accessKeys": {
      "docs-key": "open-gitpagedocs-docs"
    },
    "providers": [
      { "type": "authjs", "enabled": true, "sessionEndpoint": "/api/auth/session" },
      { "type": "jwt", "enabled": true, "tokenStorageKey": "git-page-docs:jwt-token" }
    ]
  },
  "routes-md": [
    {
      "id": 6,
      "path": {
        "en": "gitpagedocs/docs/versions/0.0.8/en/authorized-routes.md",
        "pt": "gitpagedocs/docs/versions/0.0.8/pt/authorized-routes.md",
        "es": "gitpagedocs/docs/versions/0.0.8/es/authorized-routes.md"
      },
      "authorization": {
        "accessKeyId": "docs-key",
        "requiredRoles": ["maintainer"],
        "requireExternalAuth": true,
        "allowedProviders": ["authjs", "jwt"]
      }
    }
  ]
}

CLI Options

Option Description
--owner <user> GitHub owner (e.g. Vidigal-code)
--repo <repo> GitHub repository (e.g. git-page-docs)
--path <subpath> Subpath for docs (e.g. docs); without it, base path = repo name for correct asset loading on project sites
--output <dir> Output directory (default: gitpagedocs or gitpagedocshome with --home)
--search true|false Enable/disable repository search (mainly for --home)
--layoutconfig Generate local layout templates in gitpagelayouts/
--layouts-dir <dir> Folder that holds local layouts (default: gitpagelayouts)
--push Create workflow, commit artifacts, push to origin
--pages-actions Only switch the repository's GitHub Pages source to GitHub Actions (same as pages actions; no docs generation or push)
--home Standalone distribution in gitpagedocshome/ (static site + .env + Dockerfile + README)
--interactive / -i Run in interactive mode (already the default in a terminal)
--no-interactive / --yes / -y Never prompt; use flags and defaults (implied in CI and when stdin is piped)
ai or --ai Interactive AI documentation mode (paths, provider, API key/base URL, multilingual output)
pages actions Detect owner/repo/branch from the git remote and, after confirmation, switch Pages to GitHub Actions
pages deploy Resolve owner/repo (flags or git remote), confirm, then run the full --push flow and print the site URL
--build Compatibility flag (no change to output)
--serve Compatibility flag
--full Compatibility flag

Shortcut syntax: npx @gitpagedocs/cli --push --<owner> --<repo> (e.g. --Vidigal-code --git-page-docs) is equivalent to --owner <owner> --repo <repo>.

With --home, output is gitpagedocshome/ (or --output value). Otherwise, output remains gitpagedocs/ (or --output value).

AI CLI (interactive docs generator)

Run:

npx @gitpagedocs/cli ai

This mode provides:

  • provider selection (openai, claude, gemini, ollama)
  • API key / base URL input
  • path input (supports multiple paths and cross-repo paths)
  • multilingual markdown generation (pt, en, es)
  • optional .gitpagedocsconfig persistence for manual reuse — the API key is sealed in the encrypted vault .gitpagedocsvault (vault password created on first use, asked on every run)
  • interactive fallback when directories are missing (fix/skip/abort)

The same credentials power gitpagedocs chat [question], a streaming AI chat in the terminal (REPL on a TTY; one-shot with a question or piped stdin; --provider, --model, --system). See cli/README.md.

Generates in the gitpagedocs pattern. The model is told what gitpagedocs is and returns documentation split into multiple pages. gitpagedocs ai first scaffolds the base gitpagedocs/ structure, then writes each page to gitpagedocs/docs/versions/<latest>/<lang>/<slug>.md (in every language) and wires them into that version's config.json (routes-md + menus-header-md), so the AI pages show up directly in the docs viewer menu. The added entries are tagged aiGenerated and are idempotent — re-running gitpagedocs ai replaces them instead of duplicating.

Note: a later plain gitpagedocs run rebuilds the base config from the deterministic templates and drops the AI wiring — re-run gitpagedocs ai to restore it.

Manual config (.gitpagedocsconfig)

The config is stored in the per-user OS config directory (never inside the repository, so nothing secret can be committed by accident), with owner-only file permissions on POSIX systems:

  • Windows: %APPDATA%\gitpagedocs\.gitpagedocsconfig
  • macOS: ~/Library/Application Support/gitpagedocs/.gitpagedocsconfig
  • Linux: $XDG_CONFIG_HOME/gitpagedocs/.gitpagedocsconfig (or ~/.config/gitpagedocs/.gitpagedocsconfig)

Set GITPAGEDOCS_CONFIG_DIR to override the directory. Delete the stored file, the vault and their credentials at any time with npx @gitpagedocs/cli config clear. File contents:

{
  "version": 1,
  "ai": {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "apiKeyEncrypted": true,
    "paths": ["src", "cli", "../another-repo/src"],
    "languages": ["pt", "en", "es"],
    "outputDir": "gitpagedocs/docs",
    "filePrefix": "ai-generated",
    "contextPrompt": "Você é um redator técnico sênior..."
  }
}

The API key is not in this file. When a configuration is saved, the key is sealed into the encrypted vault .gitpagedocsvault in the same directory (AES-256-GCM; key derived from your password with PBKDF2-HMAC-SHA-256, 210k iterations) and the config only keeps "apiKeyEncrypted": true:

  • the vault password is created on first use (typed twice) and asked on every run of gitpagedocs ai / gitpagedocs chat that uses the stored key (3 attempts, then the run aborts);
  • GITPAGEDOCS_VAULT_PASSWORD supplies it without a prompt (CI, pipes, no TTY);
  • a plaintext "apiKey" written by 0.0.1 is sealed into the vault and removed from the file the next time it is read;
  • gitpagedocs config clear deletes the config and the vault.

For Ollama, use baseUrl instead of an API key (no vault involved).

Documentation password gate

Protect the whole documentation site behind a password:

gitpagedocs password

It prompts for a password (type + confirm), writes a non-reversible public key to site.docsAccess in gitpagedocs/config.json, and prints a private key to copy. The scheme is double-hash: privateKey = SHA256(password), publicKey = SHA256(privateKey) — the password itself is never stored. When docsAccess.enabled is set, the viewer blocks the entire documentation behind a full-page gate; visitors unlock with the password OR the private key (verified against the public key). The unlock is cached in localStorage, and a lock icon in the menu clears the cache to re-block. Leave docsAccess.enabled false (the default) to keep the docs open.

AI chat drawer (auto-lock)

The in-docs chat drawer keeps the provider key in the encrypted localStorage vault and unlocks it with the local password. Two site keys in gitpagedocs/config.json control it:

Key Default Description
AiChatEnabled true (anything but false) Shows the AI chat button in the sidebar and mounts the drawer
AiChatAutoLockSeconds 30 Idle seconds before the drawer locks itself (60, 100, …; 0 disables; a non-numeric or negative value falls back to 30)

Behavior:

  • Any pointer, key, wheel or touch event inside the drawer counts as activity. Ten seconds before the limit (at 20 s idle with the default) a centered modal shows a countdown in the selected language — pt Salvar / Cancelar, en OK / Cancel, es Guardar / Cancelar. Cancel keeps the session; the confirm button or the countdown reaching zero locks the drawer.
  • Locking drops the in-memory password: the keys stay encrypted in the vault and the password gate is shown again. The timer pauses while a reply is streaming.
  • The modal traps focus (Tab / Shift+Tab / Escape = cancel), hides everything behind it, follows the active theme (light or dark) and is responsive down to phone widths. Its strings come from langmenu: aiChatAutoLockTitle, aiChatAutoLockDesc (with {seconds}), aiChatAutoLockConfirmBtn, aiChatAutoLockCancelBtn.
  • The provider/model picker is generated from the shared catalog (gitpagedocs models <id>), so a model id retired by its provider is replaced by the provider default instead of failing. Every option reads Provider · Model (OpenAI · GPT-4o mini, Anthropic Claude · Sonnet 4.6, Google Gemini · 2.5 Flash, Ollama · Llama 3); the provider name comes from langmenu (aiChatProviderOpenAI, aiChatProviderClaude, aiChatProviderGemini, aiChatProviderOllama) and the model name from the catalog. The picker is the same theme-aware dropdown as the language and theme selectors, so the open list is painted by the theme instead of the browser's native popup.
  • Buttons on the primary colour use the derived --primary-foreground token (near-black text on a light primary such as carbon-dark's white, white text on deep tones), and native controls follow the theme's derived --color-scheme; both are computed from the layout palette, so themes declare nothing new.
  • The exclamation-mark button in the drawer header opens a "How to use and risks" tab, readable before any password exists: how the vault and the per-request decryption work, a step-by-step guide, every event of the flow and the risks that remain. Its text comes from the langmenu keys aiChatInfo* (one list item per line; {seconds} shows AiChatAutoLockSeconds).
  • Transient provider errors (HTTP 408/425/429/500/502/503/504) are retried up to 3 times with backoff; a final failure is shown as a plain sentence ending with Try again! (langmenu.aiChatRetryHint), never as a bracketed status code.

Markdown page actions

Every markdown page shows, beside the fullscreen button, a copy button (puts the page's original .md text on the clipboard) and a download button (saves it as <file>.md), for the language being read. Labels come from gitpagedocs/langs/<lang>.json: mdCopyLabel, mdCopiedLabel, mdCopyErrorLabel, mdDownloadLabel.

Configuration File Format

Runtime supports three config file formats (in order of precedence):

  • gitpagedocs/config.json
  • gitpagedocs/config.js (CommonJS module.exports or ESM export default)
  • gitpagedocs/config.ts (TypeScript; exports default object)

Languages and UI Strings

The UI text is not part of config.json; it lives in one JSON file per language:

  • site.languages in gitpagedocs/config.json — switches each language on (true) or off (false), in menu order: { "languages": { "en": true, "pt": true, "es": false } }. A language set to false disappears from the language selector and its strings are not loaded, even when its docs exist.
  • gitpagedocs/langs/<lang>.json — that language's langmenu (header, search, source viewer, audio player, AI chat, docs-access labels) and translations (notFound, navigation, footer).

To add a language, create gitpagedocs/langs/<lang>.json and add "<lang>": true to site.languages. Strings inlined in site.langmenu / translations still work: the langs/ files win when both exist, and any missing key is backfilled from the current release baseline.

Versioning and changelog

0.0.1 is the first official stable release and the baseline every later version counts from. The 1.1.x line published before it (npm 1.1.44–1.1.71) is deprecated on the registry and its GitHub releases were removed. See CHANGELOG.md for what each release contains.

License

ISC. See repository for details.

Supported AI providers (14)

Provider ID Default model Capabilities
OpenAI openai gpt-4o-mini stream, vision
Anthropic anthropic claude-sonnet-4-6 stream, vision
Google Gemini gemini gemini-2.5-flash stream, vision, audio
OpenRouter openrouter openai/gpt-4o-mini stream, vision
Ollama (local) ollama llama3 stream, vision
Azure OpenAI azure-openai gpt-4o-mini stream, vision
Mistral mistral mistral-large-latest stream
DeepSeek deepseek deepseek-chat stream
Cohere cohere command-r-plus stream
Groq groq llama-3.3-70b-versatile stream
xAI Grok xai grok-2-latest stream, vision
Together AI together meta-llama/Llama-3.3-70B-Instruct-Turbo stream
Fireworks AI fireworks accounts/fireworks/models/llama-v3p3-70b-instruct stream
Perplexity perplexity sonar stream

CLI commands

  • gitpagedocs init — scaffold gitpagedocs config files
  • gitpagedocs config — show the resolved gitpagedocs config
  • gitpagedocs provider [id] — list AI providers or show one
  • gitpagedocs models [provider] — list catalog models
  • gitpagedocs ai — interactive AI docs generator (writes pages in the gitpagedocs pattern)
  • gitpagedocs chat [question] — streaming AI chat in the terminal (REPL on a TTY; one-shot with a question or piped stdin)
  • gitpagedocs document[:repo|:file|:folder] — generate documentation with AI in the gitpagedocs pattern
  • gitpagedocs password — set a documentation access password (writes the public key to config.json)
  • gitpagedocs config clear — delete the stored .gitpagedocsconfig and the encrypted key vault
  • gitpagedocs docs — refresh the managed regions of README, CONTRIBUTING and SECURITY
  • gitpagedocs deploy | pages — configure GitHub Pages via Actions and push
  • gitpagedocs pages actions — switch the repository's GitHub Pages source to GitHub Actions (no docs generation or push)
  • gitpagedocs pages deploy — detect owner/repo, confirm, then generate, commit, push and print the site URL
  • gitpagedocs doctor — diagnose the environment
  • gitpagedocs mcp start — start the MCP server over stdio
  • gitpagedocs version — print the CLI version
  • gitpagedocs update — check the registry for a newer CLI and print the install command

About

Powered by Next.js 15, React 19, TypeScript, and Node.js, this project builds multilingual documentation for GitHub Pages. It uses static export, ESLint, react-icons, gray-matter, and marked to render Markdown, apply customizable themes, and keep code quality strong, while environment variables control local and remote gitpagedocs loading behavior.

vidigal-code.github.io/git-page-docs/introduction-guide?theme=carbon-dark&modetheme=dark

Resources

Readme

Contributing

Contributing

Security policy

Security policy
Activity

Stars

4 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages