Формат markdown

В качестве основного формата написания документации к проекту выбран формат Markdown, точнее его спецификация CommonMark с некоторыми расширениями, описанными в этом разделе.

Таблицы

Таблицы как на GitHub:

| Head 1 | Head 2|
| --- | --- |
| cell 1 | cell 2 |
| cell 3 | cell 4 |

Результат:

Definition List

Definition List (формат как тут):

Определение 1
: Описание 1

Определение 2
: Описание 2

Результат:

Определение 1

Описание 1

Определение 2

Описание 2

Атрибуты

Атрибуты для сгенерированных html-элементов (формат как тут).

Header 1 {#section1 .css-class-red attr1=value1}
========

Параграф {style="color:red"}

Результат:

<h1 id="section1" class="css-class-red" attr1="value1">Header 1</h1>
<p style="color:red">Параграф</p>

Макрокоманды

Макрокомандой является параграф, который начинается с @@. Текст параграфа является текстом макрокоманды. Преобразуется в тег <cm>. Например такая разметка:

text1

@@code file=f1

text1

@@ cm1

будет преобразована в такой текст html:

<p>text1</p>
<cm>code file=f1</cm>
<p>text2</p>
<cm>cm1</cm>

Первое слово до пробела определяется как имя макрокоманды, остальной текст - атрибуты макрокоманды. Атрибуты в формате name=value. Если value не имеет пробелов, то его можно не брать в кавычки, иначе нужно брать в одинарные или двойные кавычки.

Свойства документа

Свойства документа. Блок должен быть указан в самом начале документа.

---
key1: value1
key2: value2
---

Начало документа тут.

Замечания

Блок с замечаниями (формат как тут).

!!! note
    Это замечание
    
!!! warning
    Это предупреждение

Результат:

Фрагменты кода

Для вставки фрагмента кода используется стандартный синтаксис markdown с указанием языка для подсветки. Язык можно не указывать, тогда будет отображен только текст без подсветки.

```groovy
def s = "hello"
```

```
def s = "hello"
```

Результат:

def s = "hello"

def s = "hello"

После языка можно указывать атрибуты в формате name=value, они становятся атрибутами div, обрамляющего кодовый блок. Атрибут title - заголовок кодового блока:

```groovy title=file1.groovy
def s = "hello"
```

Результат:

def s = "hello"

Картинки

Как в спецификации.

![](images/1.jpg)

в тексте ![](images/2.png) тоже можно

Результат:

<p><img src="images/1.jpg" alt="" /></p>
<p>в тексте <img src="images/2.png" alt="" /> тоже можно</p>