Conversion d’Ami Pro .SAM en Markdown pour les pipelines Docs

TL;DR

Choisissez Markdown lorsque le contenu se dirige vers un dépôt, un générateur de site statique ou un pipeline de texte. Markdown est petit, facile à diff et portable : les titres, listes, tableaux et liens survivent, les diagrammes extraits deviennent des fichiers image liés, et les équations peuvent conserver leur LaTeX. Combiné avec Git, une archive Ami Pro convertie devient examinable dans les demandes de tirage au lieu d'être considérée de confiance par défaut. Convertissez avec Ami Pro Converter.

Pourquoi Markdown pour les documents anciens

Docs-as-code a changé ce que signifie « avoir de la documentation ». Le contenu dans un dépôt bénéficie d’un historique de versions, de la relecture de code, de la vérification automatique des liens et d’un pipeline de construction. Le contenu dans un format binaire propriétaire n’obtient rien de tout cela — et un fichier .sam obtient moins que rien, car aucun outil dans la chaîne ne peut même le lire.

La conversion en Markdown déplace des décennies de matériel dans le même flux de travail que tout le reste. Une procédure d'installation de 1995 devient un fichier que vous pouvez comparer avec sa révision de 2002, annoter dans une demande de tirage, et publier via le même générateur de site statique que les notes de publication de ce trimestre.

Markdown est également le choix pratique le plus durable disponible. C'est un texte brut avec une couche de convention légère : lisible sans aucun logiciel, analysable par des dizaines d'implémentations, et convertible en HTML, PDF, DOCX, ou autre chose sur demande. Étant donné que tout le problème a commencé avec un format de fournisseur survivant à son fournisseur, cette portabilité est l'essentiel.

Ce qui se cartographie clairement, et ce qui ne le fait pas

Markdown est délibérément minimal, ce qui est sa force et sa limite. La structure se traduit bien ; la présentation ne se traduit pas, et c'est généralement acceptable car la présentation est de toute façon le niveau que vous souhaitez remplacer.

Titres — les styles Ami Pro de la feuille .STY deviennent des niveaux de titre Markdown, donnant une véritable structure au document
Listes — les listes à puces et numérotées se convertissent en listes standard Markdown, y compris les imbrications
Accentuation — le gras et l’italique se traduisent directement ; le soulignement n’a pas d’équivalent Markdown et devient généralement une accentuation
Tables — les tableaux simples deviennent des tableaux à pipes ; les mises en page complexes avec cellules fusionnées ne peuvent pas être représentées et nécessitent un repli HTML ou une note
Images — les diagrammes WMF/EMF extraits sont enregistrés en tant que fichiers et référencés avec la syntaxe d'image standard
Équations — disponibles en LaTeX pour les moteurs capables de gérer les mathématiques, ou sous forme d'images liées lorsqu'ils ne le sont pas

Les feuilles de style sont ce qui rend les titres possibles

C'est le détail qui détermine si la conversion Markdown est utile ou inutile. Markdown n'a pas de concept de « Helvetica gras 16 points » — il a des niveaux de titre. La seule façon pour un convertisseur de savoir qu'une ligne est un titre de niveau deux plutôt qu'un paragraphe mis en évidence est de résoudre le style de paragraphe par rapport à la feuille de style .STY.

Avec la feuille de style présente, un document converti arrive avec une hiérarchie de titres à partir de laquelle vous pouvez créer une table des matières et diviser le contenu. Sans elle, vous obtenez une séquence plate de paragraphes avec quelques lignes en gras, et chacun des avantages ci-dessus disparaît.

Donc, avant de convertir une archive pour un pipeline de documents, vérifiez que les fichiers .STY ont été transférés depuis l'ancien serveur. Cela prend une minute et cela détermine le résultat de l'ensemble du projet.

Gestion des images dans un dépôt

1. Décidez où se trouvent les actifs

La plupart des générateurs de sites statiques s'attendent à ce que les images soient dans un répertoire dédié ou placées à côté de la page. Choisissez la convention avant de convertir afin de déplacer les fichiers une seule fois, et non de renommer les références dans des milliers de fichiers Markdown par la suite.

2. Surveiller la taille du dépôt

Les diagrammes extraits s'additionnent. Quelques milliers de documents avec des figures peuvent ajouter des centaines de mégaoctets à un dépôt auparavant uniquement textuel. Envisagez Git LFS, ou conservez les ressources dans un stockage d'objets et référencez-les par URL.

3. Normaliser les noms de fichiers

Les archives héritées sont remplies de noms de l'époque DOS, d'espaces et de majuscules/minuscules mixtes. Normalisez les noms en minuscules avec des traits d'union pendant le déplacement et conservez une table de correspondance afin de pouvoir toujours retrouver une page publiée à partir de son fichier .sam d'origine.

4. Choisissez une stratégie d'équation dès le départ

Si votre site affiche des mathématiques, utilisez le LaTeX extrait pour obtenir des formules nettes, sélectionnables et recherchables. Si ce n'est pas le cas, utilisez des images rendues et acceptez que les mathématiques ne soient pas recherchables. Mélanger les deux types dans un même archive est l'option à éviter.

Révision de milliers de fichiers convertis

Personne ne lit trois mille fichiers Markdown, mais Git rend la révision sélective faisable d'une manière qu'un dossier de fichiers DOCX ne permet pas. Validez le résultat de la conversion en un seul gros commit sur une branche, puis révisez par motif plutôt que par fichier.

Grep est l'outil principal ici. Cherchez des fichiers suspectement courts, des fichiers sans en-tête, des références d'images non résolues, des balises entre crochets éparses indiquant un trou dans l'analyse, et des caractères de remplacement indiquant un problème d'encodage. Chacune de ces recherches met en évidence une classe d'échec en quelques secondes.

Ajoutez de l'automatisation au pipeline pendant que vous y êtes : un vérificateur de liens pour détecter les références internes cassées, un validateur de métadonnées frontales si votre générateur l'exige, et une étape de construction qui échoue en cas d'images manquantes. Une fois que cela est passé, l'archive est dans le même régime de qualité que votre documentation maintenue.

Où Markdown est la mauvaise cible

Markdown ne peut délibérément pas exprimer une mise en page complexe, et certains documents Ami Pro ont été conçus plutôt qu'écrits — bulletins d'information, formulaires formatés, couvertures de rapports avec composition basée sur des cadres. Les forcer dans Markdown produit quelque chose de techniquement valide et pratiquement inutile.

Il en va de même pour les documents dont le sens est juridique et dépend de la présentation exacte : contrats exécutés, formulaires signés, avis officiels. Pour ceux-ci, PDF est le résultat fidèle, et si vous voulez qu'ils soient consultables aux côtés du Markdown, convertissez aux deux formats et liez le PDF depuis un bref stub Markdown.

Être sélectif n'est pas un compromis. Un dépôt de documents rempli de Markdown propres et structurés, plus un ensemble lié de PDF pour les documents nécessitant une mise en page fixe, est un meilleur résultat qu'un tas uniforme de conversions dégradées.

Ce que le Markdown apporte à une archive ancienne

Historique des versions, relecture et comparaisons pour des documents qui n’en ont jamais eu
Publiable avec le même générateur de site statique que la documentation actuelle
Des fichiers texte brut minuscules et portables, qui survivent à n’importe quel outil
Une structure de titres adaptée aux tables des matières et au découpage pour l’IA
Des équations LaTeX qui restent consultables au lieu de devenir des images

Les documents hérités méritent des outils modernes

L'écart entre un fichier .sam et un fichier Markdown dans un dépôt n'est pas seulement un changement de format. C'est la différence entre un contenu que personne ne peut inspecter et un contenu qui participe à la révision, à la recherche et à la publication automatique comme tout le reste que votre équipe écrit.

Confirmez les feuilles de style, décidez de vos conventions pour les ressources et les équations avant de commencer, convertissez l'archive en un seul passage, et faites une révision par grep plutôt qu'en lisant. Ensuite, envoyez-la par le même pipeline que le reste de vos documents.