Skip to content

Conversation

@mphstudios
Copy link
Member

@mphstudios mphstudios commented Jan 22, 2026

Adds long-form documentation to the CLI via the help command.

Purpose

Users need guidance on workflows, troubleshooting, and feature-specific topics that do not fit in command help text. The Quire CLI needed extended documentation, beyond scope of the Commander.js built-in --help output.

Requirements for extended documentation:

  • Display markdown-formatted help content (in the terminal)
  • List available topics with a short description
  • Page long content in interactive terminals
  • Throw typed errors for unknown topics

Architecture Decisions

  1. Use the existing help command to delegate to a "help content library"
  2. The "help content library" should be versioned in the repository (lib/help/topics/) and maintained as part of code change and review process
  3. Leverage the already installed js-yaml library for markdown files with YAML front-matter
  4. Implement the "help content library" (lib/help/index.js) with a simple API that provides methods to getTopicList and getTopicContent
  5. Implement a pager utility (helpers/pager.js) for long content (this should respect the system $PAGER environment setting)
❯ quire help           
Available help topics:

  configuration    Project and CLI configuration options
  debugging        Troubleshooting common issues
  epub             Creating e-book publications
  pdf              Creating print-ready PDF publications
  publishing       Deploying your Quire publication
  workflows        Step-by-step guides for common Quire tasks

Run "quire help <topic>" for detailed information.
Run "quire <command> --help" for command-specific options.

Content for topics is maintained as markdown files in the repository cli/src/lib/help/topics/ directory.

See the Help Topic System documentation included with this pull-request.

@mphstudios mphstudios marked this pull request as ready for review January 22, 2026 17:14
@mphstudios mphstudios force-pushed the feature/help-topics branch 2 times, most recently from 87309a8 to 8a9d5c4 Compare January 22, 2026 22:07
@mphstudios mphstudios force-pushed the feature/cli-ux-improvements branch from 2c9bd2e to 54623ff Compare January 22, 2026 22:29
@mphstudios mphstudios force-pushed the feature/help-topics branch 2 times, most recently from 55a6d8d to 6cc6661 Compare January 23, 2026 00:44
@mphstudios mphstudios force-pushed the feature/cli-ux-improvements branch from eb9450d to 2b9bc08 Compare January 23, 2026 18:47
Base automatically changed from feature/cli-ux-improvements to main January 23, 2026 22:49
@mphstudios mphstudios changed the title Feature: help topics Feature: Help Topics System Jan 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants