Writing a Paper in Markdown (Part 2: Testing)

Following the previous article, Writing a Paper in Markdown (Setup) , this post tests whether a “write in Markdown → export to Word (docx) for submission” workflow is actually practical.

I specifically checked three areas: (1) citations (Pandoc + Zotero), (2) text formatting (bold/italic, superscript/subscript, etc.), and (3) figures and tables—especially where tables tend to break during Word conversion.

I also tried converting back from Word to Markdown after a co-author review (comments/edits), to see how well the workflow can round-trip.

Bottom line (TL;DR)

Markdown → Word (docx) is practical for drafting (Pandoc + Zotero works well).
Citations, basic formatting (bold/italic), superscript/subscript, and inserting figures converted without major issues.
Caveat: tables—especially pipe tables with long cell text—may not wrap in Word and can get truncated.
Word → Markdown conversion is not reliable; expect issues.

You can convert a Markdown file to Microsoft Word using Pandoc. In this test, I wrote the conversion options in a shell script and ran it.

A common approach is to put conversion options into a YAML file and reference it from the command line. I tried that, but my YAML setup sometimes failed (likely due to subtle formatting issues), so I used a shell script instead.

cd Documents/Manuscript

sh pandoc_md2docs.sh

If you’re using VS Code with the Zotero Citation Picker extension, the workflow is:

Launch Zotero.
Place the cursor where you want to insert a citation in your Markdown file.
Open the Command Palette (Cmd-Shift-P), type “Zotero”, and choose “Zotero Citation Picker”.
Search for a paper and select it from the list.
To insert multiple references in the same location, keep selecting additional items before confirming.
Press Return to insert the citation into the text.

For other editors, you can do it directly from Zotero. Even in VS Code, if drag-and-drop doesn’t work, copy/paste usually does:

Launch Zotero.
Search for the reference in your library.
Drag it into your editor, or copy it with Cmd-Shift-C and paste with Cmd-V at the desired location.
If multiple references are needed at the same spot, replace the separator between them with a semicolon.

You’ll get a citation key like [@arifClinicallySignificantProstate2020] .

I tested bold, italics, superscripts, subscripts, underline, and strikethrough using both “standard Markdown” symbols ( * , _ , ^ , ~ ) and HTML tags. Note that underline is not part of the original Markdown syntax.

Markdown syntax examples
**strong** (**), __strong__ (__), <strong>strong</strong> (str)

*italic* (*), _italic_ (_), <em>italic</em> (em)

***str_ital*** (*), ___str_ital___ (_), <strong><em>str_ital</em></strong> (st/em)

^13^C (^), <sup>13</sup>C (sup)

H~2~O (~), H<sub>2</sub>O (sub)

~~Not~~ (~~), <s>Not</s> (s)

<u>underline</u> (u), <ins>underline</ins> (ins)

The block above shows how the formatting is written in Markdown.

VS Code Markdown preview (default)
strong (**), strong (__), strong (str)

italic (*), italic (_), italic (em)

str_ital (***), str_ital (___), str_ital (st/em)

^13^C (^), ¹³C (sup)

H~2~O (~), H₂O (sub)

Not (~~), Not (s)

underline (u), underline (ins)

In the default VS Code preview, ^a^ and ~a~ do not render as superscript/subscript, but everything else worked. After installing the VS Code extension “Markdown Extended”, superscript/subscript also worked using ^a^ and ~a~ .

After conversion to Microsoft Word (Docx)
strong (**), strong (__), strong (str)

italic (*), italic (_), italic (em)

str_ital (***), str_ital (___), str_ital (st/em)

¹³C (^), 13C (sup)

H₂O (~), H2O (sub)

Not (~~), Not (s)

underline (u), underline (ins)

In Word output, the original Markdown symbol-based formatting ( * , _ , ^ , ~ ) worked, but HTML-tag-based formatting did not. For writing papers in Markdown, it’s safer to stick to the original Markdown syntax for formatting.

Markdown tables are commonly written using the pipe ( | ) method. The outer pipes are optional. The header separator line uses dashes ( - ), and alignment is controlled using colons ( : ). Column widths usually follow the longest cell. One important caveat: in the Markdown preview, long text wraps automatically, but after conversion to Word, long text may not wrap and can be truncated. Also, unlike grid tables, pipe tables do not support multi-line content or lists inside cells.

If you use VS Code with “Markdown Extended”, copying a table from Excel often pastes into the pipe-table format. Extensions like “Markdown All in One” can also help align the pipes for readability.

|  Right | Left  | Default  |   Center   |
| -----: | :---- | -------- | :--------: |
| orange | apple | melon    | strawberry |
|  horse | tiger | elephant |    bear    |
|      3 | 2     | 1        |     1      |

Grid tables do not display correctly in VS Code’s built-in Markdown preview, but they do convert cleanly to Word via Pandoc. Grid tables use pipes for columns, and use = / - to draw borders, with + at intersections. Alignment is also controlled with colons. A key benefit is that you can create line breaks and lists inside cells.

+--------+-------+----------+-------------+
|  Right | Left  | Default  |    Center   |
+=======:+:======+==========+:===========:+
| orange | apple | melon    | strawberry\ |
|        |       |          | blueberry   |
+--------+-------+----------+-------------+
|  horse | tiger | elephant |     bear    |
+--------+-------+----------+-------------+
|    3   | 2     | 1        |      1      |
+--------+-------+----------+-------------+

For simple tables, the pipe method is usually fine, but be careful with long text because of truncation after conversion. If you need multi-line cells, grid tables are safer (even if the preview looks messy). For complex tables, creating them in Excel and pasting into Word at the end is often the most practical approach.

To insert figures in Markdown, specify the path to the image file. I couldn’t reliably control the displayed image size in this workflow.

### Figures

![](test.jpg)

**Figure 1A** This figure shows that.

I also tested whether it’s possible to convert a Word back into Markdown after co-authors review the manuscript in Word (with comments and tracked changes).

pandoc -s output_rev.Docx -o output_rev.md

In short: it did not work well.

Comments and tracked changes were preserved in a readable way, but citations did not convert back into citation keys.

Instead of returning to something like [@arifClinicallySignificantProstate2020] , the citations turned into Word-style numbers (e.g., ^3^ ). The reference list and figures had similar issues. In other words, the conversion is not reversible.

I tested how far you can go with a “write in Markdown, convert with Pandoc” workflow for academic writing.

Citations, basic formatting (bold/italic/superscript/subscript), and inserting figures converted to Word without major issues.

Tables are possible, but long text can be truncated in Word output. If you need complex tables, it’s safer to create them in Excel and paste into Word at the final stage.

Converting an edited Word back into Markdown did not work for my use case, mainly because citations don’t return to citation keys.

Last updated: November 1, 2022