Export Org Mode to Markdown in Emacs Without Breaking Your Tables

The problem: your Org notes need to become Markdown

You keep meeting notes and drafts in Emacs Org Mode, but your publishing pipeline expects Markdown—perhaps for Hugo, Jekyll, or GitHub Pages. Copying by hand is error-prone, especially with tables and source blocks. The good news is that Emacs 27 and later ship with a native Markdown exporter, so you do not need a third-party package to convert an Org file.

What the exporter preserves and what it changes

Org Mode’s Markdown exporter handles the common structures well:

• Headings become Markdown headings
• Ordered and unordered lists convert to Markdown lists
• Org tables become pipe tables
• Source blocks become fenced code blocks
• Links and emphasis carry over in most cases

It does not preserve everything. Dynamic blocks such as clock tables, agenda views, and inline tasks have no Markdown equivalent and are usually dropped or rendered as plain text. LaTeX fragments may remain as raw math delimiters rather than converting to Markdown-friendly math syntax. Footnotes sometimes export inconsistently and deserve a manual check.

Worked example: export one Org file

Create a file named ~/content/posts/draft.org with this content:

* Draft post
** Section one

Some text with a link: [[https://example.org][Example]]

| Item | Status |
|------+--------|
| Draft | open   |

#+BEGIN_SRC python
print("hello")
#+END_SRC

Open that file in Emacs and run M-x org-md-export-to-markdown. You can also trigger it with C-c C-e, then press m for Markdown.

Where to run: inside Emacs, with the Org buffer active. Required permissions: ordinary write access to the directory containing the Org file; no administrator privileges are needed. The exporter writes draft.md next to the source file by default. If that Markdown file already exists, Emacs may overwrite it depending on your settings, so check for an existing file before exporting.

Expected result: a draft.md file containing Markdown headings, a pipe table, and a fenced Python block. Open it in a Markdown previewer to confirm the syntax renders.

Adjust export behavior with variables

You can control heading depth, table of contents, and code fences through org-md-export-options. Add this to your Emacs configuration:

(setq org-md-export-options
      '(:headline-levels 4
        :code-fences t
        :toc nil))

This limits exported headings to four levels, forces fenced code blocks, and omits the table of contents. Restart Emacs or evaluate the expression with M-x eval-expression before exporting again.

Check the result before publishing

1. Open the exported .md file in a Markdown previewer and verify headings, tables, and code blocks appear.
2. Compare the Org source and Markdown output section by section; nothing should be silently dropped except constructs Markdown cannot represent.
3. If you use Hugo, copy the Markdown file into your content/posts/ folder and run hugo server from your site directory to confirm the page builds.
4. If the page does not build, inspect the exported Markdown for raw LaTeX or unexpected HTML that your static site generator cannot parse.

Limitations

Large Org documents can produce long Markdown files and slow down the export. The exporter also leaves interactive Org features behind; Markdown is static, so clock tables and agenda exports will not function after conversion. Treat the Markdown file as a publishing artifact, not a replacement for the Org source.

Bottom line

For Emacs 27 or later, the built-in Org Markdown exporter is the simplest path from Org notes to a Markdown publishing pipeline. Export one file, inspect the output, adjust org-md-export-options if needed, and delete the generated Markdown if the result does not meet your standards. The Org source remains unchanged.