Convertisseur en ligne gratuit de ASCIIDOC en EPUB

Les lecteurs d’ebooks et les systèmes de publication exigent généralement EPUB plutôt qu’un fichier source AsciiDoc. La conversion conserve ses titres, paragraphes, listes, liens, images et autres contenus structurés dans un format redistribuable que les lecteurs peuvent ouvrir sur des téléphones, des tablettes et des appareils dédiés à la lecture d’ebooks.

Qu’est-ce que le format ASCIIDOC ?

AsciiDoc est un format de balisage en texte brut destiné aux documents structurés tels que les livres, les manuels, la documentation logicielle, les articles et les fichiers README. Les auteurs écrivent les titres, listes, tableaux, liens, blocs de code, attributs, références croisées et avertissements à l’aide d’une syntaxe textuelle lisible, plutôt que de modifier un document binaire.

Les extensions source courantes comprennent .adoc, .asciidoc et .asc. Asciidoctor et Asciidoc utilisent ces fichiers pour générer des documents HTML, PDF, des pages man et des documents EPUB. Les développeurs les rencontrent généralement dans des dépôts de documentation, des projets de sites statiques, des projets basés sur Git et des systèmes de génération de documentation.

Qu’est-ce que le format EPUB ?

EPUB est un package d’ebook basé sur ZIP qui contient du contenu XHTML, des feuilles de style CSS, des métadonnées, des fichiers de navigation et, éventuellement, des images, des polices et d’autres ressources. EPUB 3 prend en charge le HTML sémantique, les mises en page responsives, la navigation, l’audio ou la vidéo, ainsi que l’écriture de droite à gauche ou verticale lorsque le système de lecture prend en charge ces fonctionnalités.

Contrairement à un PDF à mise en page fixe, le contenu EPUB se redistribue en fonction de la taille de l’écran, des paramètres de police et de l’orientation de l’appareil de lecture. Il convient à la distribution de documentations ou de livres longs via des lecteurs d’ebooks et des bibliothèques, ainsi qu’à la vérification du résultat avec des applications compatibles avec EPUB.

Comment convertir ASCIIDOC en EPUB

Utiliser Asciidoctor EPUB3

Asciidoctor EPUB3 est le choix le plus direct, car il comprend les constructions propres à AsciiDoc au lieu de traiter la source comme un balisage générique. Installez d’abord Ruby s’il n’est pas déjà disponible, puis installez le convertisseur :

gem install asciidoctor-epub3

Depuis le répertoire contenant le fichier source, exécutez :

asciidoctor-epub3 book.adoc -o book.epub

Remplacez book.adoc par le nom de fichier réel. Le convertisseur lit l’en-tête du document, les fichiers inclus, les images référencées, les attributs et les éléments structurels, puis écrit book.epub.

Pour un projet composé de plusieurs fichiers, conservez les sources incluses et les répertoires d’images aux emplacements relatifs attendus. Une commande courante avec un répertoire de travail personnalisé est :

asciidoctor-epub3 -D output book.adoc

Définissez les métadonnées du document dans l’en-tête AsciiDoc avant la conversion, par exemple :

= Book title
Author Name <author@example.com>
:revnumber: 1.0
:description: A short description
:doctype: book
:toc:
:sectnums:

Utilisez un attribut d’image tel que :imagesdir: images lorsque les chemins des images sont relatifs à un répertoire commun. Vérifiez que chaque image référencée existe et utilise un format pris en charge par les systèmes de lecture cibles, généralement JPEG, PNG ou SVG.

Convertir sans installer de logiciel

Vous pouvez convertir gratuitement le fichier sur le site web 101convert.com lorsqu’il n’est pas pratique d’installer Ruby ou Asciidoctor. Téléversez le fichier AsciiDoc, choisissez EPUB comme format de sortie, lancez la conversion, puis téléchargez l’ebook généré.

Utiliser Pandoc comme solution alternative

Pandoc peut convertir directement certains documents AsciiDoc :

pandoc book.adoc -o book.epub

Utilisez Pandoc pour les documents relativement simples ou lorsqu’il fait déjà partie du flux de publication. Asciidoctor EPUB3 préserve généralement plus fidèlement les attributs propres à AsciiDoc, les avertissements, les inclusions et les références croisées.

Qualité, compatibilité et limitations

EPUB est redistribuable, de sorte que les sauts de ligne fixes, les positions exactes des pages et les instructions de mise en page de type PDF ne peuvent pas être conservés de manière uniforme. La pagination, la gestion des veuves et orphelines et le retour à la ligne varient selon le système de lecture et les paramètres de police de l’utilisateur.

Les extensions AsciiDoc complexes, les convertisseurs personnalisés, les diagrammes intégrés, les macros non prises en charge et la mise en forme propre au PDF peuvent nécessiter des ajustements manuels. Générez les fichiers de diagrammes avant la conversion et utilisez des chemins relatifs pour toutes les ressources locales.

Ouvrez le résultat dans au moins un lecteur EPUB et vérifiez la table des matières, la hiérarchie des titres, les liens, les blocs de code, les tableaux, les images et les caractères spéciaux. Pour une validation au niveau du package, exécutez EPUBCheck :

epubcheck book.epub

Corrigez les ressources manquantes, le XHTML non valide, les erreurs de métadonnées et les avertissements de navigation avant de distribuer le fichier.