---
title: "Markdown document conversion: choose a pandoc route"
slug: markdown-document-conversion
excerpt: "The table under Match your file to a conversion route pairs a source format and a destination with a pandoc route and a post."
quickAnswer: "The section Match your file to a conversion route pairs a source and destination format in its table with a pandoc route and the post that holds its steps. Under Tools to have in place for each route, read the version lines quoted from the three test logs. Before you share or keep the result, go through A check list for the converted file."
keyTakeaways:
  - "Start with Match your file to a conversion route for the table of three routes."
  - "The section Tools to have in place for each route quotes the pandoc and typst version lines."
  - "Under Failures and warnings the test logs caught, find one quoted run per route."
  - "For reader steps, go to A check list for the converted file."
  - "Read Getting Markdown out of a PDF for the post on that conversion."
publishedDate: 2026-10-21
dateModified: 2026-10-21
author: Bobby Huang
cluster: B
role: post
status: published
faq:
  - q: "Why does my PDF run mention pdflatex?"
    a: "Look under Failures and warnings the test logs caught for the T1 message quoted from the PDF test log."
  - q: "Why did an image go missing after I converted?"
    a: "The runs quoted in Failures and warnings the test logs caught show a warning line from the Word run and a media check from the docx run."
  - q: "Is there one list of checks for a converted file?"
    a: "Numbered reader steps sit under A check list for the converted file."
  - q: "Which pandoc flag goes with which output?"
    a: "Find the What pandoc needs column in Match your file to a conversion route."
related:
  - markdown-to-pdf
  - markdown-to-word
  - word-to-markdown
---

Which conversion route fits my document? Name the format you have and the format you need, then pick the pandoc route that joins that pair. When the file comes out, open it and check it yourself.

Three routes are mapped here. Each had a single test run on a single machine, and every result below quotes that route's test log. You get the command, what the route needs and one thing its log caught. The full steps live in each route's own post, and this page sends you there.

## Match your file to a conversion route

Find the row whose first two cells match your source and destination.

| From | To | What pandoc needs | What to check after | Steps |
|---|---|---|---|---|
| Markdown (.md) | PDF | The flag `--pdf-engine=typst`; T2 in the PDF test log returned rc=0 with it | The numbered check list in that post | Markdown to PDF post |
| Markdown (.md) | Word (.docx) | An output name ending in .docx; T1 in the Word test log returned rc=0 | The numbered check list in that post | Markdown to Word post |
| Word (.docx) | Markdown (.md) | `-t markdown` plus `--extract-media`; T3 in the docx test log returned rc=0 | The numbered check list in that post | Word to Markdown post |

The third column holds the part of the command that sets that route apart, taken from a run that ended with rc=0. The fourth column points you to the numbered check list inside that route's post. The last column names the post itself.

For the PDF route, work from [the Markdown to PDF walkthrough](markdown-to-pdf.md). For a .docx made from a .md file, use [the walkthrough on Markdown to Word](markdown-to-word.md). To bring a .docx back into Markdown with its picture, follow [the walkthrough on Word to Markdown](word-to-markdown.md).

The two Word rows come from separate tests. The docx test did not reuse the file the Word test wrote. It built its own input, report.docx, with pandoc from notes.md in its T1 run. T1 there gave rc=0, with report.docx listed at 14910 bytes.

## Tools to have in place for each route

Pandoc runs in all three routes. The version line pandoc 3.8.3 sits near the top of the three logs.

The PDF route also calls typst, the engine its flag names. The PDF test log gives that version as:

```text
typst 0.15.1 (unknown commit)
```

The Word and docx test scripts never call typst, so their logs carry no typst line.

Next comes your input file, at the exact name you type. Two logs also hold a control run against an input name that matched no file. In the PDF test log, T7 pointed pandoc at nofile.md. It printed a "does not exist" error, gave rc=1 and left no miss.pdf. In the docx test log, T6 did the same with nofile.docx and also returned rc=1.

The PDF and docx test logs both print their input, notes.md, in full. Its 32 lines hold an image reference, a link, a quote, a table, fenced Python code, two lists, four headings and front matter. The picture it points at is diagram.png, listed at 2905 bytes in both logs.

## Failures and warnings the test logs caught

Here is one item per route. Each names the run and its log, and quotes what pandoc printed.

**Markdown to PDF.** T2 in the PDF test log ran this line:

```bash
pandoc notes.md --pdf-engine=typst -o out2.pdf
```

T2 gave rc=0. Inside out2.pdf, the opening five bytes read `%PDF-`, and the log counted 2 `/Type /Page` objects. Before that, T1 named no engine and asked for out1.pdf. Its single output line came with rc=47:

```text
pdflatex not found. Please select a different --pdf-engine or install pdflatex
```

No out1.pdf turned up in the check that followed T1. The T2 line differs from T1 by the typst flag and the output name.

**Markdown to Word.** T1 in the Word test log ran this line:

```bash
pandoc notes.md -o notes.docx
```

Pandoc printed one warning:

```text
[WARNING] Could not fetch resource diagram.png: replacing image with description
```

Even so, T1 gave rc=0, and notes.docx was listed at 11554 bytes. So in T1 the exit code said nothing about the missing picture, and the warning line was where it showed. For how an image line points at its file, open [the post on Markdown image paths](markdown-images.md).

**Word to Markdown.** T2 in the docx test log converted report.docx with no media flag. That run gave rc=0, while the image line in out.md linked to media/rId12.png. The follow-up check for that file came back rc=1, meaning no such file. T3 added the flag:

```bash
pandoc report.docx -t markdown --extract-media=assets -o out2.md
```

T3 returned rc=0. This time the image line named assets/media/rId12.png. The listing of the assets folder showed that picture.

So, of the runs quoted here, two gave rc=0 with a picture missing: T1 in the Word test log and T2 in the docx test log. In both, something besides the exit code told the story. For the Word run it was a printed warning, and for the docx run it was a file check.

If you would rather not use a terminal, the free [Markdown to PDF](/tools/markdown-to-pdf) and [Markdown to Word](/tools/markdown-to-word) pages run in your browser and do not upload the file.

## A check list for the converted file

The logs looked at exit codes, file names, file sizes and some output text. No log shows how a PDF or a .docx looks, so the steps below are yours.

1. Read the lines pandoc printed, and look for any that start with `[WARNING]`.
2. Confirm the exit code was 0 and the output file exists under the name you gave.
3. Open the output and read it through once, start to finish.
4. Find each image and make sure the picture is there, with no text sitting in its place.
5. For a Markdown output, confirm the file each image line names exists on disk.
6. Go down the numbered list in your route's own post.
7. Keep the source file until the output passes. Fix problems in the source, then convert again.

Does your document need breaks between pages? The [post on page breaks](markdown-page-break.md) covers them.

## Getting Markdown out of a PDF

For text pulled from a PDF and turned back into Markdown, see [the PDF to Markdown post](pdf-to-markdown.md).

## Where Sashmark fits

Each route on this page begins with one Markdown file, so mistakes are best fixed in that file first. Sashmark, which reads and edits .md files on the desktop, is still being built, and no version of it has been released. If the design holds, it would show a .md file as a page you can read, take a correction typed on that page, and write back just that correction with its Round-Trip design. Its Changes View, also still a plan, would mark the text an agent changed while the file was out of your sight, with or without a repo. The app itself has no AI features.

See the [planned features](/features), the [help pages](/help) and the [roadmap](/roadmap) for where each part stands.

[sashmark.com](https://www.sashmark.com/)