Как сохранить Markdown как автономную HTML-страницу
Преобразуйте локальную заметку в HTML, упакуйте нужные ресурсы и проверьте результат без сети.
Вы написали краткую инструкцию для выездного занятия. Получатели читают её в браузере, а интернет в аудитории бывает недоступен. Markdown удобно оставить редактируемым исходником и собрать из него отдельный HTML-файл для чтения. В зависимости от выбранных настроек файл может обращаться к соседним картинкам или содержать их внутри. Решение нужно проверить до передачи, иначе документ откроется, но ключевая схема не загрузится.
Подготовьте небольшую папку исходников
Создайте учебную папку с файлом guide.md и вложением media/checklist.png. Используйте изображение без личных данных, которое можно передать получателям. В документе добавьте заголовок, короткий порядок действий, ссылку на внешний источник и изображение. Когда главная инструкция должна работать без сети, внешний адрес оставьте только для дополнительного чтения. Дайте текстовое описание ключевого изображения, чтобы человек мог выполнить задачу и без него.
Установленный Pandoc можно проверить командой pandoc --version. Справка утилиты содержит параметры преобразования и поддерживаемые форматы. Если в старой версии параметр из примера отсутствует, сначала прочитайте справку именно установленной версии. Копировать команды, которые обещают скачать преобразователь и тут же запустить его, для этого примера не требуется.
Соберите обычную страницу
Откройте терминал в папке с исходником. Явно укажите входной формат. Редакторы могут расширять Markdown. Явное название формата помогает при следующей сборке использовать те же правила разбора. В учебном примере базовых заголовков, ссылок и списков достаточно.
pandoc --from=commonmark --to=html5 --standalone --metadata title="Подготовка занятия" guide.md -o guide.htmlПараметр --standalone просит создать полный HTML-документ, а не только фрагмент содержимого. Имя выходного файла отличается от имени исходника расширением. До запуска убедитесь, что в этой папке нет важной страницы guide.html. Новый результат может заменить предыдущий. Для первого эксперимента можно выбрать отдельное имя, например guide-preview.html. Откройте результат браузером и проверьте, что заголовок показан и у страницы понятное имя во вкладке.
При обычной сборке изображение может оставаться внешним для HTML. Это удобно, когда несколько страниц используют один ресурс и передаются вместе с папкой media. Тогда перемещение одного файла HTML нарушит связь. Браузер может успешно читать картинку с прежнего места, пока исходная папка доступна. Само открытие страницы не подтверждает автономность файла.
Выберите способ передачи
Для маленькой страницы с одной схемой удобно встроить ресурсы. Pandoc умеет создавать самостоятельный HTML с встраиваемыми стилями и изображениями. Встраивание увеличивает размер страницы. Для большого набора фотографий или медиа удобнее архив с понятной структурой, поскольку каждый ресурс остаётся отдельным файлом. Перед отправкой учитывайте ограничение канала передачи и реальные возможности устройства получателя.
pandoc --from=commonmark --to=html5 --standalone --embed-resources --metadata title="Подготовка занятия" guide.md -o guide-offline.htmlИспользуйте только нужные ресурсы. Сборка с внешними источниками может попытаться обратиться к ним, а ссылка на внешний сайт не превращается в копию этого сайта. Для автономного урока заранее сохраните разрешённые изображения локально. При включении сторонней картинки проверьте условия использования. Оригинальный Markdown ссылается на неё, но HTML с встраиванием уже несёт копию изображения.
Если читателям нужна папка с несколькими страницами, не склеивайте их только ради автономности. Оставьте стартовую страницу и относительные ссылки. Укажите, какой файл открывать первым. Передавайте архив так, чтобы получатель распаковал его целиком. Открытие HTML прямо из интерфейса архива может дать другое поведение, поскольку программа иногда извлекает только выбранный файл.
Проверьте, что получилось
Скопируйте только guide-offline.html в другую папку и откройте его там без сети. Изображение должно появиться, а текст остаться читаемым. Для архива вместо этого распакуйте его в новый каталог и проверьте каждый обязательный переход. Откройте страницу на телефоне или уменьшите ширину окна. Проверьте таблицы, длинные строки и код, если они есть. Конвертация сохраняет структуру в пределах поддерживаемого формата, а не точную вёрстку исходного приложения.
Если картинка пропала, проверьте адрес в Markdown и путь запуска. Относительный путь мог разрешиться иначе, чем в предпросмотре редактора. Если ожидаемое расширение разметки показалось как обычный текст, проверьте, указан ли подходящий входной формат. Правьте исходный Markdown, иначе изменения в HTML исчезнут при следующей сборке. Уточните исходник, повторите преобразование и заново проверьте копию. Обязательные материалы должны читаться без сети. Следующую редакцию должно быть возможно собрать из той же папки одной понятной командой.
Проверьте кодировку и путь к ресурсу
Для полезной проверки добавьте слово с буквой «ё» в подпись схемы и короткую ссылку на раздел той же страницы. Откройте результат в браузере и проверьте, что буквы не заменились нечитаемыми знаками, а переход приводит к нужному заголовку. Если сборка не может найти локальную картинку, запустите её из той папки, которую описывает руководство. Для более сложной структуры посмотрите в справке Pandoc параметры поиска ресурсов. Перед передачей проверьте список файлов или размер итогового HTML. Случайно встроенная большая фотография может сделать маленькую инструкцию неудобной для отправки, даже если она правильно открывается.