How pplmx/h2h works
Main components
• CLI Entry Point: Represented by main.go and cmd/root.go, which handle command-line arguments and act as the interface between the user and the application logic.
• Conversion Engine: Encapsulated largely in internal/convert.go, this component contains the core logic to parse Markdown files, transform FrontMatter between Hexo and Hugo formats, and handle conversion directions (hexo2hugo and hugo2hexo).
• File I/O & Logging: The tool processes directories of Markdown files (specified by --src and --dst), reads/writes these files, and logs conversion activity to h2h.log.
• Configuration & Build Tools: Though not part of the runtime flow, files like go.mod, Makefile, Dockerfile, and the various CI/CD GitHub workflows indicate additional support for building, testing, and deploying the tool.
• Testing & Documentation: The tests directory and various documentation files (e.g., docs/usage.md) ensure the system’s functionality and provide guidance for contributors.
Relationships and interactions
• The User (via CLI) supplies the source/destination directories and options (e.g., --format, --direction).
• The CLI system (main.go and cmd/root.go) parses these inputs and invokes the conversion engine.
• The Conversion Engine (internal/convert.go) then reads each Markdown file, identifies the FrontMatter format, converts it as needed, and then writes the output to the destination directory.
• Logging is performed concurrently, writing detailed information and errors to h2h.log.
• Optionally, integration with external tools (GitHub workflows, Docker, etc.) ensures continuous testing, building, and deployment, though these do not directly interact with the live conversion process.
Important architectural patterns and design principles
• Separation of Concerns: Splitting the CLI interface, conversion core, file management, and logging into distinct modules (cmd, internal, tests).
• Modularity: Isolating conversion logic within a dedicated internal package makes the tool easier to understand, test, and extend.
• Layered Architecture: Input (CLI) → Processing (Conversion Engine) → Output (File I/O & Logging).
• User Input → CLI Command Parsing → Conversion Logic → File I/O/Logging.
• Annotations for key technologies:
• Go for the programming language (main.go, cmd, internal, tests).
• GitHub Actions & Docker for CI/CD, building containerized versions.
• Detail on error handling: note that conversion errors and path issues are documented in the h2h.log file.
• That the tool accepts command-line parameters to drive the conversion process and that the conversion engine supports both YAML and TOML for FrontMatter conversion.
• Logging mechanism as a vital component for tracing conversion steps and any errors that occur.