Konverterar Ami Pro .SAM till Markdown för Docs-pipelines

TL;DR

Välj Markdown när innehållet är på väg in i ett arkiv, en statisk webbgenererare eller en textpipeline. Markdown är liten, diff-vänlig och bärbar: rubriker, listor, tabeller och länkar överlever, extraherade diagram blir länkade bildfiler, och ekvationer kan behålla sin LaTeX. Kombinerat med Git blir ett konverterat Ami Pro-arkiv granskningsbart i pull-requests istället för att förlitas på tro. Konvertera med Ami Pro Converter.

Varför Markdown för äldre dokument

Docs-as-code förändrade vad "att ha dokumentation" betyder. Innehåll i ett förvar får versionshistorik, kodgranskning, automatiserad länkgranskning och en byggpipeline. Innehåll i ett proprietärt binärt format får inget av det — och en .sam-fil får mindre än inget, eftersom inget verktyg i kedjan ens kan läsa det.

Att konvertera till Markdown flyttar årtionden av material in i samma arbetsflöde som allt annat. En installationsprocedur från 1995 blir en fil som du kan jämföra med dess revidering från 2002, kommentera i en pull-begäran och publicera genom samma statiska webbplatsbyggare som kvartalets versionsanteckningar.

Markdown är också det mest hållbara praktiska valet som finns tillgängligt. Det är ren text med ett lätt konventionslager: läsbar utan någon programvara, går att tolka av dussintals implementationer, och kan konverteras till HTML, PDF, DOCX eller något annat på begäran. Eftersom hela problemet började med ett leverantörsformat som överlevde sin leverantör, är portabiliteten poängen.

Vad som kartläggs tydligt, och vad som inte gör det

Markdown är medvetet minimal, vilket är dess styrka och dess begränsning. Struktur översätts bra; presentation gör det inte, och det är vanligtvis okej eftersom presentation är det lager du ändå vill ersätta.

Rubriker — Ami Pro-stilar från .STY-arket blir Markdown rubriknivåer, vilket ger verklig dokumentstruktur
Listor — punkt- och numrerade listor konverteras till standard Markdown-listor, inklusive inbäddning
Betoning — fetstil och kursiv stil motsvarar direkt; understrykning har ingen Markdown-motsvarighet och blir vanligtvis betoning
Tabeller — enkla tabeller blir pipetabeller; komplexa layouter med sammanslagna celler kan inte representeras och behöver HTML-fallbak eller en anteckning
Bilder — extraherade WMF/EMF-diagram skrivs som filer och refereras med standard bildsyntax
Ekvationer — tillgängliga som LaTeX för matematiskt kapabla renderare, eller som länkade bilder där de inte är det

Stilmallar är det som gör rubriker möjliga

Detta är detaljen som avgör huruvida Markdown-konvertering är användbar eller värdelös. Markdown har inget begrepp om "16-punkters fet Helvetica" — det har rubriknivåer. Det enda sättet en konverterare kan veta att en rad är en nivå-två-rubrik snarare än ett betonat stycke är genom att lösa styckeformatet mot .STY-stilmallen.

Med stilarket närvarande kommer ett konverterat dokument med en rubrikhierarki som du kan skapa en innehållsförteckning från och dela upp. Utan det får du en platt sekvens av stycken med ibland fetstilta rader, och alla ovanstående fördelar försvinner.

Så innan du konverterar ett arkiv för en dokumentpipeline, verifiera att .STY-filerna följde med från den gamla servern. Det tar en minut och det avgör resultatet av hela projektet.

Hantera bilder i ett arkiv

1. Bestäm var tillgångarna finns

De flesta statiska webbplatsgeneratorer förväntar sig bilder i en dedikerad katalog eller samplacerade med sidan. Välj konventionen innan du konverterar så att du flyttar filer en gång, istället för att byta namn på referenser över tusentals Markdown-filer i efterhand.

2. Visa förrådets storlek

Utdragna diagram lägger ihop sig. Några tusen dokument med figurer kan lägga till hundratals megabyte till ett arkiv som tidigare endast hade text. Överväg Git LFS, eller behåll resurser i objektlagring och referera till dem via URL.

3. Normalisera filnamn

Arvarkiv är fulla av namn från DOS-eran, mellanslag och blandad skrift. Normalisera till gemener med bindestreckade namn under flytten och behåll en kartläggningstabell så att du fortfarande kan spåra en publicerad sida tillbaka till dess ursprungliga .sam-fil.

4. Välj en ekvationsstrategi från början

Om din webbplats visar matematik, använd den extraherade LaTeX-koden och få skarpa, valbara, sökbara formler. Om den inte gör det, använd renderade bilder och acceptera att matematiken inte är sökbar. Att blanda båda i ett arkiv är alternativet att undvika.

Granska tusentals konverterade filer

Ingen läser tremiljontals Markdown-filer, men Git gör selektiv granskning hanterbar på ett sätt som en mapp med DOCX-filer inte gör. Sätt ut konverteringsresultatet som ett enda stort commit på en gren, och granska sedan efter mönster snarare än efter fil.

Grep är huvudverktyget här. Sök efter misstänkt korta filer, filer utan någon rubrik alls, oupplösta bildreferenser, lösa markerade taggar som indikerar ett tolkningsgap, och ersättningskaraktärer som indikerar ett kodningsproblem. Var och en av dessa sökningar visar en typ av fel på några sekunder.

Lägg till automatisering i pipeline samtidigt: en länkgranskare för att fånga trasiga interna referenser, en front-matter-validerare om din generator kräver det, och ett byggsteg som misslyckas vid saknade bilder. När dessa passerar är arkivet i samma kvalitetsnivå som din underhållna dokumentation.

Där Markdown är fel mål

Markdown kan medvetet inte uttrycka komplex sidlayout, och vissa Ami Pro-dokument var mer designade än skrivna — nyhetsbrev, formaterade formulär, rapportomslag med ram-baserad komposition. Att tvinga in dessa i Markdown producerar något som är tekniskt korrekt men praktiskt taget värdelöst.

Samma gäller för dokument vars betydelse är juridisk och beror på exakt presentation: ingångna kontrakt, undertecknade formulär, officiella meddelanden. För dessa är PDF den ärliga utdata, och om du vill att de ska gå att upptäcka tillsammans med Markdown, konvertera till båda och länka PDF från en kort Markdown-stub.

Att vara selektiv är inte ett kompromiss. Ett dokumentarkiv fullt av rena, strukturerade Markdown plus en länkad uppsättning PDF för dokument som behöver fast layout är ett bättre resultat än en enhetlig hög av försämrade konverteringar.

Det här ger Markdown ett gammalt arkiv

Versionshistorik, granskning och jämförelser för dokument som aldrig haft det
Kan publiceras med samma statiska webbplatsgenerator som dagens dokumentation
Små, flyttbara textfiler som överlever alla enskilda verktyg
Rubrikstruktur som passar för innehållsförteckningar och AI-uppdelning
LaTeX-ekvationer som förblir sökbara i stället för att bli bilder

Äldre dokument förtjänar moderna verktyg

Klyftan mellan en .sam-fil och en Markdown-fil i ett arkiv är inte bara en formatförändring. Det är skillnaden mellan innehåll som ingen kan granska och innehåll som deltar i granskning, sökning och automatiserad publicering som allt annat ditt team skriver.

Bekräfta stilmallarna, bestäm dina tillgångs- och ekvationskonventioner innan du börjar, konvertera arkivet i ett svep och granska med grep istället för att läsa. Skicka sedan det genom samma arbetsflöde som resten av dina dokument.