Язык разметки Markdown и способы его применения

инструментарий
markdown
Дата публикации

8 августа 2022 г.

Трудно выбрать инструмент для оформления презентации или лабораторной работы из-за их огромного разнообразия. Для этих целей чаще всего используют офисные пакеты, такие как Microsoft Office или Libre Office. В текстовых процессорах есть набор готовых стилей и возможность создать собственные, но это отвлекает от самого содержания документа. Нужно одновременно думать над контентом и его оформлением. К тому же контент в формате документов doc или pdf слишком статичен.

Около года назад я познакомился с языком разметки Markdown (или сокращённо MD) и теперь использую его для оформления учебных материалов, в том числе содержащих интерактивные и динамические элементы.

Почему стоит использовать?

Markdown-документ - это обычный текстовый файл, открыть который можно любым простым текстовым редактором. Как и любой другой язык разметки, MD отвечает за семантику, то есть элементы разметки отвечает за назначение элемента - будет ли он заголовком, параграфом, элементом списка и так далее. За стилистическое оформление будет отвечать инструмент экспорта. Автору стоит заботиться только о содержании а не оформлении.

Инструмент экспорта определяет доступные выходные форматы. Ещё один плюс Markdown-документа - это возможность экспортировать один и тот же файл в разные форматы исходя из текущих задач.

Markdown-разметка лаконична. MD-текст можно прочитать и без экспорта в другие форматы. Некоторые языки разметки не могут похвастаться таким качеством. Например HTML-разметка использует теги - парные и одиночные. Заметную часть текста будут содержать сами теги. В Markdown это не так. Например в HTML, разметка простой страницы с заголовками, параграфами, списком и другими элементами выглядит так:

<h1>Заголовок 1 уровня</h1>
<h2>Заголовок 2 уровня</h2>
<h3>Заголовок 3 уровня</h3>

<p>Это первый параграф с <i>курсивом</i> и <b>жирным начертанием</b></p>
<p>А это второй параграф</p>
<p>
    Список:
    <ul>
        <li>Первый элемент</li>
        <li>Второй элемент</li>
        <li>Третий элемент</li>
    </ul>
</p>

А вот тот же пример, но с Markdown-разметкой:

#  Заголовок 1 уровня
## Заголовок 2 уровня
### Заголовок 3 уровня

Это первый параграф с *курсивом* и **жирным начертанием**

А это второй параграф

Список:
- Первый элемент
- Второй элемент
- Третий элемент

Кроме заголовков, параграфов и списков есть элементы разметки для ссылок, изображений, таблиц, цитат, блоков кода. Также в MD-документе допустимы и HTML-теги. Чтобы встроить интерактивный элемент или видео подойдёт тег iframe или embed. Подробнее со стандартными элементами разметки можно ознакомиться в этом руководстве.

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

Инструменты экспорта

Инструкции к лабораторным

Документы с Markdown-разметкой я использовал для составления инструкций к лабораторным работам и практическим занятиям. По началу, я экспортировал каждый документ в HTML-формат по отдельности, пока не нашёл утилиту mkdocs. Это модуль для языка программирования Python с помощью которого набор MD-документов оформляется в формате сайта с автоматически созданным меню и оглавлением для каждой страницы.

Если при этом установить модуль material-mkdocs, то можно не только поменять тему оформления сайта, но и применить разные расширения Markdown-разметки, например для простой вставки клавиатурных комбинаций2, математических формул, записанных в LaTeX формате3 или врезок с советами, подсказками или рекомендациями с разным оформлением4, которые можно сделать раскрывающими по щелчку.

Значительный плюс в размещении заданий в формате веб-страницы - её интерактивность5. Кроме обычных изображений в инструкции размещаются gif-файлы с анимацией и встроенные элементы. При необходимости, в инструкцию добавляются ссылки на внешние ресурсы.

Несмотря на то, что сайт статичен, material-mkdocs позволяет включить функцию поиска по сайту.

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

Блог

Записи в этом блоге тоже изначально создаются как Markdown-документы а затем экспортируются в виде сайта с выбранной темой оформления. Для экспорта используется генератор статичных сайтов Hugo. Ко всем этим инструментам нужно привыкнуть и настроить под свои нужды. Но как только настройка завершена, всё внимание можно уделять только содержанию.

На этом сайте располагается мини-курс по использованию Hugo.

Презентации

MD-документ можно экспортировать в презентацию с помощью утилиты Pandoc. В этом посте есть инструкции. Я пробовал создавать презентации таким способом, но пока не смог перейти к их использованию, так как оформить сложную презентацию с анимацией сложнее, чем в PowerPoint или Google Презентациях. Но, думаю, для простых презентаций такой процесс будет оправдан.

Какой редактор использовать?

Я использую редактор Typora. Его большой плюс - это мгновенный предпросмотр разметки. То есть редактор работает в WYSIWYG-режиме6. После вставки в документа изображения, редактор сам копирует его в папку с ресурсами, которая создаётся рядом с редактируемым файлом.

Ещё один хороший редактор - MarkText. Он во многом похож на Typora.

Описание языка разметки Markdown получились очень кратким, а инструментов работы с ним - ещё короче. Но главное, что их применение выводит на передний план содержимое, и не его оформление.

Сноски

  1. Примеры аннотаций можно найти на этой странице.↩︎

  2. Страница с клавиатурными комбинациями для TinkerCad.↩︎

  3. Пример можно найти в этой инструкции.↩︎

  4. На этой странице есть множество примеров таких врезок.↩︎

  5. В этом занятии встречаются как встроенные из TinkerCad модели, так и анимации, которые описывают использование инструментов моделирования.↩︎

  6. WYSIWYG (What You See Is What You Get) - Что видишь, то и получаешь.↩︎