Ссылки и вложения, которые переживут перенос
Соберите переносимую папку Markdown: локальные вложения, относительные ссылки и проверка после копирования.
Вы отправили коллегам инструкцию с двумя скриншотами. У вас всё видно, у коллег ссылки открывают пустую страницу. Часто ссылка ведёт в папку загрузок автора. На другом компьютере нужного файла по этому адресу нет. Этот материал поможет собрать небольшую документацию, которую можно перенести целиком и проверить без доступа к исходному устройству.
Выберите границу переносимого комплекта
Допустим, у вас инструкция по подготовке мастерской к встрече. Храните её в отдельной папке workshop-guide. Внутри положите start.md, страницу notes/room.md и схему помещения media/room-layout.png. Такой набор легко переслать архивом. Перед упаковкой откройте папку и посмотрите, какие документы действительно нужны читателю. Если инструкция отсылает к старому отчёту из другой папки, либо включите подходящую копию, либо замените отсылку коротким объяснением.
Важно учитывать две разные точки отсчёта. В обычной файловой организации путь media/room-layout.png от start.md ведёт вниз в папку media. Из страницы notes/room.md до той же схемы сначала нужно подняться на один уровень. На сайте адрес обрабатывается относительно адреса страницы или правилами сборки. Поэтому правильный локальный путь сам по себе ещё не гарантирует работающую ссылку после публикации.
Запишите пути от документа
Положите следующую ссылку в start.md. Используйте косую черту даже при работе в Windows. Для переносимого набора проще сразу давать новым файлам короткие имена строчными латинскими буквами. Так легче обнаружить расхождение регистра, которое не замечает ваш файловый менеджер.
[Подготовить помещение](notes/room.md)
Во второй заметке вернитесь к началу комплекта и покажите ту же схему. Если автору нужно переставить заметку на уровень глубже, придётся изменить относительные ссылки в ней. Хранение общего изображения в одном месте помогает избегать лишних копий, но требует проверять входящие ссылки при переименовании.
[К началу инструкции](../start.md)
Ссылка на обычное вложение использует квадратные скобки и адрес в круглых. Для встроенного изображения перед квадратными скобками ставят восклицательный знак. В подписи к ссылке назовите документ, который откроется. Альтернативный текст изображения передаёт необходимую информацию человеку, который не видит картинку. Для сложного плана добавьте рядом текстовые ориентиры, например «столы стоят вдоль длинной стены, проход к входу свободен». Сам текст поможет исполнить инструкцию даже без изображения.
Разберите исключения до отправки
Абсолютный путь вроде C:/Users/anna/Downloads/room-layout.png привязан к компьютеру. Адрес, начинающийся с косой черты, на сайте обычно отсчитывается от корня домена. Это может быть удобно для собственного сайта, но ссылка рискует сломаться, если комплект опубликовать в подпапке. Внешний HTTPS-адрес полезен, когда требуется именно внешний документ. Проверьте доступ к нему с учётной записью читателя, поскольку открытие ссылки в вашем браузере может зависеть от ранее выполненного входа.
Если путь с пробелом уже существует и имя менять нежелательно, попробуйте закодировать пробел как %20 и проверить результат в целевой среде. Не вставляйте в путь необработанный символ решётки, если он является частью имени файла. В адресе решётка отделяет фрагмент страницы. Для первого комплекта легче переименовать такой файл в безопасное короткое имя и обновить ссылки, чем выяснять, что именно перекодировал редактор.
Иногда Markdown-приложение само создаёт ссылки формата [[Схема]]. Такое поведение удобно внутри этого приложения. Если материал передаётся человеку с другим редактором, используйте переносимые относительные ссылки и проверьте, что адрес не зависит от открытого хранилища заметок. Не заменяйте ссылки массово только по имени файла. plan.png может существовать в двух разных папках.
Проверьте копию в условиях читателя
Создайте архив только из выбранной папки и распакуйте его в другой каталог. Откройте начальный документ из распакованного набора, а исходный проект временно закройте в редакторе. Перейдите от первой страницы к вложенной заметке. Затем откройте из неё схему и вернитесь назад. Если редактор всегда обращается к исходному хранилищу, повторите проверку в другом приложении или на другом устройстве. При публикации проверьте собранный сайт отдельно. Сборщик может преобразовать ссылки или ожидать, что изображения лежат в папке публичных ресурсов.
Завершите проверку без сети, если обещали автономный комплект. Локальные изображения должны появиться без обращения к интернету. Для внешних ссылок оставьте пояснение, что они требуют подключения, и не опирайтесь на них в действиях, обязательных для первого запуска. Удалите из комплекта документы, в которых есть закрытые данные, и убедитесь, что их не упоминают оставшиеся ссылки. Готовый пакет открывается в нужной среде, содержит только необходимые файлы и не требует угадывать, что автор имел в виду под названием вложения.
Сравните структуру папок и путь загрузки
Для двух вариантов отправки используйте один и тот же контрольный шаг. Откройте ссылку из вложенной страницы, а затем посмотрите, откуда загрузился файл. При работе с сайтом это видно в инструментах браузера. При работе с архивом достаточно открыть документ из отдельной папки без исходного проекта. Проверка помогает поймать ситуацию, когда прежняя копия картинки ещё доступна и скрывает ошибку в новом пути.