0 added
0 removed
Original
2026-01-01
Modified
2026-02-26
1
<p>Представьте, что вы пишите статью, книгу или обучающий курс. Но мало написать простой текст, еще его нужно сделать структурным: выделить заголовки и цитаты, оформить ссылки и формулы. Чтобы сделать материал понятным, нужно его обозначить его структуру. Для этого используются языки разметки - например,<strong>AsciiDoc</strong>.</p>
1
<p>Представьте, что вы пишите статью, книгу или обучающий курс. Но мало написать простой текст, еще его нужно сделать структурным: выделить заголовки и цитаты, оформить ссылки и формулы. Чтобы сделать материал понятным, нужно его обозначить его структуру. Для этого используются языки разметки - например,<strong>AsciiDoc</strong>.</p>
2
<p>В этом гайде разберемся, как создавать файлы в формате AsciiDoc, в каких программах их можно редактировать, как размечать текст и получить результат в HTML.</p>
2
<p>В этом гайде разберемся, как создавать файлы в формате AsciiDoc, в каких программах их можно редактировать, как размечать текст и получить результат в HTML.</p>
3
<h2>Содержание</h2>
3
<h2>Содержание</h2>
4
<ul><li><a>Почему нужно выбрать AsciiDoc</a></li>
4
<ul><li><a>Почему нужно выбрать AsciiDoc</a></li>
5
<li><a>Чем Asciidoc удобнее Markdown</a></li>
5
<li><a>Чем Asciidoc удобнее Markdown</a></li>
6
<li><a>Как начать работать с AsciiDoc</a></li>
6
<li><a>Как начать работать с AsciiDoc</a></li>
7
<li><a>Синтаксис AsciiDoc</a></li>
7
<li><a>Синтаксис AsciiDoc</a></li>
8
<li><a>Заключение</a></li>
8
<li><a>Заключение</a></li>
9
<li><a>Полезные ссылки</a></li>
9
<li><a>Полезные ссылки</a></li>
10
</ul><h2>Почему нужно выбрать AsciiDoc</h2>
10
</ul><h2>Почему нужно выбрать AsciiDoc</h2>
11
<p>Языки разметки помогают сформировать структуру в текстах, а также обозначить его основные элементы. С помощью конструкций для каждого элемента можно обозначить заголовок, выделить понятие или фрагмент кода, вставить ссылку или изображение.</p>
11
<p>Языки разметки помогают сформировать структуру в текстах, а также обозначить его основные элементы. С помощью конструкций для каждого элемента можно обозначить заголовок, выделить понятие или фрагмент кода, вставить ссылку или изображение.</p>
12
<p>В веб-разработке язык разметки -<strong>HTML</strong>. С его помощью размечаются данные на странице. Например, страница с этим гайдом тоже размечена языком HTML, а браузер интерпретирует ее по общим соглашениям. Благодаря HTML, на этой странице вы видите заголовки, списки и прочие элементы, которые мы ввели с помощью специальных конструкций.</p>
12
<p>В веб-разработке язык разметки -<strong>HTML</strong>. С его помощью размечаются данные на странице. Например, страница с этим гайдом тоже размечена языком HTML, а браузер интерпретирует ее по общим соглашениям. Благодаря HTML, на этой странице вы видите заголовки, списки и прочие элементы, которые мы ввели с помощью специальных конструкций.</p>
13
<p>Но многие специалисты, которые работают с HTML, считают его неудобным. Например, чтобы создать список, в этом языке разметки используют такую конструкцию:</p>
13
<p>Но многие специалисты, которые работают с HTML, считают его неудобным. Например, чтобы создать список, в этом языке разметки используют такую конструкцию:</p>
14
<p>Размечать текст таким образом не очень удобно:</p>
14
<p>Размечать текст таким образом не очень удобно:</p>
15
<ul><li>Пришлось ввести дополнительные 48 символов, которые не имеют отношения к тексту</li>
15
<ul><li>Пришлось ввести дополнительные 48 символов, которые не имеют отношения к тексту</li>
16
<li>Была высокая вероятность ошибиться. Если бы мы забыли указать <li></li> или <ul></ul>, то браузер вывел бы разметку неправильно. Подобная ошибка может затронуть и соседние блоки с текстом</li>
16
<li>Была высокая вероятность ошибиться. Если бы мы забыли указать <li></li> или <ul></ul>, то браузер вывел бы разметку неправильно. Подобная ошибка может затронуть и соседние блоки с текстом</li>
17
<li>Работать с такой разметкой сложно, потому что часто писатели, контент-менеджеры и редакторы не знают язык HTML</li>
17
<li>Работать с такой разметкой сложно, потому что часто писатели, контент-менеджеры и редакторы не знают язык HTML</li>
18
</ul><p>Решить эту проблему можно с помощью сторонних форматов разметки текстов - например,<strong>AsciiDoc</strong>. В этом гайде рассмотрим именно этот формат.</p>
18
</ul><p>Решить эту проблему можно с помощью сторонних форматов разметки текстов - например,<strong>AsciiDoc</strong>. В этом гайде рассмотрим именно этот формат.</p>
19
<p>Работать с AsciiDoc намного удобнее. Чтобы структурировать текст, нужно вводить минимальное количество дополнительных символов. Например, список из примера выше можно написать так:</p>
19
<p>Работать с AsciiDoc намного удобнее. Чтобы структурировать текст, нужно вводить минимальное количество дополнительных символов. Например, список из примера выше можно написать так:</p>
20
<p>* Первый пункт списка * Второй пункт списка ** Первый подпункт второго пункта списка ** Второй подпункт второго пункта списка</p>
20
<p>* Первый пункт списка * Второй пункт списка ** Первый подпункт второго пункта списка ** Второй подпункт второго пункта списка</p>
21
<p>Как видите, здесь мы добавили лишь шесть дополнительных символов - вместо 48 в HTML.</p>
21
<p>Как видите, здесь мы добавили лишь шесть дополнительных символов - вместо 48 в HTML.</p>
22
<p><strong>AsciiDoc</strong>- это не единственный язык разметки с простым и удобным форматированием. Еще писатели часто используют<strong>Markdown</strong>, который тоже хорошо заменяет HTML. Но есть случаи, когда AsciiDoc справляется лучше. Расскажем о них подробнее.</p>
22
<p><strong>AsciiDoc</strong>- это не единственный язык разметки с простым и удобным форматированием. Еще писатели часто используют<strong>Markdown</strong>, который тоже хорошо заменяет HTML. Но есть случаи, когда AsciiDoc справляется лучше. Расскажем о них подробнее.</p>
23
<h2>Чем Asciidoc удобнее Markdown</h2>
23
<h2>Чем Asciidoc удобнее Markdown</h2>
24
<p>Если вы работаете с текстами в Markdown и вам хватает его функциональности, то нет смысла переходить на другой язык.</p>
24
<p>Если вы работаете с текстами в Markdown и вам хватает его функциональности, то нет смысла переходить на другой язык.</p>
25
<p>Однако у AsciiDoc есть ряд достоинств, которых нет у Markdown.</p>
25
<p>Однако у AsciiDoc есть ряд достоинств, которых нет у Markdown.</p>
26
<h3>Макросы</h3>
26
<h3>Макросы</h3>
27
<p>В AsciiDoc удобнее добавлять элементы на страницу с помощью<strong>макросов</strong>- небольших фрагментов кода, который помогает автоматизировать рутинные задачи.</p>
27
<p>В AsciiDoc удобнее добавлять элементы на страницу с помощью<strong>макросов</strong>- небольших фрагментов кода, который помогает автоматизировать рутинные задачи.</p>
28
<p>Для примера рассмотрим, как вставлять видео из YouTube в Markdown и AsciiDoc.</p>
28
<p>Для примера рассмотрим, как вставлять видео из YouTube в Markdown и AsciiDoc.</p>
29
<p>Чтобы вставить видео из Youtube с помощью Markdown, можно скопировать HTML-код с тегом <iframe> и добавить его на страницу. Тогда код будет выглядеть так:</p>
29
<p>Чтобы вставить видео из Youtube с помощью Markdown, можно скопировать HTML-код с тегом <iframe> и добавить его на страницу. Тогда код будет выглядеть так:</p>
30
<p>Чтобы добавить видео в формате AsciiDoc, используется макрос video. С его помощью добавляют видео как со своего компьютера, так и со сторонних ресурсов. Вот как будет выглядеть разметка в формате AsciiDoc:</p>
30
<p>Чтобы добавить видео в формате AsciiDoc, используется макрос video. С его помощью добавляют видео как со своего компьютера, так и со сторонних ресурсов. Вот как будет выглядеть разметка в формате AsciiDoc:</p>
31
<p>== Наше самое популярное видео Введение в логику, урок 1: Базовые понятия video::eXI_TFW5Cdo[youtube, width=560, height=315]</p>
31
<p>== Наше самое популярное видео Введение в логику, урок 1: Базовые понятия video::eXI_TFW5Cdo[youtube, width=560, height=315]</p>
32
<p>Как видите, здесь код выглядит меньше, красивее и понятнее. Вместо HTML-кода используется конструкция с идентификатором видео, его источником, шириной и высотой. Остальное AsciiDoc сделает самостоятельно.</p>
32
<p>Как видите, здесь код выглядит меньше, красивее и понятнее. Вместо HTML-кода используется конструкция с идентификатором видео, его источником, шириной и высотой. Остальное AsciiDoc сделает самостоятельно.</p>
33
<p>Таких макросов в AsciiDoc много. С их помощью можно добавлять аудио, видео, создавать кнопки для взаимодействий, добавлять готовую верстку для блоков и прочее. Их можно найти<a>в официальной документации к AsciiDoc</a>.</p>
33
<p>Таких макросов в AsciiDoc много. С их помощью можно добавлять аудио, видео, создавать кнопки для взаимодействий, добавлять готовую верстку для блоков и прочее. Их можно найти<a>в официальной документации к AsciiDoc</a>.</p>
34
<p>Макросы - не единственное преимущество перед Markdown. Помимо этого используются и другие функции, которые работают по единому стандарту и доступны в AsciiDoc. Например, можно обозначать математические формулы. Эти преимущества не означают, что нельзя сделать такие же блоки на Markdown. Но в AsciiDoc для этого используются официальные стандарты. При этом новые функции работают предсказуемо и понятно, а их написание стандартизировано.</p>
34
<p>Макросы - не единственное преимущество перед Markdown. Помимо этого используются и другие функции, которые работают по единому стандарту и доступны в AsciiDoc. Например, можно обозначать математические формулы. Эти преимущества не означают, что нельзя сделать такие же блоки на Markdown. Но в AsciiDoc для этого используются официальные стандарты. При этом новые функции работают предсказуемо и понятно, а их написание стандартизировано.</p>
35
<p>Далее расскажем, как разметить текст в AsciiDoc. Но чтобы сразу применять новые знания на практике, нужно подготовиться.</p>
35
<p>Далее расскажем, как разметить текст в AsciiDoc. Но чтобы сразу применять новые знания на практике, нужно подготовиться.</p>
36
<h2>Как начать работать с AsciiDoc</h2>
36
<h2>Как начать работать с AsciiDoc</h2>
37
<p>Чтобы начать работать с форматом AsciiDoc, создайте файл с расширением<strong>.adoc</strong>. Так вы сможете сразу повторять примеры гайда.</p>
37
<p>Чтобы начать работать с форматом AsciiDoc, создайте файл с расширением<strong>.adoc</strong>. Так вы сможете сразу повторять примеры гайда.</p>
38
<p>Редактировать файл можно стандартным блокнотом или редактором: например, VSCode, Sublime Text, Atom. Открыть файл можно с помощью браузера, у которого установлено расширение Asciidoctor.js Live Preview. Вот ссылки на расширение в магазинах для конкретных браузеров:</p>
38
<p>Редактировать файл можно стандартным блокнотом или редактором: например, VSCode, Sublime Text, Atom. Открыть файл можно с помощью браузера, у которого установлено расширение Asciidoctor.js Live Preview. Вот ссылки на расширение в магазинах для конкретных браузеров:</p>
39
<ul><li><a>Chrome</a></li>
39
<ul><li><a>Chrome</a></li>
40
<li><a>Edge</a></li>
40
<li><a>Edge</a></li>
41
<li><a>Firefox</a></li>
41
<li><a>Firefox</a></li>
42
<li><a>Opera</a></li>
42
<li><a>Opera</a></li>
43
<li><a>Safari</a></li>
43
<li><a>Safari</a></li>
44
</ul><p>Если вы используете редактор VSCode, можно установить дополнение<a>AsciiDoc</a>. Оно добавит в редактор подсветку синтаксиса, экспорт в PDF, HTML и функцию Live Preview:</p>
44
</ul><p>Если вы используете редактор VSCode, можно установить дополнение<a>AsciiDoc</a>. Оно добавит в редактор подсветку синтаксиса, экспорт в PDF, HTML и функцию Live Preview:</p>
45
<p>Если интересно только попробовать разметку, но ничего дополнительно не устанавливать, то можно воспользоваться<a>AsciiDoc Live</a>. Это онлайн-редактор, в котором можно сразу увидеть результат преобразования разметки в HTML. При этом можно экспортировать текст из формата AsciiDoc в HTML.</p>
45
<p>Если интересно только попробовать разметку, но ничего дополнительно не устанавливать, то можно воспользоваться<a>AsciiDoc Live</a>. Это онлайн-редактор, в котором можно сразу увидеть результат преобразования разметки в HTML. При этом можно экспортировать текст из формата AsciiDoc в HTML.</p>
46
<p>Разработчики AsciiDoc советуют не использовать Word, Libre Office, Google Docs и другие тяжелые редакторы. Они мешают работать с .adoc. Вам придется сначала оформлять текст в редакторе, а потом переносить в .adoc и переделывать форматирование еще раз. Это двойная работа, и ее можно избежать, если сразу начинать работу с текстом в формате .adoc.</p>
46
<p>Разработчики AsciiDoc советуют не использовать Word, Libre Office, Google Docs и другие тяжелые редакторы. Они мешают работать с .adoc. Вам придется сначала оформлять текст в редакторе, а потом переносить в .adoc и переделывать форматирование еще раз. Это двойная работа, и ее можно избежать, если сразу начинать работу с текстом в формате .adoc.</p>
47
<p>Теперь, когда вы готовы к работе с AsciiDoc, можно разобрать его синтаксис. Советуем сразу применять знания на практике, чтобы видеть, как это работает.</p>
47
<p>Теперь, когда вы готовы к работе с AsciiDoc, можно разобрать его синтаксис. Советуем сразу применять знания на практике, чтобы видеть, как это работает.</p>
48
<h2>Синтаксис AsciiDoc</h2>
48
<h2>Синтаксис AsciiDoc</h2>
49
<p>AsciiDoc напоминает формат<a>разметки Markdown</a>. Если вы работали с ним, то многие вещи покажутся похожими и интуитивно понятными. И наоборот, если вы знаете AsciiDoc, то использование Markdown не вызовет трудностей.</p>
49
<p>AsciiDoc напоминает формат<a>разметки Markdown</a>. Если вы работали с ним, то многие вещи покажутся похожими и интуитивно понятными. И наоборот, если вы знаете AsciiDoc, то использование Markdown не вызовет трудностей.</p>
50
<p>Еще AsciiDoc интерпретирует многие записи формата Markdown. Если у вас есть текст в Markdown, то попробуйте поменять расширение и посмотреть, как много элементов останутся такими же. Список совместимости можно посмотреть в<a>документации</a>.</p>
50
<p>Еще AsciiDoc интерпретирует многие записи формата Markdown. Если у вас есть текст в Markdown, то попробуйте поменять расширение и посмотреть, как много элементов останутся такими же. Список совместимости можно посмотреть в<a>документации</a>.</p>
51
<p>Рассмотрим основные примеры разметки, которых хватит для оформления базового текста. Мы будем разбирать, как разметить:</p>
51
<p>Рассмотрим основные примеры разметки, которых хватит для оформления базового текста. Мы будем разбирать, как разметить:</p>
52
<ul><li>Параграфы</li>
52
<ul><li>Параграфы</li>
53
<li>Заголовки</li>
53
<li>Заголовки</li>
54
<li>Выделение</li>
54
<li>Выделение</li>
55
<li>Списки</li>
55
<li>Списки</li>
56
<li>Код</li>
56
<li>Код</li>
57
<li>Ссылки</li>
57
<li>Ссылки</li>
58
<li>Цитаты</li>
58
<li>Цитаты</li>
59
<li>Изображения</li>
59
<li>Изображения</li>
60
<li>Таблицы</li>
60
<li>Таблицы</li>
61
<li>Математические формулы</li>
61
<li>Математические формулы</li>
62
</ul><p>Разберем разметку каждого элемента подробнее.</p>
62
</ul><p>Разберем разметку каждого элемента подробнее.</p>
63
<h3>Параграфы</h3>
63
<h3>Параграфы</h3>
64
<p>Каждая новая строка в тексте - новый параграф. Чтобы добавить его, нужно перейти на новую строчку. Но чтобы параграфы отделялись друг от друга, необходимо оставить между ними пустую строку. Так будет понятно, где закончился один параграф и начался другой:</p>
64
<p>Каждая новая строка в тексте - новый параграф. Чтобы добавить его, нужно перейти на новую строчку. Но чтобы параграфы отделялись друг от друга, необходимо оставить между ними пустую строку. Так будет понятно, где закончился один параграф и начался другой:</p>
65
<p>Здесь видно, что первый параграф находится на строке "1", строка "2" - разделительная, и на строке "3" находится следующий параграф. Никаких символов, чтобы обозначить параграф, не нужно.</p>
65
<p>Здесь видно, что первый параграф находится на строке "1", строка "2" - разделительная, и на строке "3" находится следующий параграф. Никаких символов, чтобы обозначить параграф, не нужно.</p>
66
<h3>Заголовки</h3>
66
<h3>Заголовки</h3>
67
<p>Заголовками отделяют логические блоки, чтобы читателю было проще ориентироваться в тексте. В AsciiDoc используется шесть уровней заголовков:</p>
67
<p>Заголовками отделяют логические блоки, чтобы читателю было проще ориентироваться в тексте. В AsciiDoc используется шесть уровней заголовков:</p>
68
<p>= - заголовок первого уровня</p>
68
<p>= - заголовок первого уровня</p>
69
<p>== - заголовок второго уровня</p>
69
<p>== - заголовок второго уровня</p>
70
<p>=== - заголовок третьего уровня</p>
70
<p>=== - заголовок третьего уровня</p>
71
<p>==== - заголовок четвертого уровня</p>
71
<p>==== - заголовок четвертого уровня</p>
72
<p>===== - заголовок пятого уровня</p>
72
<p>===== - заголовок пятого уровня</p>
73
<p>====== - заголовок шестого уровня</p>
73
<p>====== - заголовок шестого уровня</p>
74
<p>Размеры заголовков при переходе от первого к последнему уровню уменьшаются. Это помогает обозначать блоки одного уровня.</p>
74
<p>Размеры заголовков при переходе от первого к последнему уровню уменьшаются. Это помогает обозначать блоки одного уровня.</p>
75
<h3>Выделение</h3>
75
<h3>Выделение</h3>
76
<p>В текстах полезно выделять ключевые слова или мысли, так читатель концентрирует внимание на самой важной части. Выделять текст можно с помощью<strong>жирного шрифта</strong>или<em>курсива</em>:</p>
76
<p>В текстах полезно выделять ключевые слова или мысли, так читатель концентрирует внимание на самой важной части. Выделять текст можно с помощью<strong>жирного шрифта</strong>или<em>курсива</em>:</p>
77
<p>А вы знаете, что _AsciiDoc_ - *невероятный инструмент* для разметки текста?</p>
77
<p>А вы знаете, что _AsciiDoc_ - *невероятный инструмент* для разметки текста?</p>
78
<p>Выделить жирным шрифтом можно с помощью двух символов * по краям выделенного текста. А курсив обозначается с помощью _ тоже по краям текста, который нужно выделить.</p>
78
<p>Выделить жирным шрифтом можно с помощью двух символов * по краям выделенного текста. А курсив обозначается с помощью _ тоже по краям текста, который нужно выделить.</p>
79
<h3>Списки</h3>
79
<h3>Списки</h3>
80
<p>Как и в HTML, в AsciiDoc есть списки двух видов:</p>
80
<p>Как и в HTML, в AsciiDoc есть списки двух видов:</p>
81
<ul><li>Нумерованные</li>
81
<ul><li>Нумерованные</li>
82
<li>Маркированные</li>
82
<li>Маркированные</li>
83
</ul><p>Чтобы создать нумерованный список, используйте символ .:</p>
83
</ul><p>Чтобы создать нумерованный список, используйте символ .:</p>
84
<p><strong>Простой нумерованный список</strong></p>
84
<p><strong>Простой нумерованный список</strong></p>
85
<p>== Пошаговый рецепт . Налить 200 грамм молока . Добавить 50 грамм мороженого . Влить 10 грамм сиропа . Перемешать в блендере в течение пяти минут</p>
85
<p>== Пошаговый рецепт . Налить 200 грамм молока . Добавить 50 грамм мороженого . Влить 10 грамм сиропа . Перемешать в блендере в течение пяти минут</p>
86
<p>Маркированный список создается с помощью символа *. Например, вот так будет выглядеть список покупок:</p>
86
<p>Маркированный список создается с помощью символа *. Например, вот так будет выглядеть список покупок:</p>
87
<p><strong>Простой маркированный список</strong></p>
87
<p><strong>Простой маркированный список</strong></p>
88
<p>== Купить * Молоко * Сыр * Йогурт греческий * Йогурт с малиной * Пельмени</p>
88
<p>== Купить * Молоко * Сыр * Йогурт греческий * Йогурт с малиной * Пельмени</p>
89
<p>Еще в AsciiDoc можно создавать большие вложенности одних пунктов в другие. Для этого нужно добавить второй символ списка. Также списки можно комбинировать, создавая сложные многоуровневые конструкции:</p>
89
<p>Еще в AsciiDoc можно создавать большие вложенности одних пунктов в другие. Для этого нужно добавить второй символ списка. Также списки можно комбинировать, создавая сложные многоуровневые конструкции:</p>
90
<p><strong>Сложный многоуровневый список</strong></p>
90
<p><strong>Сложный многоуровневый список</strong></p>
91
<p>== Купить * В продуктовом .. Молоко .. Сыр .. Йогурт ... Греческий ... С малиной .. Пельмени * В книжном ** Ясно, понятно ** Пиши, сокращай</p>
91
<p>== Купить * В продуктовом .. Молоко .. Сыр .. Йогурт ... Греческий ... С малиной .. Пельмени * В книжном ** Ясно, понятно ** Пиши, сокращай</p>
92
<h3>Оформление кода</h3>
92
<h3>Оформление кода</h3>
93
<p>Текстовый файл часто создается, чтобы описать проект, где содержится код. В Хекслете мы учим программированию, поэтому тоже постоянно показываем фрагменты кода.</p>
93
<p>Текстовый файл часто создается, чтобы описать проект, где содержится код. В Хекслете мы учим программированию, поэтому тоже постоянно показываем фрагменты кода.</p>
94
<p>Чтобы код не терялся в тексте, его тоже нужно выделять. Так будет виден его синтаксис. Для этого используется конструкция:</p>
94
<p>Чтобы код не терялся в тексте, его тоже нужно выделять. Так будет виден его синтаксис. Для этого используется конструкция:</p>
95
<p>[source,lang] ---- Код ----</p>
95
<p>[source,lang] ---- Код ----</p>
96
<p>lang - это параметр, который указывает язык. Строки с этим параметром не видно в итоговом тексте. Код - это часть кода, который требуется показать.</p>
96
<p>lang - это параметр, который указывает язык. Строки с этим параметром не видно в итоговом тексте. Код - это часть кода, который требуется показать.</p>
97
<p>Вот как выглядит оформление кода на языке Ruby:</p>
97
<p>Вот как выглядит оформление кода на языке Ruby:</p>
98
<p>[source,ruby] ---- require 'sinatra' get '/hi' do "Hello World!" end ----</p>
98
<p>[source,ruby] ---- require 'sinatra' get '/hi' do "Hello World!" end ----</p>
99
<p>Такое оформление кода поможет сторонним плагинам сделать подсветку синтаксиса.</p>
99
<p>Такое оформление кода поможет сторонним плагинам сделать подсветку синтаксиса.</p>
100
<h3>Ссылки</h3>
100
<h3>Ссылки</h3>
101
<p>С помощью ссылок можно отсылаться к другому материалу или странице, на которую пользователю стоит перейти. Это помогает наполнить материал дополнительной информацией.</p>
101
<p>С помощью ссылок можно отсылаться к другому материалу или странице, на которую пользователю стоит перейти. Это помогает наполнить материал дополнительной информацией.</p>
102
<p>Чтобы создать ссылку, используйте конструкцию link[description], где:</p>
102
<p>Чтобы создать ссылку, используйте конструкцию link[description], где:</p>
103
<ul><li>link - ссылка</li>
103
<ul><li>link - ссылка</li>
104
<li>description - текст ссылки</li>
104
<li>description - текст ссылки</li>
105
</ul><p>Например, нам нужно вставить ссылку на блог Хекслета:</p>
105
</ul><p>Например, нам нужно вставить ссылку на блог Хекслета:</p>
106
<p>https://ru.hexlet.io/blog/posts/[Блог Хекслет]</p>
106
<p>https://ru.hexlet.io/blog/posts/[Блог Хекслет]</p>
107
<p>Вот так это будет выглядеть в редакторе и в итоговом тексте:</p>
107
<p>Вот так это будет выглядеть в редакторе и в итоговом тексте:</p>
108
<p>Чтобы текст залинковался, между ссылкой и [] не должно быть пробела.</p>
108
<p>Чтобы текст залинковался, между ссылкой и [] не должно быть пробела.</p>
109
<p>В процессе написание текстов некоторые ссылки могут быть добавлены в виде текста, чтобы по ним нельзя было перейти. Например, чтобы указать ссылку на какую-то несуществующую тестовую страницу для описания работы кода. Если добавить ссылку не по шаблону link[description], то она будет автоматически преобразована в ссылку, где вместо описания будет вставлен URL.</p>
109
<p>В процессе написание текстов некоторые ссылки могут быть добавлены в виде текста, чтобы по ним нельзя было перейти. Например, чтобы указать ссылку на какую-то несуществующую тестовую страницу для описания работы кода. Если добавить ссылку не по шаблону link[description], то она будет автоматически преобразована в ссылку, где вместо описания будет вставлен URL.</p>
110
<p>Чтобы вставить ссылку как текст, используется экранирование. Таким образом говорится, что не нужно обрабатывать этот участок текста. В AsciiDoc для экранирования ссылок используется символ \, который ставится перед ссылкой.</p>
110
<p>Чтобы вставить ссылку как текст, используется экранирование. Таким образом говорится, что не нужно обрабатывать этот участок текста. В AsciiDoc для экранирования ссылок используется символ \, который ставится перед ссылкой.</p>
111
<p>\https://ru.hexlet.io/</p>
111
<p>\https://ru.hexlet.io/</p>
112
<p>Такая ссылка будет обработана как текст и по ней нельзя перейти с помощью клика мышкой.</p>
112
<p>Такая ссылка будет обработана как текст и по ней нельзя перейти с помощью клика мышкой.</p>
113
<h3>Цитаты</h3>
113
<h3>Цитаты</h3>
114
<p>Часто в текстах нужно вставлять прямую речь, например, цитату эксперта. Для этого используется символ >:</p>
114
<p>Часто в текстах нужно вставлять прямую речь, например, цитату эксперта. Для этого используется символ >:</p>
115
<p>> Основная задача не в том, чтобы найти ошибку, а в том, чтобы найти условия, при которых код продолжает свою работу</p>
115
<p>> Основная задача не в том, чтобы найти ошибку, а в том, чтобы найти условия, при которых код продолжает свою работу</p>
116
<p>Если цитата содержит несколько строк, то их можно соединить с помощью конструкции > +:</p>
116
<p>Если цитата содержит несколько строк, то их можно соединить с помощью конструкции > +:</p>
117
<p>> Эффективная отладка кода + > - один из ключевых показателей хороших разработчиков</p>
117
<p>> Эффективная отладка кода + > - один из ключевых показателей хороших разработчиков</p>
118
<p>В итоговом тексте цитата выделится кавычками, и читатель поймет, что это прямая речь эксперта.</p>
118
<p>В итоговом тексте цитата выделится кавычками, и читатель поймет, что это прямая речь эксперта.</p>
119
<h3>Изображения</h3>
119
<h3>Изображения</h3>
120
<p>Изображения - инструмент, который помогает визуализировать текст. Например, без них этот гайд был бы менее понятным.</p>
120
<p>Изображения - инструмент, который помогает визуализировать текст. Например, без них этот гайд был бы менее понятным.</p>
121
<p>Изображения добавляются с помощью конструкции image::image.png[], где:</p>
121
<p>Изображения добавляются с помощью конструкции image::image.png[], где:</p>
122
<ul><li>image.png - путь к изображению. Он может быть как точным, так и относительно "отправной точки". Это зависит от того, где располагается файл</li>
122
<ul><li>image.png - путь к изображению. Он может быть как точным, так и относительно "отправной точки". Это зависит от того, где располагается файл</li>
123
<li>[] - описание изображения, которым пользуются программы для чтения с экрана или поисковики</li>
123
<li>[] - описание изображения, которым пользуются программы для чтения с экрана или поисковики</li>
124
</ul><p>Например, вот так будет выглядеть вставка логотипа Хекслета, который находится в https://github.com/Hexlet/assets/blob/master/images/hexlet_logo.png?raw=true:</p>
124
</ul><p>Например, вот так будет выглядеть вставка логотипа Хекслета, который находится в https://github.com/Hexlet/assets/blob/master/images/hexlet_logo.png?raw=true:</p>
125
<p>image::https://github.com/Hexlet/assets/blob/master/images/hexlet_logo.png?raw=true[Логотип Хекслета]</p>
125
<p>image::https://github.com/Hexlet/assets/blob/master/images/hexlet_logo.png?raw=true[Логотип Хекслета]</p>
126
<h3>Таблицы</h3>
126
<h3>Таблицы</h3>
127
<p>Таблицы - способ группировки схожей информации, с помощью которой можно заменить список, если в нем есть однотипная информация.</p>
127
<p>Таблицы - способ группировки схожей информации, с помощью которой можно заменить список, если в нем есть однотипная информация.</p>
128
<p>Предположим, что нужно добавить информацию о языке программирования и его области применений. Выделим две категории информации:</p>
128
<p>Предположим, что нужно добавить информацию о языке программирования и его области применений. Выделим две категории информации:</p>
129
<ol><li>Язык</li>
129
<ol><li>Язык</li>
130
<li>Область применения</li>
130
<li>Область применения</li>
131
</ol><p>Такую информацию можно представить в виде таблицы из двух колонок. Чтобы создать таблицу в AsciiDoc, используют несколько типов синтаксиса. Для примера возьмем синтаксис, который похож на список:</p>
131
</ol><p>Такую информацию можно представить в виде таблицы из двух колонок. Чтобы создать таблицу в AsciiDoc, используют несколько типов синтаксиса. Для примера возьмем синтаксис, который похож на список:</p>
132
<p>[cols=2] |==== |HTML |Web-страницы и приложения в браузере |JS |Web-разработка pass:[<br>] Мобильная разработка pass:[<br>] GameDev |====</p>
132
<p>[cols=2] |==== |HTML |Web-страницы и приложения в браузере |JS |Web-разработка pass:[<br>] Мобильная разработка pass:[<br>] GameDev |====</p>
133
<ul><li>[cols=2] - определение количества колонок</li>
133
<ul><li>[cols=2] - определение количества колонок</li>
134
<li>Парные |==== - определение начала и конца таблицы</li>
134
<li>Парные |==== - определение начала и конца таблицы</li>
135
<li>| - ячейка таблицы</li>
135
<li>| - ячейка таблицы</li>
136
</ul><p>Но такая таблица будет непонятной, так как нет заголовков. Если их добавить, то синтаксис будет выглядеть так:</p>
136
</ul><p>Но такая таблица будет непонятной, так как нет заголовков. Если их добавить, то синтаксис будет выглядеть так:</p>
137
<p>|==== |Язык |Где используется |HTML |Web-страницы и приложения в браузере |JS |Web-разработка pass:[<br>] Мобильная разработка pass:[<br>] GameDev |====</p>
137
<p>|==== |Язык |Где используется |HTML |Web-страницы и приложения в браузере |JS |Web-разработка pass:[<br>] Мобильная разработка pass:[<br>] GameDev |====</p>
138
<p>В этом примере исчезло указание [cols=2], так как количество ячеек определяется количеством заголовков. Заголовки указываются после открытия таблицы в одну строку. Каждый заголовок начинается с символа |</p>
138
<p>В этом примере исчезло указание [cols=2], так как количество ячеек определяется количеством заголовков. Заголовки указываются после открытия таблицы в одну строку. Каждый заголовок начинается с символа |</p>
139
<p>Строка pass:[<br>] добавляет HTML-тег <br> для переноса внутри строки. Так же можно добавить теги <kbd></kbd>, которые размечают клавиши на клавиатуре:</p>
139
<p>Строка pass:[<br>] добавляет HTML-тег <br> для переноса внутри строки. Так же можно добавить теги <kbd></kbd>, которые размечают клавиши на клавиатуре:</p>
140
<p>Для открытия DevTools используйте комбинацию клавиш pass:[<kbd>Ctrl + Shift + I<kbd>]</p>
140
<p>Для открытия DevTools используйте комбинацию клавиш pass:[<kbd>Ctrl + Shift + I<kbd>]</p>
141
<h3>Математические формулы</h3>
141
<h3>Математические формулы</h3>
142
<p>Часто тексты на научные и технические темы включают математические обозначения. Такой функциональности нет ни в HTML, ни в AsciiDoc. Но в последнем есть обозначения математических формул, которые обрабатываются сторонними плагинами, например,<a>MathJax</a>.</p>
142
<p>Часто тексты на научные и технические темы включают математические обозначения. Такой функциональности нет ни в HTML, ни в AsciiDoc. Но в последнем есть обозначения математических формул, которые обрабатываются сторонними плагинами, например,<a>MathJax</a>.</p>
143
<p>По умолчанию, для вывода формул используется формат AsciiMath. Для этого выполняется два действия:</p>
143
<p>По умолчанию, для вывода формул используется формат AsciiMath. Для этого выполняется два действия:</p>
144
<ol><li>В документе<em>до</em>использования формул указывается строка :stem:. Это сигнал для обработки документа сторонними библиотеками. STEM - сокращение от Science, Technology, Engineering and Math</li>
144
<ol><li>В документе<em>до</em>использования формул указывается строка :stem:. Это сигнал для обработки документа сторонними библиотеками. STEM - сокращение от Science, Technology, Engineering and Math</li>
145
<li>Перед формулой указывается конструкцию stem:[Формула]</li>
145
<li>Перед формулой указывается конструкцию stem:[Формула]</li>
146
</ol><p>:stem: stem:[EEx: x!=a^2+b^2, x,a,b in Z] stem:[a]: Apple продает смартфоны - stem:[true] stem:[b]: Apple продает яблоки - stem:[false] stem:[a ^^ b]: Apple продает смартфоны и яблоки - stem:[false] Пусть stem:[X=5]</p>
146
</ol><p>:stem: stem:[EEx: x!=a^2+b^2, x,a,b in Z] stem:[a]: Apple продает смартфоны - stem:[true] stem:[b]: Apple продает яблоки - stem:[false] stem:[a ^^ b]: Apple продает смартфоны и яблоки - stem:[false] Пусть stem:[X=5]</p>
147
<p>Когда обозначаются математические формулы, используются знаки из нотации AsciiMath. Они преобразовываются в математические символы. Чтобы интерпретатор верно распознал формулы, нужно использовать специальные обозначения. Например, знак ≠ нужно обозначать в формуле как !=.</p>
147
<p>Когда обозначаются математические формулы, используются знаки из нотации AsciiMath. Они преобразовываются в математические символы. Чтобы интерпретатор верно распознал формулы, нужно использовать специальные обозначения. Например, знак ≠ нужно обозначать в формуле как !=.</p>
148
<p>Знаки, их вывод и запись можно изучить на<a>официальной странице AsciiMath</a>.</p>
148
<p>Знаки, их вывод и запись можно изучить на<a>официальной странице AsciiMath</a>.</p>
149
<h2>Заключение</h2>
149
<h2>Заключение</h2>
150
<p>Мы рассмотрели основные случаи разметки текста. Полную документацию по работе с AsciiDoc можно найти в полезных ссылках. Там вы познакомитесь со всеми макросами языка.</p>
150
<p>Мы рассмотрели основные случаи разметки текста. Полную документацию по работе с AsciiDoc можно найти в полезных ссылках. Там вы познакомитесь со всеми макросами языка.</p>
151
<p>AsciiDoc сделает материал понятным и логичным, так как с его помощью можно структурировать текст, выделить важные моменты, визуализировать примеры и оформить математические формулы. У AsciiDoc простой синтаксис и множество макросов с дополнительными функциями - именно поэтому это хорошая альтернатива HTML и Markdown.</p>
151
<p>AsciiDoc сделает материал понятным и логичным, так как с его помощью можно структурировать текст, выделить важные моменты, визуализировать примеры и оформить математические формулы. У AsciiDoc простой синтаксис и множество макросов с дополнительными функциями - именно поэтому это хорошая альтернатива HTML и Markdown.</p>
152
<h2>Полезные ссылки</h2>
152
<h2>Полезные ссылки</h2>
153
<ul><li><a>В чем разница между AsciiDoc и Markdown?</a></li>
153
<ul><li><a>В чем разница между AsciiDoc и Markdown?</a></li>
154
<li><a>Совместимость AsciiDoc и Markdown</a></li>
154
<li><a>Совместимость AsciiDoc и Markdown</a></li>
155
<li><a>Шпаргалка по синтаксису AsciiDoc</a></li>
155
<li><a>Шпаргалка по синтаксису AsciiDoc</a></li>
156
<li><a>Полная документация AsciiDoc</a></li>
156
<li><a>Полная документация AsciiDoc</a></li>
157
<li><a>AsciiMath</a></li>
157
<li><a>AsciiMath</a></li>
158
</ul>
158
</ul>