Tag: bash

I’ve finally had the time to convert preprint academic articles of JCRINN to markdowns!

Microsoft Word documents are common in research, teaching, and administration. When preparing these documents for a large language model (LLM), converting them to Markdown gives you a readable text file that you can inspect, edit, and supply to an AI application.

Pandoc is a command-line document converter available on Linux. It supports Microsoft DOCX input and several Markdown formats, making it useful for preparing manuscripts, reports, lecture notes, and technical documentation. Its focus is document structure, rather than reproducing the original page layout. Pandoc documentation

For academic writing, sections such as Introduction, Methods, Results, and Discussion provide useful boundaries. A retrieval system can divide a document at these boundaries and retrieve relevant passages when answering a question. Microsoft’s Azure AI Search documentation provides a concrete example of indexing Markdown by heading and retaining section information. This supports using Markdown as a practical format for structured retrieval. Microsoft documentation

The practical benefits include:

• Visible input: You can review the actual text supplied to the AI application.
• Reusable content: The same file can support summarisation, question answering, search, and a document knowledge base.
• Source tracking: Keeping the title, authors, DOI, and source URL helps connect extracted claims to their original document.
• Controlled selection: You can provide relevant sections instead of repeatedly submitting the complete document.

Markdown does not make an LLM automatically understand a document better or prevent invented answers. It also does not necessarily reduce token usage compared with a good DOCX text extractor. File size on disk is not a reliable measure of model input tokens. The benefit is greater control over the text and structure entering your workflow.

How to convert DOCX documents to Markdown in Ubuntu / Linux

Step 1: Install Pandoc

sudo apt install pandoc

Ubuntu’s repository version may be older than the latest upstream release. If you need a newer feature or conversion fix, consult the official Pandoc installation instructions. A LaTeX installation is unnecessary for DOCX-to-Markdown conversion.

Step 2 : Convert DOCX to Markdown (single file)

pandoc "report.docx" --from=docx --to=gfm --wrap=none -o "report.md"

For an academic manuscript with footnotes and equations, Pandoc’s own Markdown format is another useful choice:

To extract embedded images and update their references:

pandoc "report.docx" --from=docx --to=markdown --wrap=none \
  --extract-media="report-assets" -o "report.md

These formats and options are documented in the Pandoc User’s Guide. Running another example with the same output filename replaces the previous Markdown file.

An image reference does not give a text-only model access to the image’s contents. Supply figures separately to a vision-capable system, or add verified descriptions and relevant values as text.

Step 3: Review the converted document

Compare it with the Word original. Check section headings, numerical results, units, table labels, equations, references, and figure captions. Complex tables and formatting may not survive conversion accurately. Pandoc conversion limitations

For research documents, retain the qualifications attached to findings. A reported accuracy value without its dataset, evaluation method, or limitations can produce a misleading summary.

Step 4: Use the Markdown with an LLM

Upload the file to an application that accepts Markdown, or paste a relevant section into the conversation. For a larger collection, configure your retrieval workflow to preserve document identity and section headings with each passage.

A useful starting prompt is:

Using only the supplied document, identify the research objective, method, dataset, main results, and limitations. Cite the relevant section for each item. Preserve numerical values and units exactly. If information is absent, state “not reported”.

BONUS: Batch convert all DOCX files with bash

For a folder containing several documents, save the following script as batch-docx-to-markdown.sh

The script can be downloaded here in this gist: https://gist.github.com/mypapit/df6615f8611f03678bc93ee0485001be#file-batch-docx-to-markdown-sh