Как поддерживать повторяющиеся ссылки в Markdown
Соберите адреса в одном месте и проверьте, что ссылка с понятной подписью ведёт к нужному источнику.
В руководстве по работе со школьным архивом на один и тот же справочник ссылаются в трёх разделах. Когда справочник переезжает, автор исправляет первый адрес, но пропускает два других. Для таких документов полезны ссылочные определения Markdown. Смысл перехода по-прежнему виден рядом с текстом, а менять адрес можно в одном месте. Этот способ уместен, если документ действительно содержит повторяющиеся ссылки или длинные адреса мешают читать исходник.
Перепишите один переход и сравните результат
Обычная ссылка хранит адрес непосредственно за подписью. Ссылочная форма указывает на определение по метке. В учебном примере обе ссылки ведут на одну спецификацию. Текст ссылок отличается, потому что в первом абзаце читатель ищет описание формата, а во втором сверяет правило. Метка для обеих ссылок одна.
Откройте [описание формата Markdown][commonmark].
Сверьте [правила разметки в спецификации][commonmark].
[commonmark]: https://spec.commonmark.org/0.31.2/Положите определение отдельно от абзаца. В начале строки идут квадратные скобки с меткой, затем двоеточие и адрес. В итоговой странице определение не должно показываться отдельным абзацем. Откройте предпросмотр и нажмите обе ссылки. Если на месте подписи остались квадратные скобки, сначала проверьте совпадение меток и положение определения относительно других блоков.
Необязательно давать метке такое же имя, как подписи. Можно написать короткий идентификатор вроде catalog-policy, который помогает найти адрес в исходнике. Для однократной ссылки на простую страницу прямая форма часто читается быстрее. Переводите в ссылочную форму только те адреса, которые обновляются вместе или повторяются в одном документе.
Выберите место для определений
В небольшом руководстве удобно держать определения внизу. В длинной статье можно разместить их возле раздела с источниками. Не вставляйте определения в середину непрерывного абзаца и не размещайте их внутри блока кода, если рассчитываете на рабочую ссылку. Внутри блока кода определение остаётся частью показанного примера, а браузер не превращает его в адрес.
У определения нет видимой подписи на готовой странице. Поэтому для читателя, которому нужен отдельный список источников, оставьте обычный раздел. В нём можно сослаться на тот же адрес через метку. Запись «Источник» сама по себе мало помогает. Укажите название документа и объясните, какую часть руководства он подтверждает. Тогда читатель сможет найти документ даже после смены адреса.
Если собираетесь копировать фрагменты между файлами, учитывайте границу документа. Определения обычно разрешаются в пределах одного Markdown-документа. Скопированный абзац с [подпись][commonmark] может лишиться адреса. При переносе захватите соответствующее определение или превратите ссылку обратно в прямую. Особенно легко потерять определение, когда в новом файле уже используется такая же короткая метка для другого источника.
Проверьте конфликт меток
CommonMark сопоставляет метки с учётом нормализации пробелов и регистра. Два определения, которые выглядят немного по-разному, могут указывать на одну и ту же метку. Если определений с одной меткой несколько, используется первое. Это не похоже на обычную ошибку сборки. Страница может выглядеть правильно, но вести на старый адрес.
Чтобы заметить проблему, поищите в исходнике открывающую скобку с меткой и двоеточием. Проверьте, что определение одно. В большой редакционной работе можно договориться о коротких уникальных именах по предмету и версии, например format-commonmark-0312. Не добавляйте суффикс только ради красоты. Он нужен, если рядом действительно есть другой выпуск источника, который нельзя заменить новым автоматически.
Отдельно проверьте вложенные кавычки, пробелы в адресах и символы скобок. Если конкретный адрес сложно читать как Markdown, скопируйте его из адресной строки и протестируйте в целевой среде. Для локальных путей лучше придерживаться понятных имён и передавать вместе с документом нужные файлы. Ссылочное определение упрощает обслуживание, но не делает отсутствующее вложение доступным.
Выполните пробное обновление
Выберите документ с двумя повторяющимися переходами. Сохраните копию. Перепишите переходы через одно определение и проверьте опубликованный предпросмотр. Затем на копии замените адрес в определении на другую доступную страницу. Обе ссылки должны сменить назначение, а подписи остаться прежними. Верните исходный адрес и проверьте, что каждая подпись всё ещё точно описывает место назначения.
Теперь попробуйте вынести один абзац в отдельный файл. Проверьте, что без определения читатель не получит молча потерянный переход, а после переноса определения ссылка снова работает. Для готовой инструкции важны три результата. Одинаковый адрес исправляется в одном месте. Названия ссылок описывают разные задачи читателя. В целевом редакторе ни одна рабочая ссылка не остаётся в виде сырой разметки.
Не смешивайте повтор ссылки и повтор доказательства
Иногда два абзаца опираются на один документ, но на разные его разделы. Сохранить общий адрес полезно для знакомства с документом. Для проверки конкретной детали лучше дать отдельную метку с точным фрагментом. Например, введение стандарта и правило о списках решают разные задачи читателя. Если один раздел позже переедет, правка его ссылки не должна перенаправить вторую ссылку на новое место. Прочитайте готовые предложения, не глядя на адреса. Читатель должен по подписи понять, открывает ли он весь документ или нужное правило. Такое разделение важнее уменьшения числа определений в исходнике.