Converting Ami Pro .SAM to Markdown for Docs Pipelines

Why Markdown for legacy documents

Docs-as-code changed what "having documentation" means. Content in a repository gets version history, code review, automated link checking, and a build pipeline. Content in a proprietary binary format gets none of that — and a .sam file gets less than none, because no tool in the chain can even read it.

Converting to Markdown moves decades of material into the same workflow as everything else. A 1995 installation procedure becomes a file you can diff against its 2002 revision, annotate in a pull request, and publish through the same static site generator as this quarter’s release notes.

Markdown is also the most durable practical choice available. It is plain text with a light convention layer: readable without any software, parseable by dozens of implementations, and convertible to HTML, PDF, DOCX, or anything else on demand. Given that the whole problem started with a vendor format outliving its vendor, that portability is the point.

What maps cleanly, and what does not

Markdown is deliberately minimal, which is its strength and its limit. Structure translates well; presentation does not, and that is usually fine because presentation is the layer you want to replace anyway.

• Headings — Ami Pro styles from the .STY sheet become Markdown heading levels, giving real document structure
• Lists — bulleted and numbered lists convert to standard Markdown lists, including nesting
• Emphasis — bold and italic map directly; underline has no Markdown equivalent and typically becomes emphasis
• Tables — simple tables become pipe tables; complex merged-cell layouts cannot be represented and need HTML fallback or a note
• Images — extracted WMF/EMF diagrams are written as files and referenced with standard image syntax
• Equations — available as LaTeX for math-capable renderers, or as linked images where they are not

Style sheets are what make headings possible

This is the detail that decides whether Markdown conversion is useful or worthless. Markdown has no concept of "16-point bold Helvetica" — it has heading levels. The only way a converter can know that a line is a level-two heading rather than an emphasised paragraph is by resolving the paragraph style against the .STY style sheet.

With the style sheet present, a converted document arrives with a heading hierarchy you can build a table of contents from and chunk on. Without it, you get a flat sequence of paragraphs with occasional bold lines, and every one of the benefits above evaporates.

So before converting an archive for a docs pipeline, verify the .STY files came across from the old server. It takes a minute and it determines the outcome of the entire project.

Handling images in a repository

Reviewing thousands of converted files

Nobody reads three thousand Markdown files, but Git makes selective review tractable in a way that a folder of DOCX files does not. Land the conversion output as a single large commit on a branch, then review by pattern rather than by file.

Grep is the main tool here. Search for suspiciously short files, files with no heading at all, unresolved image references, stray bracketed markup that indicates a parsing gap, and replacement characters that indicate an encoding problem. Each of those searches surfaces a class of failure in seconds.

Add automation to the pipeline while you are at it: a link checker to catch broken internal references, a front-matter validator if your generator requires it, and a build step that fails on missing images. Once those pass, the archive is in the same quality regime as your maintained documentation.

Where Markdown is the wrong target

Markdown deliberately cannot express complex page layout, and some Ami Pro documents were designed rather than written — newsletters, formatted forms, report covers with frame-based composition. Forcing those into Markdown produces something technically valid and practically useless.

The same applies to documents whose meaning is legal and depends on exact presentation: executed contracts, signed forms, official notices. For those, PDF is the honest output, and if you want them discoverable alongside the Markdown, convert to both and link the PDF from a short Markdown stub.

Being selective is not a compromise. A docs repository full of clean, structured Markdown plus a linked set of PDFs for documents that need fixed layout is a better outcome than a uniform pile of degraded conversions.