mdoffice is the whole suite at a terminal. It is a program in its own right, markdown-office/mdoffice, which requires both converter packages and calls them — so what it does is what those libraries do.

The options of each half are on a page of their own: For word and For presentations. How to get the tool is on Installation.

mdoffice word README.md          # writes README.docx
mdoffice word README.docx        # writes README.md
mdoffice slides deck.md          # writes deck.pptx

Parts

The first argument says which converter the run is for.

A bare file is not a run. mdoffice notes.md is refused, and the parts are listed:

mdoffice: Unknown part "notes.md".

  mdoffice <part> — one of:

  word       Markdown to .docx, .odt and .rtf, and .docx back to Markdown
  slides     Markdown to .pptx

The Word half decides the direction from the file's first bytes, but with more than one converter here a name alone cannot say which way the data goes, and an error that guessed would be right half the time and wrong the other half.

Commands

In the Word part, with no command, the direction is detected. --to overrides it: docx or word for a Word document, odt for an OpenDocument Text, rtf for Rich Text Format, and markdown or md for Markdown. opendocument and rich text say the same as odt and rtf. The slides part has one command, so mdoffice slides deck.md is the same run as mdoffice slides to-pptx deck.md.

A command named on the command line decides the direction itself, and --to is then only allowed to agree with it:

mdoffice word: --to docx does not match what this reads; it takes odt.
mdoffice word:   Omit it and let mdoffice word work the direction out from the file.

The two forms do not take quite the same options. With no command named, the direction is worked out from a list of its own, and that list does not carry --theme or --require-control:

mdoffice word: Unknown option "--theme".
mdoffice word:   Run `mdoffice help` to see what each command accepts.

Naming the command takes them, so mdoffice word to-docx notes.md --theme corporate is the way to write it.

Every command answers --help on its own, and every part answers help:

mdoffice help
mdoffice word help
mdoffice word to-docx --help
mdoffice slides to-pptx --help

Exit codes

0 on success, and 1 for anything that did not finish — whether the cause is a mistake the caller can put right or a defect they cannot. A mistake is printed as the sentence alone, because it is the caller's to fix:

mdoffice word: The file "nosuch.md" does not exist.
mdoffice word:   Name the file to read, or omit it to read standard input.

A defect is printed with its class and the line it happened on, because it is nobody's to fix and somebody's to see: mdoffice word: <ExceptionClass>: <message>, and then the file and the line underneath it.

Things it is easy to get wrong

• --output=x, --output x and -o x are the same. Leading dashes are stripped before the lookup, so even -o=x works.

• Everything after a bare -- is an operand, and a lone - is standard input.

• An option no command takes is named, and the hint says which command it does belong to:

  mdoffice word: The option "--media" does not apply here.
  mdoffice word:   It belongs to `to-markdown`.
  

• An option no command takes at all is refused with the way out:

  mdoffice word: Unknown option "--nope".
  mdoffice word:   Run `mdoffice help` to see what each command accepts.
  

Pipes

cat notes.md | mdoffice word to-docx - -o - | pbcopy
cat deck.md  | mdoffice slides to-pptx - -o - | pbcopy

Reading standard input and writing standard output both work, which makes it a filter rather than a command that has to be handed a filename. The result leaves through standard output and everything else goes to standard error, so a pipe gets a document and not a progress line.

What is lost

A run that dropped something says so on standard error, naming the feature:

mdoffice word: odt cannot carry table-borders: a table comes out with no borders

The Word half reports what a target format cannot carry. The slides half reports what it had to shrink to make fit — a block that is clamped rather than drawn over whatever comes next, so the file itself says nothing about it.

--version, and which library produced the document

An installed copy answers with its own version and the two libraries it holds:

$ mdoffice --version
mdoffice 0.1.0
  markdown-office/markdown-word            0.2.0
  markdown-office/markdown-presentation    0.2.0

The tool versions itself separately from the libraries it holds, because it is neither of them: a CLI-only change is a reason to release, and one version across three repositories would mean a Word-only fix forcing a presentation release. The libraries are read from the install rather than declared, so a --version and the files beside it cannot disagree — and a checkout answers with the branch it resolved rather than with a release, because that is what it holds.

mdoffice word --version reports the Word half alone, on one line:

$ mdoffice word --version
mdoffice word 0.2.0

Every example on this page was built by the library it documents while this page was built. This page as Markdown.