Summary
Migrate all conversion subcommands to a unified macdoc convert --to <format> entry point, following macOS textutil -convert <fmt> patterns.
Current State
macdoc word to-md file.docx
macdoc html to-md file.html
macdoc md to-html file.md
macdoc srt to-html file.srt
macdoc bib to-html file.bib
macdoc bib to-md file.bib
macdoc bib to-json file.bib
Each source format is a separate subcommand with its own to-* children.
Target State
macdoc convert --to md file.docx
macdoc convert --to md file.html
macdoc convert --to html file.md
macdoc convert --to html file.srt
macdoc convert --to html file.bib --style apa
macdoc convert --to md file.bib --style apa
macdoc convert --to json file.bib --style apa
macdoc convert --to tokens file.md
Design Principles (from .claude/rules/cli-textutil-compat.md)
- Action first:
convert --to <format>
- File last: always the trailing argument
- Auto-detect input format from file extension (
.docx → Word, .html → HTML, .bib → BibLaTeX, etc.)
- Long flags:
--to, --output, --style (swift-argument-parser convention)
- Non-conversion subcommands unchanged:
pdf init/status/..., config ai detect/...
Routing Logic
| Input extension |
--to |
Package |
.docx |
md |
word-to-md-swift |
.html |
md |
html-to-md-swift |
.md |
html |
md-to-html-swift |
.srt |
html |
srt-to-html-swift |
.bib + --style apa |
html |
bib-apa-to-html-swift |
.bib + --style apa |
md |
bib-apa-to-md-swift |
.bib + --style apa |
json |
bib-apa-to-json-swift |
| any text |
tokens |
token-counter-swift (issue #20) |
Backward Compatibility
Old subcommands (word to-md, html to-md, etc.) kept as aliases during migration, with deprecation warning. Remove in next major version.
Options
macdoc convert --to <format> [options] <file>
Options:
--to <format> Target format (md, html, json, latex, tokens)
--output <path> Output file path (default: stdout or same dir with new extension)
--stdout Force output to stdout
--style <style> Citation/formatting style (e.g. apa) — for bib conversions
--model <model> Model for token counting (gpt-4o, claude-sonnet)
--hard-breaks Treat soft breaks as hard breaks (md→html)
--full Output full HTML document instead of fragment
References
.claude/rules/cli-textutil-compat.md
- macOS
textutil -convert syntax
- swift-argument-parser conventions
Summary
Migrate all conversion subcommands to a unified
macdoc convert --to <format>entry point, following macOStextutil -convert <fmt>patterns.Current State
Each source format is a separate subcommand with its own
to-*children.Target State
Design Principles (from
.claude/rules/cli-textutil-compat.md)convert --to <format>.docx→ Word,.html→ HTML,.bib→ BibLaTeX, etc.)--to,--output,--style(swift-argument-parser convention)pdf init/status/...,config ai detect/...Routing Logic
.docxmdword-to-md-swift.htmlmdhtml-to-md-swift.mdhtmlmd-to-html-swift.srthtmlsrt-to-html-swift.bib+--style apahtmlbib-apa-to-html-swift.bib+--style apamdbib-apa-to-md-swift.bib+--style apajsonbib-apa-to-json-swifttokenstoken-counter-swift(issue #20)Backward Compatibility
Old subcommands (
word to-md,html to-md, etc.) kept as aliases during migration, with deprecation warning. Remove in next major version.Options
References
.claude/rules/cli-textutil-compat.mdtextutil -convertsyntax