AsciiDoc : Ontdek en beheers de syntaxis voor effectieve documentatie
Gepubliceerd op 20 June 2025
Inleiding
AsciiDoc is een lichtgewicht opmaaktaal, ontworpen om gestructureerde technische documenten, artikelen, boeken of presentaties te schrijven. Het onderscheidt zich door de leesbaarheid, de syntactische rijkdom en het vermogen om verschillende formaten te genereren (HTML, PDF, DocBook, enzovoort). In dit artikel gaan we de essentiële syntaxis van AsciiDoc onderzoeken en tips geven voor een snelle kennismaking.
Wat is AsciiDoc?
AsciiDoc is een taal voor documentbeschrijving, vergelijkbaar met Markdown maar krachtiger. Het maakt het efficiënt mogelijk om teksten, titels, lijsten, tabellen, codeblokken en veel meer te structureren. De veelzijdigheid maakt het een populaire keuze voor de documentatie van open source-projecten, het schrijven van boeken en webpublicatie.
Waarom AsciiDoc kiezen?
-
Leesbare en intuïtieve syntaxis.
-
Native ondersteuning van complexe structuren (tabellen, notities, admonities, etc.)
-
Multi-formaatgeneratie (HTML, PDF, ePub, DocBook…)
-
Eenvoudige integratie met statische sitegeneratoren zoals JBake of Antora.
-
Geavanceerde aanpassing met attributen en extensies.
use-case diagram (Use Case)
Een gebruikscase-diagram toont de belangrijkste interacties tussen gebruikers en het systeem. Hier is een eenvoudig voorbeeld voor een documentatiesysteem:
@startuml :Gebruiker: --> (Documentatie schrijven) :gebruiker: --> (Genereren PDF) :Gebruiker: --> (Publiceren op de website) (Documentatie schrijven) ..> (Genereer PDF) : omvat @enduml
Mindmap diagram
De mind map (mentale kaart) is ideaal om de concepten die gerelateerd zijn aan AsciiDoc en hun relaties te verkennen:
@startmindmap * AsciiDoc ** Syntaxis *** Titels *** Lijsten *** Codeblokken *** Tabellen ** Extensies *** PlantUML *** MathJax ** Exporteren *** HTML *** PDF *** EPUB @endmindmap
stroomdiagram
Een flowdiagram maakt het mogelijk om het proces van genereren van een AsciiDoc-document te beschrijven:
@startuml start :Schrijven bestand .adoc; :Voeg afbeeldingen en diagrammen toe; if (Valider la syntaxe ?) then (oui) :Genereren HTML/PDF; :Publiceren of delen; else (non) :Fouten corrigeren; :terug naar het begin; endif stop @enduml
Basisstructuur van een AsciiDoc-bestand
Een AsciiDoc-bestand begint meestal met een titel, optionele attributen, gevolgd door gestructureerde inhoud. Hier is een minimalistisch voorbeeld:
= Titre Principal
Auteur
2024-09-03
:toc:
:icons: font
Votre contenu commence ici...basisyntaxis
Titels en secties
AsciiDoc ondersteunt meerdere niveaus van titels:
= Titre de niveau 1
== Titre de niveau 2
=== Titre de niveau 3
==== Titre de niveau 4Vet, cursief en monospaced tekst
*gras* _italique_ `monospace`Opsommingspunten en genummerde lijsten
* Élément 1
* Élément 2
. Premier
. Deuxième
. TroisièmeLinks en afbeeldingen
Lien standard : https://asciidoc.org[AsciiDoc]
Image : image::images/logo.png[AsciiDoc Logo]Codeblokken
[source,python]def hello(): print("Bonjour AsciiDoc !")
Tabellen
|===
| Colonne 1 | Colonne 2
| Valeur A
| Valeur B
| Valeur C
| Valeur D
|===Notities en waarschuwingen
AsciiDoc biedt visuele informatieblokken :
NOTE: Ceci est une note importante.
TIP: Conseil utile pour l’utilisateur.
WARNING: Attention à ce point.Gebruik van attributen en variabelen
Aangepaste attributen maken het mogelijk om waarden opnieuw te gebruiken of gedrag te configureren :
:project-name: AsciiDoc Explorer
Le projet s’appelle {project-name}.Veelvoorkomende gebruiksscenario’s
-
Documentatie open source project (README, technische handleidingen) - Schrijven van boeken en e-boeken - Automatische generatie van statische websites (JBake, Antora) - Technische presentaties
Beste praktijken
-
Gebruik consistente titels en een automatisch gegenereerde inhoudsopgave (:toc:). - Geef de voorkeur aan waarschuwingen om de aandacht te vestigen op belangrijke punten. - Structureer je bestanden om het onderhoud te faciliteren. Maak gebruik van de gemarkeerde codeblokken om voorbeelden te illustreren.
Conclusie
AsciiDoc is een krachtig en toegankelijk hulpmiddel voor het schrijven van elke technische documentatie of gestructureerd artikel. De rijke syntaxis, gecombineerd met multi-formaatgeneratie, maakt het een waardevolle bondgenoot voor veeleisende ontwikkelaars en schrijvers. Probeer AsciiDoc in uw volgende project uit en ontdek het verschil!
Verder gaan
-
Officiële documentatie : https://asciidoc.org - Asciidoctor: https://asciidoctor.org - JBake en AsciiDoc: https://jbake.org/docs/2.6.4/#asciidoc_support
Deel je ervaringen en tips in een reactie!