feat: migrate documentation from mdBook to Jekyll (gh CLI parity)#136
Merged
q-soriarty merged 14 commits intodevelopfrom Apr 2, 2026
Merged
feat: migrate documentation from mdBook to Jekyll (gh CLI parity)#136q-soriarty merged 14 commits intodevelopfrom
q-soriarty merged 14 commits intodevelopfrom
Conversation
Design spec and detailed implementation plan for migrating the manual from mdBook to Jekyll, matching gh CLI manual layout.
Adapted internal/docs/markdown.go from github.com/cli/cli with: - gh CLI dependencies inlined (FormatSlice, BuildAliasList, GroupedCommands) - GitHub-specific content removed (GH_COBRA fallback, cobra/doc import) - Core generation logic unchanged for easy upstream comparison - Flag rendering as HTML <dl> lists (identical template) - Aliases, JSON fields, subcommand grouping sections
Output directory changed to docs/site/manual/ for Jekyll. Jekyll front matter (layout: manual) added via filePrepender. Links use permalink format (no .md extension).
- Layout HTML matches gh CLI manual structure (Primer grid col-2/col-10) - CSS uses Primer utility classes extracted from cli.github.com reference - Dark theme colors, typography, flag <dl> rendering from manual.scss - Sidebar with monospace font, command grouping matching gh CLI - Copia logo + CLI branding in header - Landing page with install/config/examples sections - .gitignore updated for Jekyll build artifacts
Add AddGroup helper (adapted from gh CLI cmdutil.AddGroup) and annotate all parent commands with General/Targeted subcommand groups matching gh CLI structure.
Adapted from gh CLI style — 1-2 sentences per command explaining what it does, default behavior, and notable flags.
Match gh CLI visual style — usage and example code blocks rendered without background color, with proper indentation.
All examples updated with $ prefix and # comment lines matching gh CLI style.
Rename files to match gh CLI docs/ naming: - gh-parity.md → parity.md - gh-cli-patterns.md → cli-patterns.md - CODEBASE_MAP.md → project-layout.md Add docs/README.md index, update CLAUDE.md reference. Content review deferred to #133.
- install_linux.md: Homebrew, deb, rpm, binary - install_macos.md: Homebrew, universal binary - install_windows.md: binary, Scoop - install_source.md: Go build from source - releasing.md: Gitflow release process with GoReleaser
Lean overview with centered badges, installation links to docs/, quick start examples, roadmap, and link to manual.
- docs.yml: replace mdBook with Jekyll build (jekyll-build-pages@v1) - Delete docs/manual/ (mdBook structure, 55 files) - Makefile: add docs-serve, docs-clean targets
Add nolint:errcheck directive for fmt.Fprint calls (matching gh CLI upstream style) and wrap f.Close() in deferred closure.
This was referenced Apr 2, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #125
Closes #126
Closes #127
Closes #128
Closes #129
Closes #130
Closes #83
Closes #77
Migrate the Copia CLI manual from mdBook to Jekyll, replicating the gh CLI manual (cli.github.com/manual/) layout, theme, and doc generation.
Changes
Phase 1: Generator & Jekyll Foundation
internal/docs/markdown.go— doc generator adapted from gh CLI (flag<dl>rendering, subcommand grouping, aliases, JSON fields)script/gen-docs.go— updated to use new generator with Jekyll front matterdocs/site/— Jekyll site (layout, CSS, sidebar, landing page, config)Phase 2: Command Content Enrichment
# comment+$ commandformatPhase 3: Docs & README Migration
docs/reorganized (parity.md, cli-patterns.md, project-layout.md)Phase 4: CI/CD & Cleanup
docs.ymlworkflow: Jekyll build replaces mdBookdocs/manual/deleted (55 files)docs-serve,docs-cleantargetsSpec & Plan
docs/superpowers/specs/2026-04-02-jekyll-docs-migration-design.mddocs/superpowers/plans/2026-04-02-jekyll-docs-migration.mdTest plan
go test ./...)