Skip to content

Importing Word and PowerPoint files

py-doc import turns a Word document or a PowerPoint deck into Markdown that py-doc builds again, so a document can start in Office and move to Markdown.

py-doc import Report.docx                 # report.md and report/media/image_001.png, ... beside it
py-doc import Briefing.pptx -o imported   # imported/briefing.md and imported/briefing/media/
py-doc docx report.md                     # the round trip
py-doc slides imported/briefing.md
Option Description
-o DIR Where the Markdown and its media folder go (default: beside the input)
--force Replace an existing .md file (else exit status 1)
--no-defloat-images Word only: leave floating pictures out, with a warning, instead of placing them inline
--print-output-paths Print where the Markdown and the media went

A file that is not a Word document or deck exits with status 2. The file’s properties (title, author, subject, keywords, category, description, version, status, document number, classification, company) become front matter. The “generated by python-docx” text that library writes into new files is left out.

Word documents

  • Headings are moved up so that the first one is #. Title and Subtitle paragraphs become front matter.
  • Lists keep their nesting, tables become pipe tables (merged cells are flattened to empty cells), consecutive Code paragraphs become one fenced block, and Quote becomes a block quote.
  • Note, Tip, Important, Warning and Caution styles become > [!NOTE] callouts, and captions become [[CAPTION:Figure]] lines before their picture or table.
  • Tracked changes are accepted: insertions are kept and deletions dropped. The contents table is left out.
  • Pictures are saved as PNG in the order the document uses them. EMF, WMF and SVG go through Inkscape in the tool container. A picture that cannot be converted is named in a warning and shows as (image not imported).
  • Text boxes and footnotes are not imported, and one warning gives the count.

PowerPoint decks

The Markdown follows what py-doc slides reads, so a deck built by py-doc comes back as the same slides.

  • The first slide, when it has a centred title, gives the title and subtitle of the front matter.
  • A Section Header slide becomes a # heading and any other slide a ## heading. A slide without a title becomes a page break.
  • Text placeholders become bullet lists, nested by level, and numbered where the deck numbers them. Text boxes become paragraphs. Bold, italic, struck-out text, monospace text and links are kept.
  • Monospace paragraphs become a fenced code block, and a bold NOTE, TIP, IMPORTANT, WARNING or CAUTION paragraph starts a callout, as pandoc writes them.
  • The two halves of a Two Content or Comparison slide become a ::::: columns block.
  • Tables become pipe tables. Pictures are saved as PNG in <name>/media, and a one-line text right under a picture or table becomes its [[CAPTION:]] line.
  • Speaker notes become a ::: notes block.
  • Charts, SmartArt, video and sound, embedded objects and equations are not imported, and one warning per kind gives the count. An equation leaves (equation not imported) in its place.