Что такое заголовок - объяснять не требуется. В зависимости от важности и вложенности, заголовки бывают нескольких уровней. Рекомендуется пользоваться лишь заголовками первого, второго и третьего уровней. Если вы хотите, чтобы текст был оформлен как заголовок первого уровня, его следует подчеркнуть символами =====, если второго уровня - символами -----, если третьего - символами ~~~~~, например:

Это заголовок первого уровня
============================

Это заголовок второго уровня
----------------------------

Это заголовок третьего уровня
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Заголовки должны отделяться от остального текста пустыми строками сверху и снизу.

Абзац, это кусок текста, ограниченный сверху и снизу пустыми строками. Обычно все абзацы располагаются на одном расстоянии от левой стороны документа, но если расстояние от края до какого-то одного блока текста превосходит расстояние до остльных, то этот текст оформляется как блок текста, сдвинутый относительно родительского на величину табуляции. Пример заголовка и трёх его абзацев (три стандартных, а один смещённый вправо относительно остальных):

Это заголовок первого уровня
============================

Это абзац текста, относящегося к заголовку
первого уровня.

Это ещё абзац текста, также относящийся к
заголовку первого уровня

    А этот абзац будет сдвинут относительно других
    на некоторое количество символов. Чтобы такого
    не было - внимательно следите за расстоянием
    от края до оформляемого текста.

Это последний абзац текста, также относящийся к
заголовку первого уровня

Повсеместно возникает необходимость выделять текст жирным шрифтом или курсивом. В ReST это деается очень просто. Если текст должен быть выведен курсивом, его необходимо заключить в символы , если жирным, то в символы *, например:

*Этот текст будет выведен курсивом*

**А этот текст будет выведен жирным шрифтом**

При необходимости вывести именно символ * так, чтобы он не вопринимался как элемент выделения, перед ним следует поставить обратный слэш или заключить в двойные обратные апострофы (на клавиатуре расположены на одной клавише со знаком ~), например так:

\*Этот текст будет выведен обычным шрифтом и будет окружён звездочками\*

``**Этот текст тоже будет окружён звездочками**``

Список - набор элементов. либо пронумерованных, либо обозначеных буквами, либо обозначенных какими-либо маркерами. Таким образом, единственное, что нужно для формирования списков, это записать их как обычный текст и перед каждым из пунктов поставить желаемый маркер.

После каждого элемента списка и перед каждым элементом списка должна быть пропущена пустая строка, иначе всё оформиться как обычный текст. Для оформления упорядоченных списков применяются следующие маркеры (обратите внимание на то, что после маркеров стоят точки - это необходимо):

1. и т.д. или 1) и т.д. или (1) и т.д. - арабские цифры

A. и т.д. - заглавные буквы латинского алфавита

a. и т.д. - строчные буквы латинского алфавита

I. и т.д. - большие римские цифры

i. и т.д. - маленькие римские цифры

Списки оформляются аналогично в зависимости от желаемого маркера, поэтому приведём пример оформления списка, элементы которого пронумерованы арабскими цифрами:

1) Это первый пункт

2) это второй пункт

Неупорядоченые списки оформляются аналогично упорядоченным, но с использованием своих маркеров. Основные маркеры следующие:

* - жирный закрашенный круг

- - пустой круг

+ - закрашенный квадрат

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

1) Это первый пункт

    - это первый пункт подсписка

    - это второй пункт подсписка

2) это второй пункт

Обратите внимание, что каждый из пунктов сверху и снизу отделён от других пустой строкой.

Для того чтобы оформить текст как список определений (есть некое слово или фраза, к которой существуют более длинные комментарии), сам термин пишется как обычный абзац, а пояснение к нему пишется с новой строки, без пропуска между термином и его определением пустых строк, с отступом влево. Например:

это какой-то термин

а это определение термина или любая другая информация о нём, которую вы желаете донести до пользователей

это ещё какой-то термин

а это ещё информация

При необходимости термины можно выделять жирным шрифтом или курсивом как описано выше.

Любая ссылка в тексте (начинающаяся с указания протокола, например http) будет оформлена как ссылка и ничего специального для этого делать не надо. Хотите добавить в документ ссылку на проект DreamBot? Делайте это следующим образом:

Спасибо проекту DreamBot (http://dreambot.ru/) за всё

Если текст ссылки хочется спрятать, то конструкция будет более сложная:

Спасибо проекту `DreamBot <http://dreambot.ru/>`_ за всё

В этом тексте слово "DreamBot" будет накрыто ссылкой на

Изображения

Для включения в документ изображений используется специальная директива image. Её параметром является адрес изображения. Например, чтобы добавить на страницу логотип проекта DreamBot, нужно в коде ReST написать следующее:

image::http://dreambot.ru/@@/images/logo.gif

Ссылка может быть как на локальное изображение, так и на удалённое.

Макросы DreamBot

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

Макросы Wiki позволяют использовать в ReST аналог wiki-ссылок. Каждая такая ссылка ведет на другую статью, или, при отсутствии подходящей статьи, на форму ее создания. Если ссылке соответствует несколько статей, то при переходе показывается их список.

keyword

Макрос keyword используется для указания ссылки на статью словаря, параметры:

1. ключевое слово,
2. текст, который появится под ссылкой на статью словаря (если параметр не указан, то под ссылкой будет первый параметр).

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

[ keyword:rest ]

[ keyword:rest:язык разметки ReST ]

name

Макрос name используется для указания ссылок на другие статьи по их имени (т.е. полю title (заголовок)), параметры:

1. имя статьи,
2. текст, который появится под ссылкой на статью словаря (если параметр не указан, то под ссылкой будет первый параметр).

Пример:

[ name:Десять слов про ReST ]

[ name:Десять слов про ReST:язык разметки ReST ]

Заключение

В этой небольшой статье мы рассмотрели основные элементы размерки документа в формате ReST, благодаря которым вы сможете легко оформить желаемым образом практически любую страницу. безусловно, возможности ReST несколько шире описанных, но исчерпывающее руководство по ReST - это отдельный фундаментальный труд, в котором для абсолютного большинства пользователей системы нет никакой необходимости.