Для заметки Markdown, которую вы редактируете в Obsidian на Mac и читаете на GitHub, используйте стандартные ссылки Markdown и уникальные названия заголовков в нижнем регистре. Однословные заголовки, например setup, дают обоим рендерерам одну и ту же цель; к заголовкам с пробелами нужно отнестись внимательнее.

Это руководство посвящено навигации внутри заметки и между двумя файлами Markdown. Практическая цель — поддерживать один удобный для чтения документ, не предполагая, что каждый рендерер Markdown одинаково интерпретирует адреса заголовков.

Почему корректная ссылка Markdown может вести мимо заголовка?

Для ссылки на заголовок нужны два условия: парсер Markdown должен распознать ссылку, а рендерер — определить её адрес. Кликабельная ссылка подтверждает выполнение первого условия. Переход к нужному разделу — второго.

CommonMark определяет синтаксис заголовков и ссылок с фрагментами, включая [link](#fragment). Примеры заголовков в спецификации не устанавливают универсальный алгоритм создания идентификаторов заголовков. Именно поэтому корректный синтаксис Markdown сам по себе не гарантирует одинаковую навигацию по разделам в разных приложениях. См. спецификацию заголовков CommonMark и спецификацию ссылок.

GitHub создает якоря заголовков, переводя буквы в нижний регистр, заменяя пробелы дефисами, удаляя прочую пунктуацию и форматирование, а повторяющимся якорям присваивая числовые суффиксы. В документации Obsidian говорится, что ссылки на заголовки используют текст заголовка после #. Это разные соглашения об адресах. См. правила ссылок на разделы GitHub и документацию Obsidian по внутренним ссылкам.

Obsidian поддерживает CommonMark и GitHub Flavored Markdown наряду с собственными расширениями. Эта поддержка не делает все специфичные для приложений ссылки взаимозаменяемыми: Obsidian прямо предупреждает, что некоторые расширения в других приложениях могут отображаться как обычный текст. Эта граница описана в документации Obsidian о совместимости с Markdown.

Какое соглашение о заголовках обеспечивает одинаковую цель в обоих рендерерах?

Для новой общей заметки выбирайте уникальные заголовки из строчных букв ASCII, по возможности состоящие из одного слова. Для более длинных названий подойдет форма вроде desk-layout: видимый текст заголовка уже совпадает с фрагментом в стиле GitHub.

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

Заголовок в файле Адрес по тексту заголовка в Obsidian, с URL-кодированием Адрес, созданный GitHub
## setup #setup #setup
## desk-layout #desk-layout #desk-layout
## Desk Layout #Desk%20Layout #desk-layout

В таблице учтены рекомендации Obsidian по тексту заголовков и URL-кодированию и правила якорей GitHub. Здесь намеренно не предполагается, что Obsidian принимает все фрагменты, нормализованные GitHub.

У такого подхода есть заметный компромисс: desk-layout больше похоже на идентификатор, чем на обычное название раздела. Если важны естественные заголовки, оставьте их и проверьте получившиеся ссылки в обоих приложениях. Не переименовывайте весь документ, пока не решите, какой компромисс подходит его читателям.

Пример готовой заметки

Создайте заметку с именем desk-notes.md и вставьте в нее следующий текст Markdown. Это полный пример документа с вымышленным содержанием; блок кода нужен только для демонстрации исходного текста.

Desk notes

Jump to [setup](#setup), [materials](#materials), or
[desk layout](#desk-layout).

## setup

Place the notebook beside the keyboard.

## materials

Use a notebook, a pencil, and a desk tray.

## desk-layout

Keep the tray beside the notebook.

Return to [setup](#setup).

Обратите внимание: текст ссылки может содержать обычные пробелы: [desk layout](#desk-layout) отображается как удобочитаемый текст, а адрес остается прежним. Не нужно оформлять каждую навигационную подпись как идентификатор заголовка.

В реальной заметке добавьте в разделы достаточно текста, чтобы переход был заметен. В очень коротком документе удачный переход может почти не сдвинуть содержимое, потому что вся заметка и так помещается в окне.

Как настроить и проверить Obsidian на Mac?

Сначала проверьте саму заметку, затем настройте способ, которым Obsidian будет создавать новые ссылки. Это отдельные проверки: изменение параметра генерации ссылок не заменяет проверку уже существующей разметки Markdown.

  1. Откройте в боковой панели Settings.
  2. В разделе Files and links отключите Use Wikilinks, чтобы создаваемые ссылки использовали синтаксис Markdown.
  3. Для ссылок между общими файлами задайте для New link format значение Relative path to file.
  4. Прежде чем полагаться на новые настройки, проверьте существующие адреса.

В справке Obsidian описаны способ открыть настройки в настольной версии и оба параметра генерации ссылок в разделе Settings. Здесь удобно использовать относительные пути, поскольку они явно задают структуру общей папки.

Переключите пример заметки в Reading view сочетанием Command+E, затем нажмите каждую навигационную ссылку. В документации Obsidian указано, что это сочетание предназначено для macOS, а в режиме чтения синтаксис Markdown скрыт. Для повторяемых проверок используйте один и тот же режим, не смешивая приемы редактирования с тестированием навигации. См. режимы просмотра и редактирования.

Затем проверьте отображение файла на GitHub. Наведите указатель на заголовок и нажмите значок ссылки, чтобы посмотреть фактический фрагмент. Сравните его с текстом после # в исходной ссылке. GitHub описывает этот способ проверки в разделе Ссылки на разделы.

Используйте короткий список критериев приемки: ссылка отображается как ссылка, открывает нужный файл и ведет к нужному заголовку. Записывайте ошибки по адресам и не меняйте сразу несколько заголовков. Так проще понять, что именно исправили: имя файла, путь или фрагмент.

Как создать ссылку на заголовок в другом файле?

Начните с простого примера: разместите два файла в одной папке. Создайте index.md в той же папке, что и desk-notes.md, и добавьте в него следующий текст целиком:

Desk index

Read the [setup notes](desk-notes.md#setup).

Review the [desk layout](desk-notes.md#desk-layout).

У адреса две части: desk-notes.md выбирает файл, а #setup — раздел. GitHub разрешает относительные ссылки на файлы относительно текущего файла; в Obsidian есть настройка создания ссылок с относительными путями. Эти документированные возможности подходят для такого размещения файлов в одной папке. См. относительные ссылки GitHub и настройки ссылок Obsidian.

Сохраняйте такое же относительное расположение файлов, где бы вы ни читали эти документы. Если переместить только index.md в подпапку, существующий адрес соседнего файла больше не будет соответствовать исходной структуре. Пересчитайте путь, прежде чем проверять заголовок.

В общих ссылках на файлы указывайте расширение .md. Если в имени файла есть пробелы, используйте в адресах Markdown форму %20 согласно рекомендациям Obsidian по URL-кодированию. Кодирование пробела сохраняет пробел; оно не превращает заголовок в якорь GitHub с дефисами.

Что делать с существующими заголовками и неработающими ссылками?

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

  1. Проверьте исходный текст заголовка. Убедитесь, что цель — настоящий заголовок Markdown, например ## setup, с пробелом после начальных символов решетки. CommonMark требует этот пробел для заголовка с текстом. См. ATX-заголовки.
  2. Проверьте синтаксис ссылки. Используйте [setup](#setup). Закрывающая квадратная скобка должна непосредственно примыкать к открывающей круглой скобке; [setup] (#setup) не считается встроенной ссылкой по правилам ссылок CommonMark.
  3. Разделите проверку файла и раздела. Если не работает ссылка на другой файл, временно проверьте ссылку на файл без фрагмента. Если она не работает, сначала исправьте путь.
  4. Сравните текст заголовка с фрагментом. Для естественного заголовка вроде Desk Layout вернитесь к сравнению рендереров выше. Замена %20 на - меняет соглашение о целевом адресе.
  5. Проверьте наличие одинаковых целей. Предпочтительнее уникальные названия, например notebook-setup и tray-setup. Числовые суффиксы GitHub зависят от порядка повторяющихся якорей, поэтому перестановка может изменить адреса. См. ссылки на разделы GitHub.

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

После переименования заголовка заново проверьте входящие ссылки на раздел. В описании настройки Obsidian Automatically update internal links говорится об обновлении ссылок при переименовании файла; этого описания недостаточно, чтобы утверждать, что при любом изменении заголовка автоматически исправятся все ведущие на него ссылки. См. описание настройки Obsidian.

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

Источники