Skip to content

Importing existing documents

Starting from a draft you already wrote in Word, LibreOffice, or another tool? Bring it in once and work in Markdown from there. The same engine that writes your books also reads other formats — Keystone runs Pandoc in reverse for this.

This is a one-time porting step. The conversion gets your words and structure into Markdown; you then reshape that into a clean manuscript.

Convert a document

Put the source file in your project's artifacts/ folder, then run make import with its name:

make import artifact=draft.docx

Pandoc reads DOCX, ODT, RTF, HTML, and other formats. The conversion produces:

  • artifacts/draft-imported.md — your content as Markdown
  • artifacts/draft-assets/ — embedded images extracted as files, when the source had any

Nothing under manuscript/ or assets/ is touched — the output stays in artifacts/ for you to review first.

Move it into the project

The import is a starting point, not a finished manuscript. From the converted Markdown:

  1. Split it up. Move the text into manuscript/, ideally one file per chapter or section rather than one large file — see Manuscript & structure.
  2. Place the images. Move the extracted media into assets/ and update the image paths in your Markdown to point there.
  3. Tidy the structure. Fix heading levels so chapters are # and sections ##, and drop any stray formatting the converter carried over.
  4. List the files. Add them to publish.txt in reading order.

From there it's an ordinary Keystone project — style it with shortcuts, configure it in pandoc.yaml, and build.

What to expect

Converting from an opaque format is rarely perfect — word processors carry formatting that doesn't map cleanly to Markdown. Treat the result as a solid first draft to clean up, not a faithful 1:1 copy. The payoff is permanent: once it's Markdown, your manuscript is plain text you own and can move around freely.