Un éditeur de texte de type markdown.

Site Web

• Installer Ruby
• Installer AsciiDoc : gem install asciidoctor

docker pull asciidoctor/docker-asciidoctor

Pour exécuter une convertion, on lance docker puis asciidoctor.

docker run -v <your directory>:/documents/ --name asciidoc-to-html asciidoctor/docker-asciidoctor
asciidoctor -D /documents/output --out-file=specifications.fr.html doc/specifications/readme.fr.asciidoc

Utiliser une interface graphique avec Visual Studio Code :

• Installer Visual Studio Code
• Installer l'extension depuis Visual Studio Code Source github
• Installer et exécuter PlantUML Server via Docker : docker run -d -p 8080:8080 plantuml/plantuml-server:tomcat
• Configurer le module pour utiliser plantuml : éditer les préférences utilisateurs et ajouter :

    "asciidoc.preview.attributes": {
        "plantuml-server-url": "http://localhost:8080"
    }

• Activer l'aperçu via ctrl+shift+v.

Cela se fait avec le paquet po4a.

• Création du fichier de traduction

Utiliser le code de langage conformément à la norme ISO 639.

po4a-gettextize -f asciidoc -m documentation.asciidoc -p documentation_fr-FR.po

• Traduire la documentation

On peut utiliser poedit

• Création du fichier

po4a-translate -f asciidoc -m documentation.asciidoc -p documentation_fr-FR.po -l documentation_fr-FR.asciidoc -k 0

• Mettre à jour le fichier de traduction suite à la mise à jour de la documentation

po4a-updatepo -f asciidoc -m documentation.asciidoc -p documentation_fr-FR.asciidoc

Le projet fourni une image Travis qu'il est possible d'intégrer à GitHub.

La page ci-dessous explique parfaitement comment faire. Par contre, l'interface de Travis a changé depuis et il faudra un peu chercher.

Convert AsciiDoc to HTML/PDF & publish to GitHub Pages with Travis CI and Asciidoctor Docker containers Archive du 28/03/2016 le 04/04/2020

:last-update-label!:

Désactive la génération de la date lors du rendu HTML. Intéressant pour faire un diff sans se préoccuper de ce paramètre.

Utilise highlight.js.

• Exemple

:source-highlighter: highlight.js
:highlightjsdir: highlight

[source,sh]
----
mkdir build
----

• Compilation

Ici, on ne compile que le langage bash et cpp.

git clone --depth=1 https://github.com/highlightjs/highlight.js.git
cd highlightjs
node tools/build.js -t browser cpp bash

highlight.min.js est dans le dossier build.

Ensuite, il faut garder l'architecture suivante à coté du fichier HTML généré :

+highlight
   |highlight.min.js
   +styles
      |github.min.css

Pour le style, il faut prendre l'un des fichiers dans highlight.js\build\demo\styles et impérativement lui dossier le nom de fichier github.min.css.