OmniDocConvert PDF to Markdown on Linux Step by Step
Learn how to convert PDF to Markdown in Linux by exporting to Word with OmniDoc's desktop client, then converting the .docx file and fixing common problems.
If you work on Linux, you have probably needed to move a PDF into a Markdown file: a set of lecture notes for a repository, a specification for a documentation site, or a paper you want to annotate in a plain-text editor. The problem is that Markdown is plain text with light formatting, while a PDF is a fixed-layout file. Most PDFs do not carry clear structure for headings, lists and tables, so a direct conversion often produces a jumble of broken lines.
This guide shows a two-stage route that works well for many documents. First, you export the PDF to Word (.docx) with the OmniDoc Linux desktop client. Then you convert the Word file to Markdown with a general-purpose command-line converter. You will end with a .md file, an images folder, and a short checklist for fixing what the conversion gets wrong.
How do you convert PDF to Markdown in Linux? The short answer
Export the PDF to Word in the OmniDoc desktop client, convert the .docx to Markdown, and then check the result against the original. The Word step keeps more of the document's structure than the PDF text alone, which gives the Markdown output a better starting point.
| Your situation | What to do | Why |
|---|---|---|
| The PDF has selectable text | Export to Word, then convert the .docx to Markdown | Word keeps headings, lists and tables in a structure the converter can read |
| The PDF is scanned and you cannot select text | Run OCR in the PDF editor, then export to Word | Without a text layer, there is nothing to convert |
| The document has many equations | Convert, then rewrite equations by hand in the format your viewer supports | Equation support in Markdown depends on the renderer |
| The document is mostly plain prose | Export, convert, and do a quick read-through | Little structure exists to lose |
Before you start
- Install the OmniDoc desktop client. Download it from download.omnidoc.top, which provides builds for Windows, macOS and Linux. The export step runs there, so you need it before anything else.
- Check whether the PDF has selectable text. Try selecting a line with your cursor and copying it. If nothing highlights, the page is probably a scan and needs OCR first.
- Install a command-line converter. Use your distribution's package manager to add a general-purpose document converter that can read .docx files and write Markdown. Confirm it runs before you start, so you are not troubleshooting an install during the conversion.
- Create a clean output folder. Markdown image links are relative to the .md file, so put the output in its own folder. Converted images usually land in a subfolder that must stay next to the .md file.
Converting PDF to Markdown in Linux, step by step
- Open the PDF in the OmniDoc desktop client on Linux. Load the file you want to convert. Confirm it opens and that the pages look correct before you go further.
- Run OCR if the text is not selectable. Use the PDF editor's OCR feature on the scanned pages and wait for it to finish. Recognition errors are common in scans, so keep the original file open for comparison.
- Export the document to Word format. Use the PDF editor's export option and choose Word (.docx). Save the file in your output folder under a name that makes its origin clear.
- Review the .docx before converting. Open it in a word processor and look at the headings, lists and tables. If a heading shows up as plain bold text, apply a heading style in the Word file now, because the converter depends on that style to produce
#headings. - Convert the .docx to Markdown. Run your command-line converter on the .docx file and tell it to write Markdown output. The result is a .md file, and any embedded pictures are typically saved to a media folder beside it.
- Open the .md file in a plain-text editor and a Markdown preview. The plain-text view shows the raw syntax, such as pipe characters in tables and leading
#marks on headings. The preview shows how the file will render in a viewer. - Keep the .md file and its images folder together. If you move only the .md file, the image links break. Move the whole folder, or copy both into your repository or site directory.
Check the result
Compare the Markdown with the original PDF before you publish or reuse it. Work through the table below, and fix problems in the Word file where you can, then reconvert. That is usually faster than editing a long Markdown file by hand.
| Check | How to see it | If it's wrong |
|---|---|---|
| Headings | The preview shows heading levels that match the original | Apply heading styles in the .docx and convert again |
| Tables | Pipe tables render with the right number of columns | Rebuild complex tables by hand, or keep the table as an image |
| Images | Pictures appear in the preview from the media folder | Keep the folder beside the .md file and fix any broken paths |
| Equations | Compare each equation with the PDF | Rewrite as plain text, or as a LaTeX block if your viewer supports it |
| Missing text | Check the last paragraph of each section against the PDF | Re-run OCR on the affected pages and export again |
| Stray line breaks | Read a few paragraphs in the preview | Join lines that the PDF layout split mid-sentence |
Check the OCR output especially closely. Recognition can swap similar characters, such as "l" and "1", and those errors carry through to the Markdown. Verify any figures, names or citations against the original before you rely on them.
🎯 Which approach fits you?
The two-stage route suits people who want to keep both the content and the basic structure. If your document is simple, a quick check may be enough. If it is heavy with formulas or complex layouts, expect more manual cleanup, and consider keeping the Word file as your working copy, since editing it is easier than editing Markdown.
❓ FAQ
1. Why go through Word instead of converting the PDF directly?
A PDF stores where each piece of text sits on the page, not what it is. Word stores headings, lists and tables as structured elements, so the converter has more to work with. The .docx file also gives you a checkpoint you can fix before the Markdown step.
2. Will the Markdown look exactly like the PDF?
No. Markdown has no fixed page layout, columns or precise positioning, so the output keeps content and structure rather than appearance. Compare the two for accuracy and completeness, not visual match.
3. Does this work for scanned PDFs?
Yes, once the pages have been through OCR and exported to Word. Check the recognized text carefully, because OCR can misread characters, and verify anything important against the original.
4. Which Markdown flavor should I target?
Choose the flavor your repository, documentation site or Markdown viewer renders. Tables, footnotes and math syntax differ between flavors, so check the preview in the environment where the file will actually live.
5. Can I edit the Markdown inside OmniDoc?
The UniDoc web editor at app.unidoc.top supports Markdown with diagrams, so you can open and refine the converted file there. Check the rendered result against the original after each set of edits.
📝 Summary
To convert PDF to Markdown in Linux, export the PDF to Word with the OmniDoc desktop client, then convert the .docx file with a general-purpose converter. Keep the images folder beside the .md file, and check headings, tables, equations and OCR output against the original before you rely on the result.
