Konvertering av Ami Pro .SAM til Markdown for Docs Pipelines

TL;DR

Velg Markdown når innholdet skal inn i et depot, en statisk nettpubliseringsgenerator eller en tekstpipeline. Markdown er liten, diff-vennlig og bærbar: overskrifter, lister, tabeller og lenker bevares, utdragne diagrammer blir til koblede bildefiler, og ligninger kan beholde sin LaTeX. Kombinert med Git blir et konvertert Ami Pro-arkiv gjennomgåelig i pull requests i stedet for å bli stolt på blindt. Konverter med Ami Pro Converter.

Hvorfor Markdown for eldre dokumenter

Docs-as-code endret hva det betyr å "ha dokumentasjon." Innhold i et depot får versjonshistorikk, kodegjennomgang, automatisk lenkesjekk og en bygg-pipeline. Innhold i et proprietært binært format får ingen av delene — og en .sam-fil får mindre enn ingenting, fordi ingen verktøy i kjeden engang kan lese den.

Å konvertere til Markdown flytter tiår med materiale inn i den samme arbeidsflyten som alt annet. En installasjonsprosedyre fra 1995 blir en fil du kan sammenligne med dens revisjon fra 2002, kommentere i en pull-forespørsel, og publisere gjennom den samme statiske nettstedgeneratoren som kvartalets utgivelsesnotater.

Markdown er også det mest holdbare praktiske valget som er tilgjengelig. Det er ren tekst med et lett konvensjonslag: lesbart uten programvare, parsbart av dusinvis av implementasjoner, og konvertibelt til HTML, PDF, DOCX, eller noe annet etter behov. Gitt at hele problemet startet med et leverandørformat som overlevde sin leverandør, er portabilitet poenget.

Hva som kartlegges tydelig, og hva som ikke gjør det

Markdown er bevisst minimal, noe som er både styrken og begrensningen. Struktur oversetter godt; presentasjon gjør det ikke, og det er vanligvis greit fordi presentasjon uansett er laget du ønsker å erstatte.

Overskrifter — Ami Pro-stiler fra .STY-arket blir til Markdown-overskriftsnivåer, og gir ekte dokumentstruktur
Lister — punktlister og nummererte lister konverteres til standard Markdown-lister, inkludert nestede
Fremheving — fet og kursiv har direkte tilsvarende; understrek har ingen Markdown-ekvivalent og blir vanligvis til fremheving
Tabeller — enkle tabeller blir til rør-tabeller; komplekse oppsett med sammenslåtte celler kan ikke representeres og trenger HTML tilbakefall eller en merknad
Bilder — uttrukne WMF/EMF-diagrammer skrives som filer og refereres til med standard bildesyntaks
Ligninger — tilgjengelige som LaTeX for matematikkompatible gjengivere, eller som lenkede bilder der de ikke er det

Stilark er det som gjør overskrifter mulig

Dette er detaljen som avgjør om Markdown-konvertering er nyttig eller verdiløs. Markdown har ikke noe begrep om "16-punkts fet Helvetica" — det har overskriftsnivåer. Den eneste måten en konverterer kan vite at en linje er en nivå-to-overskrift heller enn et fremhevet avsnitt, er ved å løse avsnittsstilen mot .STY-stilarket.

Med stilarket til stede kommer et konvertert dokument med en overskriftsstruktur du kan lage en innholdsfortegnelse fra og dele opp. Uten det får du en flat rekkefølge av avsnitt med sporadiske fete linjer, og alle fordelene ovenfor forsvinner.

Så før du konverterer et arkiv for en dokumentpipeline, må du sjekke at .STY-filene har blitt overført fra den gamle serveren. Det tar et minutt, og det avgjør resultatet av hele prosjektet.

Håndtering av bilder i et depot

1. Bestem hvor eiendeler befinner seg

De fleste statiske nettstedsgeneratorer forventer bilder i en dedikert mappe eller samlokalisert med siden. Velg konvensjonen før du konverterer, slik at du flytter filer én gang, og ikke må endre referanser på tvers av tusenvis av Markdown-filer etterpå.

2. Se på lagerstørrelse

Utdragne diagrammer legger seg sammen. Noen tusen dokumenter med figurer kan legge til hundrevis av megabyte til et arkiv som tidligere bare inneholdt tekst. Vurder Git LFS, eller behold ressurser i objektlagring og referer til dem via URL.

3. Normaliser filnavn

Arvarkiver er fulle av DOS-tidsalderens navn, mellomrom og blandet bruk av store og små bokstaver. Normaliser til små bokstaver med bindestrek i navnene under flyttingen, og behold en kartleggingstabell slik at du fortsatt kan spore en publisert side tilbake til den opprinnelige .sam-filen.

4. Velg en ligningsstrategi på forhånd

Hvis nettstedet ditt gjengir matematikk, bruk den ekstraherte LaTeX-en og få skarpe, valgbare og søkbare formler. Hvis det ikke gjør det, bruk gjengitte bilder og aksepter at matematikken ikke er søkbar. Å blande begge deler i ett arkiv er alternativet man bør unngå.

Gjennomgang av tusenvis av konverterte filer

Ingen leser tremille Markdown-filer, men Git gjør selektiv gjennomgang håndterbar på en måte som en mappe med DOCX-filer ikke gjør. Legg konverteringsutdataene som en enkelt stor commit på en gren, og gjennomgå deretter etter mønster i stedet for fil.

Grep er hovedverktøyet her. Søk etter mistenkelig korte filer, filer uten overskrift i det hele tatt, uløste bildereferanser, tilfeldige merkede parenteser som indikerer et tolkningsgap, og erstatningskarakterer som tyder på et kodingsproblem. Hver av disse søkene avdekker en type feil på sekunder.

Legg til automatisering i pipelinen mens du først er i gang: en lenkesjekker for å fange opp ødelagte interne referanser, en front-matter-validerer hvis generatoren din krever det, og et byggesteg som feiler på manglende bilder. Når disse passerer, er arkivet i samme kvalitetsnivå som dokumentasjonen du vedlikeholder.

Hvor Markdown er feil mål

Markdown kan med vilje ikke uttrykke kompleks sideoppsett, og noen Ami Pro-dokumenter ble designet snarere enn skrevet — nyhetsbrev, formaterte skjemaer, rapportomslag med rammebasert komposisjon. Å tvinge disse inn i Markdown produserer noe som er teknisk gyldig og praktisk talt ubrukelig.

Det samme gjelder dokumenter hvis betydning er juridisk og avhenger av nøyaktig fremstilling: utførte kontrakter, signerte skjemaer, offisielle meldinger. For disse er PDF det ærlige resultatet, og hvis du vil at de skal være søkbare sammen med Markdown, konverter til begge og lenk PDF fra en kort Markdown-stub.

Å være selektiv er ikke et kompromiss. Et dokumentarkiv fullt av rene, strukturerte Markdown pluss et lenket sett med PDFer for dokumenter som trenger fastlagt oppsett er et bedre resultat enn en uniform haug med nedgraderte konverteringer.

Dette gir Markdown et gammelt arkiv

Versjonshistorikk, gjennomgang og sammenligninger for dokumenter som aldri har hatt det
Kan publiseres med den samme statiske nettstedsgeneratoren som dagens dokumentasjon
Små, flyttbare rene tekstfiler som overlever ethvert enkeltverktøy
Overskriftsstruktur som egner seg for innholdsfortegnelser og KI-oppdeling
LaTeX-formler som forblir søkbare i stedet for å bli bilder

Eldre dokumenter fortjener moderne verktøy

Forskjellen mellom en .sam-fil og en Markdown-fil i et depot er ikke bare en endring i format. Det er forskjellen mellom innhold som ingen kan inspisere og innhold som deltar i gjennomgang, søk og automatisert publisering som alt annet teamet ditt skriver.

Bekreft stilarkene, bestem dine ressurs- og ligningskonvensjoner før du starter, konverter arkivet i én omgang, og gjennomgå ved hjelp av grep fremfor å lese. Send det deretter gjennom samme prosess som resten av dokumentene dine.