AsciiDoc : Découvrir et maîtriser la syntaxe pour une documentation efficace
Yayınlandı: 20 June 2025
Giriş
AsciiDoc, yapılandırılmış teknik belgeler, makaleler, kitaplar ve sunumlar hazırlamak için tasarlanmış hafif bir işaretleme dili. Okunabilirliği, sözdizimi zenginliği ve HTML, PDF, DocBook vb. çeşitli formatlar üretebilme yetisiyle öne çıkar. Bu makalede, AsciiDoc’in temel sözdizimini inceleyecek ve hızlı başlangıç için ipuçları sunacağız.
AsciiDoc nedir?
AsciiDoc, belgeler açıklama dili, Markdown’a benzer ancak daha güçlüdür. Metinler, başlıklar, listeler, tablolar, kod blokları ve daha fazlasını etkili bir şekilde yapılandırmaya olanak tanır. Çoğunlukla açık kaynak proje dokümantasyonu, kitap yazma ve web yayınlama için popüler bir seçim olur.
AsciiDoc neden seçilmeli ?
-
Okunabilir ve sezgisel sözdizimi.
-
Karmaşık yapıların yerel desteği (tablolar, notlar, uyarılar vb.)
-
Çoklu format üretimi (HTML, PDF, ePub, DocBook…).
-
JBake veya Antora gibi statik site jeneratörleriyle kolay entegrasyon.
-
Özellikler ve uzantılarla gelişmiş kişiselleştirme
Kullanım Durumu Diyagramı (Use Case)
Bir kullanım durumu diyagramı, kullanıcılar ile sistem arasındaki temel etkileşimleri sunar. Bir belgeleme sistemi için basit bir örnek:
@startuml :Utilisateur: --> (Rédiger documentation) :Utilisateur: --> (Générer PDF) :Utilisateur: --> (Publier sur site web) (Rédiger documentation) ..> (Générer PDF) : inclut @enduml
zihin haritası
Zihin haritası (zihinsel harita) AsciiDoc ile ilgili kavramları ve ilişkilerini keşfetmek için idealdir :
@startmindmap * AsciiDoc ** Syntaxe *** Titres *** Listes *** Blocs de code *** Tableaux ** Extensions *** PlantUML *** MathJax ** Export *** HTML *** PDF *** EPUB @endmindmap
Flow Diyagramı (akış)
Bir akış diyagramı bir AsciiDoc belgesinin oluşturulma sürecini tanımlamaya olanak tanır:
@startuml start :Écrire fichier .adoc; :Ajouter images et diagrammes; if (Valider la syntaxe ?) then (oui) :Générer HTML/PDF; :Publier ou partager; else (non) :Corriger erreurs; :back to start; endif stop @enduml
AsciiDoc dosyasının temel yapısı
Bir AsciiDoc dosyası genellikle bir başlık, opsiyonel öznitelikler ve ardından yapılandırılmış içerikle başlar. İşte minimal bir örnek:
= Titre Principal
Auteur
2024-09-03
:toc:
:icons: font
Votre contenu commence ici...Temel sözdizimi
Başlıklar ve Bölümler
AsciiDoc birden fazla başlık seviyesini destekler :
= Titre de niveau 1
== Titre de niveau 2
=== Titre de niveau 3
==== Titre de niveau 4Metin kalın, italik ve monospace
*gras* _italique_ `monospace`Madde işareti ve numaralı listeler
* Élément 1
* Élément 2
. Premier
. Deuxième
. TroisièmeBağlantılar ve görseller
Lien standard : https://asciidoc.org[AsciiDoc]
Image : image::images/logo.png[AsciiDoc Logo]Kod blokları
[source,python]def hello(): print("Bonjour AsciiDoc !")
tablolar
|===
| Colonne 1 | Colonne 2
| Valeur A
| Valeur B
| Valeur C
| Valeur D
|===Notlar ve uyarılar
AsciiDoc görsel bilgi blokları sunar:
NOTE: Ceci est une note importante.
TIP: Conseil utile pour l’utilisateur.
WARNING: Attention à ce point.özellikler ve değişkenlerin kullanımı
Özel öznitelikler, değerleri yeniden kullanmamızı sağlar veya davranışları yapılandırır:
:project-name: AsciiDoc Explorer
Le projet s’appelle {project-name}.Genel kullanım senaryoları
-
Açık kaynak proje dokümantasyonu (README, teknik kılavuzlar) - Kitap ve e-kitap yazma - Otomatik statik web siteleri oluşturma (JBake, Antora) - Teknik sunumlar
iyi uygulamalar
-
Tutarlı başlıklar kullanın ve otomatik bir içerik tablosu (:toc:). - Önemli noktaları vurgulamak için uyarıları tercih edin. Dosyalarınızı yapılandırarak bakımı kolaylaştırın. - Açıklamalı kod bloklarından yararlanarak örnekleri gösterin.
Sonuç
AsciiDoc, güçlü ve erişilebilir bir araçtır; teknik dokümantasyon veya yapılandırılmış makale hazırlamak için kullanılır. Zengin sözdizimi, çoklu format üretimi ile birleştirildiğinde, gereksinimli geliştiriciler ve yazarlar için ideal bir ortak olur. Bir sonraki projenizde AsciiDoc’u deneyin ve farkı görün!
Daha ileri gitmek
-
Resmi dökümantasyon: https://asciidoc.org - Asciidoctor : https://asciidoctor.org - JBake ve AsciiDoc : https://jbake.org/docs/2.6.4/#asciidoc_support
Deneyimlerinizi ve ipuçlarınızı yorumda paylaşın !