Как объединить несколько Markdown-файлов в один HTML-документ

Зачем объединять набор Markdown-файлов

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

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

Подготовьте Markdown-файлы и папки

Используйте предсказуемую иерархию и выберите одну начальную страницу. Отделите материалы для читателей от шаблонов задач, правил участия и внутренних планов, если они не должны входить в руководство.

docs/
  README.md
  installation.md
  quick-start.md
  guides/
    configuration.md
    deployment.md
  images/
    settings.png

Предпочитайте относительные ссылки вида guides/configuration.md и images/settings.png. Точно соблюдайте регистр имен файлов, давайте заголовкам понятные названия, указывайте язык в блоках кода и избегайте HTML, зависящего от внешних скриптов или стилей.

Импортируйте и организуйте содержимое

Создайте документ в One File Docs через сценарий импорта Markdown. Проверьте полученные разделы и расположите их в нужном читателю порядке. Сортировка папок и файлов удобна для авторов, но не должна диктовать непонятную структуру навигации.

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

Проверьте ссылки, якоря, код и изображения

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

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

Экспортируйте HTML, сохранив Markdown источником

Экспортируйте документ после подготовки дерева, навигации и содержимого. One File Docs упакует страницы, просмотрщик, поиск, стили, скрипты и импортированные изображения в один HTML-файл. Проверьте его отдельно от исходной папки и без интернета, если важна офлайн-работа.

Продолжайте редактировать Markdown, а не сгенерированный HTML. После изменения источника повторите импорт, изучите диагностику и ссылки и создайте новый экспорт. Авторы сохранят удобный процесс с Git, а читатели будут получать один предсказуемый файл документации.