How qawatake/obsdconv works
Main Components and Their Roles
• CLI / Main Entry Point:
• Represented by main.go along with several helper files (e.g., passarg.go).
• This is where command-line flags are parsed (e.g., src, dst, and various option flags like -std, -obs, etc.).
• Configuration Component:
• Files like config.go and config_test.go indicate configuration management.
• It processes and holds the settings from CLI flags and possibly configuration files.
• Conversion Engine:
• The convert package (with files such as convert.go, error.go, link.go and several corresponding test files) is responsible for converting the Obsidian-specific syntax.
• This includes removing tags, transforming internal links, processing H1 for front matter fields (title & aliases), and handling image embeds.
• File Processing Module:
• The process package (files like process.go, component.go, walk.go) handles file system interactions:
▪ Recursively scanning directories,
▪ Skipping files or folders (based on .obsdconvignore),
▪ Managing input (src) and output (dst) directories.
• Scan/Utility Module:
• The scan package (with scan.go and util.go) likely performs additional directory or file content scanning, ensuring that conditions (e.g., filtering, alias extraction) are met.
• Testing and Samples:
• The sample and testdata directories provide examples and test cases.
• CI/CD Workflows:
• The .github/workflows directory and its YAML files define automated testing and release pipelines.
Relationships and Data Flow
• The CLI/Entry Point sends parsed configuration data to the Configuration Module.
• Using these settings, the File Processing Module scans for Obsidian markdown files in the source directory.
• For each file found, control is passed to the Conversion Engine, where content is parsed, filtered (tags, H1, links) and converted.
• The Conversion Engine may call on functions in the Scan/Utility Module to resolve internal references or perform detailed checks (e.g., for strict reference checking).
• Finally, processed content is written to the destination directory (dst).
Architectural Patterns and Design Principles
• Modularity: Separate packages (convert, process, scan) each address distinct concerns.
• Separation of Concerns: The tool cleanly distinguishes CLI handling, configuration, file I/O, text conversion, and testing.
• Error Handling: Tests and modules like convert_test.go, process_test.go show that the system is built to handle errors (e.g., in link resolution).