AsciiDoc : Découvrir et maîtriser la syntaxe pour une documentation efficace

Содержание

Введение
Что такое AsciiDoc?
- Почему выбрать AsciiDoc?
Диаграмма вариантов использования (Use Case)
Диаграмма Mind Map
Диаграмма потока (поток)
Базовая структура файла AsciiDoc
фундаментальный синтаксис
Использование атрибутов и переменных
частые случаи использования
Хорошие практики
Заключение
Чтобы пойти дальше

Введение

Целевая аудитория : Разработчики, технические писатели и все, кто хочет писать техническую документацию или богатые статьи.

AsciiDoc — лёгкий язык разметки, предназначенный для создания структурированных технических документов, статей, книг или презентаций. Он выделяется своей читаемостью, богатством синтаксиса и возможностью генерировать различные форматы (HTML, PDF, DocBook и др.). В этой статье мы рассмотрим основной синтаксис AsciiDoc и дадим советы для быстрого освоения.

Что такое AsciiDoc?

AsciiDoc — это язык описания документов, похожий на Markdown, но более мощный. Он позволяет эффективно структурировать тексты, заголовки, списки, таблицы, блоки кода и многое другое. Его универсальность делает его популярным выбором для документирования проектов с открытым исходным кодом, написания книг и веб-публикации.

Почему выбрать AsciiDoc?

Читаемый и интуитивно понятный синтаксис.
Нативная поддержка сложных структур (таблицы, примечания, предупреждения и т.д.).
Многоформатная генерация (HTML, PDF, ePub, DocBook…).
Простая интеграция с генераторами статических сайтов, такими как JBake или Antora.
Расширенная настройка с использованием атрибутов и расширений.

Диаграмма вариантов использования (Use Case)

Диаграмма вариантов использования позволяет представить основные взаимодействия между пользователями и системой. Вот простой пример для системы документации:

@startuml
:Utilisateur: --> (Rédiger documentation)
:Utilisateur: --> (Générer PDF)
:Utilisateur: --> (Publier sur site web)
(Rédiger documentation) ..> (Générer PDF) : inclut
@enduml

Диаграмма Mind Map

Ментальная карта (mind map) идеальна для изучения концепций, связанных с AsciiDoc, и их связей:

@startmindmap
* AsciiDoc
** Syntaxe
*** Titres
*** Listes
*** Blocs de code
*** Tableaux
** Extensions
*** PlantUML
*** MathJax
** Export
*** HTML
*** PDF
*** EPUB
@endmindmap

Диаграмма потока (поток)

Блок-схема позволяет описать процесс генерации документа AsciiDoc:

@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

Файл AsciiDoc обычно начинается с заголовка, необязательных атрибутов, а затем следует структурированное содержимое. Вот минимальный пример:

= Titre Principal
Auteur
2024-09-03
:toc:
:icons: font

Votre contenu commence ici...

фундаментальный синтаксис

Заголовки и разделы

AsciiDoc поддерживает несколько уровней заголовков :

= Titre de niveau 1
== Titre de niveau 2
=== Titre de niveau 3
==== Titre de niveau 4

Текст жирный, курсив и моноширинный

*gras* _italique_ `monospace`

Маркированные и нумерованные списки

* Élément 1
* Élément 2

. Premier
. Deuxième
. Troisième

Ссылки и изображения

Lien standard : https://asciidoc.org[AsciiDoc]
Image : image::images/logo.png[AsciiDoc Logo]

Блоки кода

[source,python]

def hello(): print("Привет AsciiDoc !")

Таблицы

|===
| Colonne 1 | Colonne 2

| Valeur A
| Valeur B

| Valeur C
| Valeur D
|===

Заметки и предупреждения

AsciiDoc предлагает визуальные блоки информации :

NOTE: Ceci est une note importante.
TIP: Conseil utile pour l’utilisateur.
WARNING: Attention à ce point.

Использование атрибутов и переменных

Пользовательские атрибуты позволяют повторно использовать значения или настраивать поведение :

:project-name: AsciiDoc Explorer

Le projet s’appelle {project-name}.

частые случаи использования

Документация проекта с открытым исходным кодом (README, технические руководства) - Написание книг и электронных книг - Автоматическая генерация статических веб-сайтов (JBake, Antora) - Технические презентации

Хорошие практики

Используйте последовательные заголовки и автоматическое оглавление (:toc:). - Отдавайте предпочтение замечаниям, чтобы привлечь внимание к ключевым моментам. - Структурируйте ваши файлы для упрощения обслуживания. - Воспользуйтесь аннотированными блоками кода для иллюстрации примеров.

Заключение

AsciiDoc — мощный и доступный инструмент для написания любой технической документации или структурированной статьи. Его богатый синтаксис, совмещённый с многоформатной генерацией, делает его надежным союзником для требовательных разработчиков и авторов. Попробуйте AsciiDoc в своём следующем проекте и ощутите разницу!

Чтобы пойти дальше

Официальная документация : https://asciidoc.org - Asciidoctor : https://asciidoctor.org - JBake и AsciiDoc: https://jbake.org/docs/2.6.4/#asciidoc_support

Поделитесь своим опытом и советами в комментариях !