Konverterer Ami Pro .SAM til Markdown for Docs-pipelines

TL;DR

Vælg Markdown, når indholdet skal ind i et arkiv, en statisk sidegenerator eller en tekstpipeline. Markdown er lille, diff-venlig og bærbar: overskrifter, lister, tabeller og links bevares, udtrukne diagrammer bliver tilknyttede billedfiler, og ligninger kan indeholde deres LaTeX. Kombination med Git gør, at et konverteret Ami Pro-arkiv kan gennemgås i pull requests i stedet for at blive accepteret uden gennemgang. Konverter med Ami Pro Converter.

Hvorfor Markdown for ældre dokumenter

Docs-as-code ændrede, hvad det betyder at "have dokumentation". Indhold i et repository får versionshistorik, kodegennemgang, automatiseret linkkontrol og en build-pipeline. Indhold i et proprietært binært format får intet af det — og en .sam-fil får mindre end intet, fordi intet værktøj i kæden engang kan læse det.

At konvertere til Markdown flytter årtiers materiale ind i den samme arbejdsgang som alt andet. En installationsprocedure fra 1995 bliver til en fil, du kan sammenligne med dens revision fra 2002, annotere i en pull request og offentliggøre gennem den samme statiske site-generator som denne kvartals udgivelsesnoter.

Markdown er også det mest holdbare praktiske valg, der er tilgængeligt. Det er almindelig tekst med et let konventionslag: læsbar uden nogen software, analyserbar af dusinvis af implementeringer, og kan konverteres til HTML, PDF, DOCX eller hvad som helst andet efter behov. I betragtning af at hele problemet startede med et leverandørformat, der overlevede sin leverandør, er den portabilitet pointen.

Hvad kortlægges rent, og hvad gør ikke

Markdown er bevidst minimal, hvilket er dens styrke og dens begrænsning. Struktur oversættes godt; præsentation gør ikke, og det er som regel fint, fordi præsentation er det lag, du alligevel ønsker at erstatte.

Overskrifter — Ami Pro-stilarter fra .STY-arket bliver til Markdown-overskriftsniveauer og giver ægte dokumentstruktur
Lister — punkt- og nummererede lister konverteres til standard Markdown-lister, inklusive indlejring
Fremhævning — fed og kursiv svarer direkte; understregning har ingen Markdown-ækvivalent og bliver typisk til fremhævning
Tabeller — simple tabeller bliver til pipe-tabeller; komplekse layout med flettede celler kan ikke repræsenteres og har brug for HTML tilbagefald eller en note
Billeder — udtrukne WMF/EMF-diagrammer skrives som filer og refereres med standard billedsyntaks
Ligninger — tilgængelige som LaTeX for matematik-kompatible gengivere, eller som linkede billeder, hvor de ikke er

Stilark er det, der gør overskrifter mulige

Dette er detaljen, der afgør, om Markdown-konvertering er nyttig eller værdiløs. Markdown har ikke noget begreb om "16-punkts fed Helvetica" — det har overskriftsniveauer. Den eneste måde, en konverter kan vide, at en linje er en niveau-to overskrift frem for et fremhævet afsnit, er ved at afklare afsnitsstilen mod .STY-stilarket.

Med stilarket til stede ankommer et konverteret dokument med en overskriftshierarki, som du kan opbygge en indholdsfortegnelse ud fra og opdele i sektioner. Uden det får du en flad række af afsnit med enkelte fed skriftlinjer, og alle de ovennævnte fordele forsvinder.

Så før du konverterer et arkiv til en dokumentpipeline, skal du tjekke, at .STY-filerne er blevet overført fra den gamle server. Det tager et minut, og det bestemmer resultatet af hele projektet.

Håndtering af billeder i et arkiv

1. Beslut, hvor aktiver befinder sig

De fleste statiske site-generatorer forventer billeder i et dedikeret bibliotek eller placeret sammen med siden. Vælg konventionen, før du konverterer, så du flytter filer én gang, og ikke skal omdøbe referencer på tværs af tusindvis af Markdown filer bagefter.

2. Overvåg lagerstørrelse

Udtrukne diagrammer lægger sig sammen. Et par tusinde dokumenter med figurer kan lægge hundreder af megabytes til et arkiv, der tidligere kun indeholdt tekst. Overvej Git LFS, eller opbevar aktiver i objektlager og henvis til dem via URL.

3. Normaliser filnavne

Arvarkiver er fyldt med navne fra DOS-æraen, mellemrum og blandet tekst. Normaliser til små bogstaver med bindestreger under flytningen og behold en kortlægningstabel, så du stadig kan spore en offentliggjort side tilbage til dens oprindelige .sam-fil.

4. Vælg en ligningsstrategi fra starten

Hvis dit site gengiver matematik, brug den udtrukne LaTeX og få skarpe, valgbare og søgbare formler. Hvis det ikke gør, brug gengivne billeder og accepter, at matematikken ikke er søgbar. At blande begge dele på et arkiv er muligheden, man bør undgå.

Gennemgang af tusindvis af konverterede filer

Ingen læser tremille Markdown-filer, men Git gør selektiv gennemgang håndterbar på en måde, som en mappe med DOCX-filer ikke gør. Godkend konverteringsoutputtet som et enkelt stort commit på en gren, og gennemgå derefter efter mønster i stedet for efter fil.

Grep er hovedværktøjet her. Søg efter mistænkeligt korte filer, filer uden nogen overskrift overhovedet, uløste billedreferencer, tilfældige markerede markeringer, der indikerer et fortolkningshul, og erstatningstegn, der indikerer et kodningsproblem. Hver af disse søgninger fremhæver en type fejl på få sekunder.

Tilføj automatisering til pipelinen, mens du er i gang: en linkchecker til at fange ødelagte interne referencer, en validering af front-matter, hvis din generator kræver det, og et build-trin, der fejler ved manglende billeder. Når disse passerer, er arkivet i samme kvalitetsregime som din vedligeholdte dokumentation.

Hvor Markdown er det forkerte mål

Markdown kan med vilje ikke udtrykke kompleks sidestruktur, og nogle Ami Pro dokumenter blev designet snarere end skrevet — nyhedsbreve, formaterede formularer, rapportomslag med rammebaseret komposition. At tvinge dem ind i Markdown producerer noget teknisk gyldigt og praktisk ubrugeligt.

Det samme gælder dokumenter, hvis betydning er juridisk og afhænger af præcis præsentation: underskrevne kontrakter, udfyldte formularer, officielle meddelelser. For disse er PDF den ærlige udgave, og hvis du vil have dem søgbare sammen med Markdown, konverter til begge og link PDF fra en kort Markdown stub.

At være selektiv er ikke et kompromis. Et dokumentarkiv fyldt med rene, strukturerede Markdown plus et linket sæt af PDFs for dokumenter, der har brug for fast layout, er et bedre resultat end en ensartet bunke af forringede konverteringer.

Det giver Markdown et gammelt arkiv

Versionshistorik, gennemgang og sammenligninger for dokumenter, der aldrig har haft det
Kan udgives med den samme statiske webstedsgenerator som den nuværende dokumentation
Små, flytbare rene tekstfiler, der overlever ethvert enkelt værktøj
Overskriftsstruktur, der egner sig til indholdsfortegnelser og AI-opdeling
LaTeX-ligninger, der forbliver søgbare i stedet for at blive til billeder

Arv-dokumenter fortjener moderne værktøjer

Forskellen mellem en .sam-fil og en Markdown-fil i et depot er ikke bare en ændring i format. Det er forskellen mellem indhold, som ingen kan inspicere, og indhold, der deltager i gennemgang, søgning og automatiseret publicering ligesom alt andet, dit team skriver.

Bekræft stilarkene, beslut dine aktiver og ligningskonventioner, før du starter, konverter arkivet i én omgang, og gennemgå det med grep i stedet for ved at læse. Send det derefter gennem samme pipeline som resten af dine dokumenter.