@gitpagedocs/cli

中文文档
0.0.26发布于 2026/11/09ISCES Module近 30 天下载 3862

CLI that scaffolds and maintains gitpagedocs documentation, generates docs with AI, configures GitHub Pages, and runs the MCP server.

原始使用文档
文档目录15 节
  1. Commands
  2. Generated documentation and themes
  3. Version repository links
  4. Packaging and release
  5. Layer Overview
  6. SOLID Principles
  7. Clean Architecture
  8. Authorized Routes Pipeline
  9. GitHub Pages Push Paths
  10. AI CLI (interactive + config file)
  11. What it does
  12. gitpagedocs pattern output
  13. .gitpagedocsconfig (manual mode)
  14. gitpagedocs chat
  15. Interactive fallback

@gitpagedocs/cli

The published npm package of the Git Page Docs monorepo (the command it installs is gitpagedocs). It scaffolds the gitpagedocs/ docs contract, generates docs with AI, configures GitHub Pages, and runs the MCP server.

npm install -g @gitpagedocs/cli   # global (installs the `gitpagedocs` command)
gitpagedocs                       # generate gitpagedocs/ config (config-only)

# or one-off, no install:
npx @gitpagedocs/cli

This package ships its TypeScript sources and runs them via tsx; it depends on the workspace packages @gitpagedocs/tools and @gitpagedocs/mcp (published alongside it).

Commands

CommandDescription
gitpagedocsGenerate gitpagedocs/ config + versioned docs (config-only)
gitpagedocs --layoutconfigAlso emit local layout templates in gitpagelayouts/
gitpagedocs --layouts-dir <dir>Folder for local layouts (default: gitpagelayouts)
gitpagedocs --no-interactive / -yNever prompt; use flags and defaults
gitpagedocs --push --owner <o> --repo <r> [--path <sub>]Generate, configure Pages, create workflow, commit + push
gitpagedocs --homeStandalone distribution (gitpagedocshome/: static site + .env + Dockerfile)
gitpagedocs -i / --interactiveInteractive prompts
gitpagedocs aiInteractive AI documentation generator — writes pages in the gitpagedocs pattern (see below)
gitpagedocs chat [question]Streaming AI chat in the terminal — REPL on a TTY, one-shot with a question or piped stdin; --provider, --model, --system (see below)
gitpagedocs provider [id] · models [provider]List AI providers / catalog models
gitpagedocs document[:repo|:file|:folder]Generate documentation with AI in the gitpagedocs pattern
gitpagedocs passwordSet a documentation access password (writes the public key to config.json, prints the private key)
gitpagedocs deploy / pages deployConfigure GitHub Pages via Actions, generate, commit and push
gitpagedocs pages actionsSwitch the repository's Pages source to GitHub Actions; no generation or push
gitpagedocs docsRefresh managed regions of README/CONTRIBUTING/SECURITY
gitpagedocs config clearDelete the stored .gitpagedocsconfig and the encrypted key vault .gitpagedocsvault (wipes saved AI credentials)
gitpagedocs doctor · version · updateDiagnostics / version / registry update check
gitpagedocs mcp startStart the MCP server over stdio

The AI-CLI implementation lives in cli/ai/ (relocated from the frontend so the published package is self-contained).

Generated documentation and themes

Version 0.0.26 registers documentation versions 0.0.26, 0.0.25, 0.0.24, 0.0.23, 0.0.22, 0.0.21, 0.0.20, 0.0.19, 0.0.18, 0.0.17, 0.0.16, 0.0.15, 0.0.14, 0.0.13, 0.0.12, 0.0.11, 0.0.10 and 0.0.9, newest first, with English, Portuguese and Spanish pages. Existing older folders are preserved. Source content lives in content/; defaults and UI labels live in data/; edit these sources before regeneration. The published package includes the English PDF guide and the local HTML integration for the externally hosted DOOM player.

The scaffold includes independent file pagination for Markdown, HTML, video, audio and PDF in page 50, with two localized HTML samples, local WAV tracks and a PDF reference. Configure shared controls in site.containerPagination and each sequence in its route's pagination.items. The generated pagination and Markdown markers guides explain defaults, route overrides, focus/search integration and theme-aware highlights linked from the document index. RouteGuideSpeciFicbrand keeps its existing heading-filter behavior.

The scaffold demonstrates parent Markdown destinations with recursive submenus and navigable breadcrumbs, PDF routes/actions, and a page with ordered, repeated Markdown/HTML/video/audio/PDF blocks. Route titles and descriptions have independent placement settings. Focus mode provides source actions and eight document/section navigation controls; browser narration is configured separately. See the generated configuration, content-blocks, focus, accessibility and HTML/PDF guides for complete examples.

Markdown code blocks with a supported language, including JSON, use Shiki syntax highlighting in documentation, focus mode, fullscreen and source-viewer previews. The active theme controls readable token colors and a reading surface consistent with its surrounding card across the 124 themes. Unsupported or unspecified languages remain readable plain text; very large blocks may also remain plain text to keep the reader responsive. Copy and download preserve the original Markdown.

gitpagedocs --layoutconfig ships all 124 themes: 64 original themes, 20 standalone animated presets and 20 additional dark/light parallax pairs. New presets originate in gitpagelayouts/v2/ and are compiled into package-local data by pnpm run layouts:sync; a standalone CLI installation does not need the source repository to emit them. Customize backgrounds through site.backgroundEffects, including global/per-theme settings, colors, density, speed and parallax. The master switch disables backgrounds; overrides.accessibility.showPauseButton: false hides only the pause control.

site.icons.VersionSelector and BackgroundAnimationPause/BackgroundAnimationResume use the same reactIcon, tag, size, colorDark and colorLight contract as other controls. Pause/resume appears in the navigation menu beside its lock; a manual pause persists across theme and menu changes. reactIcon: false selects localized text independently for each control.

The MCP reference documents installation, client configuration, all 20 tools and seven resources. MCP runs over stdio and reads provider credentials from its environment; it does not automatically unlock the CLI vault.

Each VersionControl.versions entry accepts branch, release and commit arrays of { name, url }. Names support Unicode, preserve their configured order and remain unchanged when the interface language changes. Legacy URL strings use translated category labels; empty categories are hidden. HTTP(S) and safe relative URLs are supported, unsupported schemes and invalid entries are omitted, and exact duplicates within a category appear once. The responsive version-links dialog groups links by category, scrolls long lists internally, follows theme tokens and supports keyboard navigation and Escape. Native links open a new tab with noopener noreferrer; site.icons.VersionLinks configures the trigger appearance. See Configuration for the historical 0.0.16 example and complete behavior.

The viewer's introduction guide changes one chapter per wheel/trackpad gesture, keyboard step or vertical swipe, without stopping text between scenes. Chapter-rail selections and back to top are immediate. One header play/pause button controls guide effects and the theme background without replacing content; reduced-motion preferences always prevail, with a disabled control explaining the system preference. The hero is visible from the first render, with optional small parallax offsets and brief section reveals. The CLI generates the documentation; the viewer itself is supplied by the source checkout or GitHub Pages build.

Expanding video, audio or HTML preserves the selected file and the same player or iframe instance when opening and closing. The viewer requests native fullscreen when available; Escape or browser controls close it and synchronize the URL. If fullscreen is unavailable or denied, the same content expands inside the page without a modal, with a close button and Escape handling within the expanded region. Markdown and PDF keep their existing viewing behavior.

Configure these arrays in gitpagedocs/config.json, independently for each documentation version. Merge entries with your existing catalog; do not replace other versions. See the named-link example for multiple branches, published releases and real commit URLs. The example's develop branch and owner/repository placeholders must be replaced with an existing branch in your repository. These fields link to existing resources; the CLI does not create those branches, commits or releases.

Packaging and release

Root and frontend workspaces are private. The public packages are @gitpagedocs/tools, @gitpagedocs/mcp and @gitpagedocs/cli; their versions, internal ranges and lockfile must agree. The npm workflow checks a new CLI version, installs with a frozen lockfile, runs typecheck and contract self-tests, then publishes the workspaces. GitHub Pages builds the viewer in its separate workflow. Neither workflow creates GitHub release notes or tags automatically.

The package allowlist includes its source, templates, data and assets. prebuilt/ is optional and is not created by the npm workflow. The config-only command generates repository data without starting a server. Run the full project checks and inspect package contents before publication; verify the published package and deployed site afterward.

CLI Architecture (Clean Architecture + SOLID)

Layer Overview

cli/
|-- index.mjs                          # Node entry (bootstraps TS presentation via tsx)
|-- package.json                       # the published `gitpagedocs` package
|-- ai/                                # AI CLI: docs generator + terminal chat
|   |-- application/                   # run-ai-cli-command, resolve-chat-credentials, ai-credentials (seal/unseal), vault-password
|   |-- infrastructure/                # ai-config-file (.gitpagedocsconfig), ai-key-vault (.gitpagedocsvault), file-system-adapter, version-docs-writer
|   |-- core/                          # chat-session, config models + parser
|   `-- presentation/                  # @clack prompts (ai-prompts, vault-prompts)
|-- contracts/                         # Stable contracts for external tooling
|   `-- doc-versions.mjs
|
|-- presentation/                      # Interface/composition root
|   |-- index.ts
|   |-- commands/                      # chat, config-clear, config-info, docs, pages, password, mcp, diagnostics, ai-info
|   |-- options/
|   `-- ui/
|
|-- application/                       # Use-cases and ports
|   |-- config-only/handler.mjs
|   |-- home/handler.mjs
|   |-- report/config-only-reporter.mjs
|   |-- use-cases/dispatch-mode.ts
|   `-- ports/cli-runtime-ports.ts
|
|-- domain/                            # Business rules
|   `-- services/sanitize-segment.mjs
|
|-- infrastructure/                    # Side effects and adapters
|   |-- config-only/runtime.mjs
|   `-- home/runtime.mjs
|
|-- builders/                          # Pure config builders
|-- data/                              # Constants and metadata
|-- content/                           # Static docs content
|-- runtime/                           # Low-level runtime helpers
`-- home/                              # Home templates/files

SOLID Principles

PrincipleApplication
SRPapplication/report only formats messages; handlers only orchestrate
OCPNew runtime implementations can be injected through ports
LSPdispatch-mode works with any runner implementing CliCommandRunner
ISPSplit runtime contracts (ConfigOnlyRuntimePort, HomeRuntimePort)
DIPUse-cases depend on application/ports, not concrete fs/git/exec

Clean Architecture

  • Interfaces/Presentation: parse CLI args, resolve mode, wire dependencies in presentation/index.ts
  • Application: orchestrate flows with explicit ports, without direct fs/git/exec imports
  • Domain: sanitize and core rules with no infrastructure dependencies
  • Infrastructure: concrete adapters for runtime side effects
  • Contracts: tools/smoke consumes cli/contracts instead of internal CLI modules

Authorized Routes Pipeline

The CLI now generates authorized-route docs and config entries in PT/EN/ES.

  • Source content: cli/content/docs.mjs (authorizedRoutes key per language)
  • Route metadata: cli/data/route-metas.mjs (ROUTE_META_ID6)
  • Route path mapping: cli/data/path-mappings.mjs (authorized-routes.md)
  • Version config composition: cli/builders/version-config-builder.mjs
  • Doc key resolution: cli/runtime/doc-path-resolver.mjs

Generated artifacts include:

  • gitpagedocs/docs/versions/<version>/config.json with auth and route authorization
  • gitpagedocs/docs/versions/<version>/{pt,en,es}/authorized-routes.md
  • menus-header-md entry dedicated to Authorized Routes

GitHub Pages Push Paths

  • Default project-site publish (--push without --path) targets /<repo>/.
  • Custom project subpath publish (--push --path <segment>) targets /<repo>/<segment>/.
  • --path accepts a single sanitized segment (letters, numbers, ., _, -).

Example:

npx @gitpagedocs/cli --owner vidigal-code --repo energy-bill-ai-parser --path git-docs --push

Expected URL after deployment:

https://vidigal-code.github.io/energy-bill-ai-parser/git-docs/

AI CLI (interactive + config file)

The CLI now includes a dedicated interactive AI mode:

npx @gitpagedocs/cli ai

What it does

  • asks for a provider from the shared catalog (14 providers, including OpenAI, Anthropic, Gemini and Ollama)
  • asks API key or Ollama URL
  • asks paths to scan (supports one or many paths, including other repositories)
  • generates documentation in pt, en, es in the gitpagedocs pattern
  • optionally persists config in .gitpagedocsconfig, sealing the API key in the encrypted vault .gitpagedocsvault (vault password created on first use, asked on every run)

gitpagedocs pattern output

The model is given a gitpagedocs-aware system prompt and returns documentation split into pages (delimited by === PAGE: <slug> | <Title> ===). The CLI scaffolds the base gitpagedocs/ structure first, then writes each page to gitpagedocs/docs/versions/<latest>/<lang>/<slug>.md for every language and wires it into that version's config.json (routes-md + menus-header-md) so the pages render in the viewer menu. Entries are tagged aiGenerated and idempotent (re-running replaces them). A later plain gitpagedocs rebuild drops the wiring — re-run gitpagedocs ai to restore.

.gitpagedocsconfig (manual mode)

The file lives in the per-user OS config directory (never inside the repository, so the API key cannot be committed by accident) and is written with owner-only 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 with gitpagedocs config clear. This example describes a saved configuration whose key already exists in the encrypted vault. Edit its non-secret settings and then run npx @gitpagedocs/cli ai. For a new installation, run the interactive setup first; if no key exists, decline reuse of the configuration and enter the credentials.

{
    "version": 1,
    "ai": {
        "provider": "openai",
        "apiKeyEncrypted": true,
        "paths": ["src", "cli", "../another-repo/src"],
        "languages": ["pt", "en", "es"],
        "outputDir": "gitpagedocs/docs",
        "filePrefix": "ai-generated",
        "contextPrompt": "Write clear technical documentation for this project."
    }
}

The API key is not in this file. Saving a configuration seals the key into the encrypted vault .gitpagedocsvault in the same directory (cli/ai/infrastructure/ai-key-vault.ts over EncryptedCredentialVault + FileVaultStorage from @gitpagedocs/tools: 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, at least 4 characters) and asked on every run of gitpagedocs ai / gitpagedocs chat that uses the stored key (3 attempts, then the run aborts with Vault password rejected).
  • GITPAGEDOCS_VAULT_PASSWORD supplies the password without a prompt (CI, pipes, no TTY); on a first run it initializes the vault, otherwise it must match the existing one.
  • A plaintext "apiKey" written by 0.0.1 is sealed into the vault and removed from the file when ai or chat reuses that configuration and unlocks it with the vault password.
  • If you hand-write the file, leave the key out: enter it in the gitpagedocs ai prompt (it is sealed on save). gitpagedocs chat can also read the provider's environment variable (gitpagedocs provider <id> lists it) when no key is stored.

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

gitpagedocs chat

gitpagedocs chat                                  # REPL on a TTY: /clear · /help · /exit (or Ctrl+C twice)
gitpagedocs chat "what does cli/ai do?"           # one-shot answer, then exit
git diff | gitpagedocs chat "review this diff"    # piped stdin is appended to the question
gitpagedocs chat --provider gemini --model gemini-2.5-pro --system "Answer in Portuguese" "..."

Credentials are resolved in this order: --provider/--model flags, the stored .gitpagedocsconfig (its key is decrypted after the vault password prompt, or from GITPAGEDOCS_VAULT_PASSWORD), then the provider's environment variable. Output streams to stdout while status lines go to stderr, so the answer can be piped.

Interactive fallback

If a directory is not found, CLI offers fallback choices:

  • fix paths and retry
  • skip missing paths and continue
  • abort safely

版本与发布记录

@gitpagedocs/cli 共发布 51 个版本,首次发布于 2026/06/15;过去 12 个月发布了 51 个版本。

版本发布日期距今
0.0.26latest2026/11/097 天前
0.0.252026/11/097 天前
0.0.242026/11/097 天前
0.0.232026/11/097 天前
0.0.222026/11/088 天前
0.0.212026/11/088 天前

关于 @gitpagedocs/cli 的常见问题

@gitpagedocs/cli 是什么?

CLI that scaffolds and maintains gitpagedocs documentation, generates docs with AI, configures GitHub Pages, and runs the MCP server.

如何安装 @gitpagedocs/cli?

在项目目录运行 npm install @gitpagedocs/cli,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 gitpagedocs,可以用 npx gitpagedocs 直接运行。

@gitpagedocs/cli 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/gitpagedocs__cli 是否存在。

@gitpagedocs/cli 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gitpagedocs/cli 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gitpagedocs/cli 可以商用吗?

@gitpagedocs/cli 使用 ISC 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gitpagedocs/cli 的下载量有多少?

根据 npm 官方下载统计,@gitpagedocs/cli 在 2026/10/17 – 2026/11/15 这 30 天内被下载 3,862 次,日均约 129 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gitpagedocs/cli 还在维护吗?

最新版本 0.0.26 发布于 2026/11/09(7 天前);至今共发布 51 个版本,其中过去 12 个月发布了 51 个;首次发布于 2026/06/15。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。