cmd

Overview ¶

build.go implements the core mdpress build command. It loads config, resolves sources, and dispatches document generation. Both local directories and GitHub repositories are supported, including zero-config discovery mode.

cache.go implements `mdpress cache`, the CLI entry point for inspecting and clearing the runtime cache directory. Until it existed the parsed-chapter cache was write-only from the user's point of view: it grew with every edit of every chapter and the only way to reclaim the space was to know the directory layout and delete it by hand.

completion.go implements the shell completion command for mdpress. It generates shell completion scripts for bash, zsh, fish, and powershell.

config_show.go implements `mdpress config show`, which prints the configuration a build would actually use.

Until this existed there was no way to see the resolved configuration: an unknown key, a theme that failed to resolve, or an output filename derived from the book title were all invisible, so "I set it and nothing happened" had no first debugging step. `config show` walks the same Load/Discover path as `build` and prints the result, plus the values that are computed rather than configured (theme source, effective typography, artifact paths).

init_chapters.go turns the flat list of Markdown files `mdpress init` finds into the nested chapter tree written to book.yaml. A project organized into directories used to come out as one long flat list, so the structure the author had already expressed on disk was thrown away at init time.

init_cmd.go implements the init subcommand. It scans Markdown files, extracts structure and titles, and generates book.yaml. When the target directory is empty it creates starter files. Interactive mode collects project metadata, with sensible defaults for non-interactive terminals.

markdown_options.go maps book.yaml settings onto Markdown parser options. It lives apart from the pipeline so every place that spins up a parser — the orchestrator and each parse worker — derives the same configuration.

markdown_scan.go provides code-aware line scanning for the Markdown checks that run outside the parser (validate's link and image extraction).

Those checks read files line by line with regexes. Without fence tracking they treat every example inside a ``` block as a real reference, so any book that documents Markdown — including mdPress's own manual — fails validation with a wall of errors for links that were never meant to resolve.

migrate.go implements the `mdpress migrate` command.

It detects a GitBook / HonKit project in the given directory, converts book.json to book.yaml, rewrites GitBook-specific template tags in Markdown files, and prints a migration report.

quickstart.go implements the quickstart subcommand. It creates a complete sample book project so users can see results quickly. The command generates book.yaml, README.md, sample chapters, an images directory, a .gitignore for build artifacts, and next-step instructions.

serve.go implements the local live preview server. It watches files, rebuilds HTML on change, and pushes reload events over WebSocket.

upgrade.go implements the upgrade subcommand. It checks for newer versions of mdpress from GitHub releases and optionally installs them.

validate.go implements the validate subcommand. It checks the book config, referenced files, and image paths, then prints a readable validation report.

validate_orphans.go finds Markdown files that sit in the project directory but are not reachable from the chapter list.

An orphan is invisible: it is not built, not searchable, not linked, and nothing in the output hints that it exists. The usual causes are a chapter that was renamed on disk but not in book.yaml, and a chapter someone wrote and forgot to register. Both look like a working project until a reader asks where the page went.