Обработка относительных путей к изображениям и ссылкам в Markdown для PDF

Файлы Markdown в репозиториях активно используют относительные пути. Схемы архитектуры хранятся в ./assets/diagram.png, снимки экранов — в ../images/screen.jpg, а ссылки ведут на ./getting-started.md. Если конвертер не учитывает структуру папок, изображения не загружаются, а ссылки перестают работать. В md2pdf относительные пути корректно рассчитываются и встраиваются в итоговый PDF.

В этой статье рассказывается, как md2pdf обрабатывает относительные пути, загружает графические ресурсы в браузере и трансформирует ссылки на файлы во внутренние якоря PDF.

Сложности работы с относительными путями в Markdown

Файлы Markdown ориентированы на локальную файловую систему или веб-интерфейс GitHub:

• Неработающие изображения: Относительный путь вроде ![Схема](images/arch.png) не может быть прочитан без контекста каталога.
• Сломанные ссылки: Ссылки на соседние файлы ([Установка](setup.md)) становятся неактивными при преобразовании в один PDF-документ.
• Переход по родительским каталогам: Пути, содержащие ../, требуют математического вычисления позиции относительно корня.

Relative Path Resolution Matrix:
Base Document:  docs/guides/installation.md
Image Path:     ../assets/diagram.png
Resolved Asset: docs/assets/diagram.png (Fetched & Inlined)

Link Path:      ./configuration.md
Resolved Link:  Internal PDF Anchor -> Chapter: Configuration

Получение изображений из репозиториев GitHub

При импорте документации из GitHub md2pdf отслеживает положение каждого файла в структуре каталогов:

1. Нормализация путей: Относительные адреса вроде ../../images/flow.png вычисляются относительно текущего файла.
2. Прямая загрузка: md2pdf формирует ссылку к CDN GitHub и загружает графический файл прямо в браузер.
3. Встраивание в память: Полученное изображение преобразуется в двоичный буфер и вшивается в страницы PDF через библиотеку pdf-lib.
4. Поддержка форматов: Поддерживаются распространенные форматы (PNG, JPEG, WebP, SVG) с автоматическим сохранением пропорций.

Превращение ссылок между файлами во внутренние переходы PDF

Технические руководства часто содержат взаимные перекрестные ссылки между главами:

• Обнаружение ссылок: md2pdf находит ссылки на файлы .md и сопоставляет их со списком глав книги.
• Внутренние переходы: Если целевой файл включен в собираемую PDF-книгу, ссылка превращается во внутренний переход к нужной странице.
• Внешняя ссылка: Если связанный файл не был выбран для книги, ссылка ведет на страницу этого файла на сайте GitHub.

Загрузка локальных файлов с комплектом изображений

При работе с файлами с локального диска md2pdf поддерживает параллельную загрузку документов и графики:

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

Формирование PDF с надежной графикой и рабочими ссылками

Корректная обработка путей избавляет от пустых мест вместо картинок и неработающих ссылок. Экспортируя документацию через md2pdf, вы получаете четкие иллюстрации и удобную внутреннюю навигацию по всей собранной книге.