Чтобы полностью отобразить длинную строку кода Markdown, сохраните код без изменений и настройте его отображение. Это руководство поможет пользователям Mac выяснить, почему примеры обрезаются, включить перенос строк в режиме чтения Obsidian и понять, что будет работать на GitHub.

От чего зависит перенос строки кода?

Блок кода, заключенный в ограждающие строки, сохраняет код как буквальный текст. CommonMark определяет открывающие и закрывающие ограждающие строки и правила разбора содержимого, но не предоставляет переносимого параметра для переноса длинных строк. Текущая спецификация соответствует версии 0.31.2. Спецификация CommonMark, блоки кода с ограждающими строками.

GitHub Flavored Markdown следует тем же основным правилам для блоков кода с ограждающими строками. Его спецификация также не требует указывать инструкцию переноса в информационной строке ограждения. Поэтому добавление wrap после названия языка не обеспечивает переносимого поведения переноса строк. В опубликованной спецификации GFM указана версия 0.29-gfm; ее номер версии не следует путать с текущей версией CommonMark. Спецификация GitHub Flavored Markdown.

В этой задаче различайте три результата:

Результат Что видит читатель Нужно ли менять исходный текст примера?
Визуальный перенос Одна исходная строка занимает несколько строк на экране Нет
Горизонтальная прокрутка Строка выходит за видимую область, но остается доступной Нет
Ручные переносы строк В примере появляются дополнительные исходные строки Да

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

Различие между исходным текстом и его представлением явно описано в CSS: обработка пробелов меняет отображение, не меняя данные исходного документа. Поэтому визуальный перенос — хорошая отправная точка, если пример должен оставаться копируемым как одна строка. Модуль CSS Text Level 3.

Сначала проверьте, отсутствует ли часть примера или просто находится за пределами видимой области

Прежде чем редактировать длинную команду или выражение, проверьте исходный текст. В Obsidian выберите Режим исходного кода с помощью переключателя режима редактирования. Чтобы сравнить его с отображаемым результатом на Mac, нажмите Cmd+E для переключения между режимом редактирования и Режимом чтения. Obsidian отличает эти режимы от Предварительного просмотра, который является режимом редактирования. Режимы просмотра и редактирования.

Используйте этот искусственный тест в отдельной заметке. Скопируйте внутреннюю часть Markdown, включая открывающую и закрывающую строки с тремя обратными кавычками. Текст намеренно является обычным текстом, а не командой для выполнения.

```text
BEGIN sample=amber notebook=desktop layout=wide description=This synthetic example contains a deliberately long line so you can check whether the final marker remains visible when the note pane becomes narrow END
```

Сузьте панель заметки и найдите END. Если он появляется на следующей строке, перенос работает. Если его можно увидеть, прокрутив блок по горизонтали, значит, содержимое доступно через прокрутку. Если оно по-прежнему недоступно, сравните отображаемый блок с исходным текстом, прежде чем делать вывод, что текст был удален.

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

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

Сначала расширьте область заметки Obsidian, прежде чем добавлять CSS

Откройте Настройки → Редактор и найдите Читаемая длина строки. Согласно документации Obsidian, эта настройка ограничивает максимальную длину строки. Временно отключите ее и сравните ту же тестовую заметку при том же размере окна. Эта настройка меняет ширину; в документации она не описана как переключатель переноса строк в блоках кода. Настройки.

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

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

Переносите длинные строки кода в режиме чтения Obsidian

Для отдельных заметок используйте документированный механизм фрагментов CSS в Obsidian и свойство cssclasses. Следующий фрагмент — это собственная настройка на основе указанного механизма и стандартного поведения CSS. Он предназначен для обычных отображаемых блоков кода с ограждающими строками в Режиме чтения; это не предоставляемый Obsidian готовый параметр переноса и не настройка режима редактора. Фрагменты CSS.

Создайте и включите фрагмент

  1. Откройте Настройки → Оформление → Фрагменты CSS.
  2. Выберите Открыть папку фрагментов.
  3. В текстовом редакторе создайте в этой папке файл wrap-code.css и сохраните в нем CSS-код ниже.
  4. Вернитесь в раздел Фрагменты CSS, выберите Перезагрузить фрагменты и включите wrap-code.

Это документированные шаги установки Obsidian для настольных компьютеров. После включения изменения сохраненного фрагмента обычно применяются автоматически. Фрагменты CSS.

.wrap-code pre,
.wrap-code pre code {
  white-space: pre-wrap;
  overflow-wrap: anywhere;
  word-break: normal;
}

Добавьте этот блок свойств в начало тестовой заметки. Если в ней уже есть свойства, добавьте wrap-code к существующим значениям cssclasses, а не вставляйте второй блок свойств.

---
cssclasses:
  - wrap-code
---

Obsidian документирует cssclasses как способ применять пользовательский CSS к выбранным заметкам. Здесь .wrap-code ограничивает правило этими заметками; остальные селекторы нацелены на отображаемые моноширинные блоки и их содержимое. Это правило не настраивает область редактирования. Фрагменты CSS.

Разберитесь, что меняет CSS

Объявление white-space: pre-wrap сохраняет пробелы и исходные переносы строк, разрешая при этом визуальный перенос. Объявление overflow-wrap: anywhere также позволяет переносить слишком длинную строку без точек разрыва, когда это необходимо, не вставляя дефис. Вместе они позволяют переносить как длинные строки с пробелами, так и длинные непрерывные последовательности символов. Модуль CSS Text Level 3, Свойство CSS overflow-wrap.

Не заменяйте их на white-space: normal: это значение объединяет пробелы и может изменить визуальные отступы, которые важно сохранить. Кроме того, одного overflow-wrap недостаточно, если правило обработки пробелов запрещает перенос. Свойство CSS white-space, Модуль CSS Text Level 3.

Вернитесь в Режим чтения, сузьте панель и снова проверьте END. Затем скопируйте содержимое теста в текстовый редактор и сравните с исходником. В результате одна исходная строка должна отображаться в нескольких строках на экране. Эта проверка копированием позволяет убедиться, что установленная у вас программа отображает текст так, как задумано, с учетом используемой темы.

Учитывайте различия между системами отображения

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

Среда На что ориентироваться Что проверить отдельно
Реализация CommonMark Документированные правила разбора блоков с ограждающими строками Перенос, прокрутку и доступную ширину для отображения
Markdown, отображаемый на GitHub Документированные правила GitHub для ограждающих строк и идентификаторов языка Отображение блока кода в конкретной целевой среде
Режим чтения Obsidian Отображаемая заметка и включенный локальный стиль Работает ли фрагмент с текущей темой
Предварительный просмотр или Режим исходного кода Obsidian Выбранный режим редактирования Отображение в редакторе; приведенный выше фрагмент его не настраивает

Границы синтаксиса определяются спецификацией CommonMark, документацией GitHub по блокам кода и документацией Obsidian по режимам просмотра.

В документации GitHub указано, что идентификатор языка после открывающей ограждающей строки включает подсветку синтаксиса. Поэтому изменение text на другой идентификатор языка не является документированным способом включить перенос. Оставьте правильный идентификатор для примера и настройте отображение в системе, которая отвечает за него. Создание и подсветка блоков кода.

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

Устраните неполадки, не удаляя необходимое содержимое сокращением

Если кажется, что правило Obsidian не действует, выполните следующие действия:

  1. Убедитесь, что проверяете в Режиме чтения.
  2. Убедитесь, что wrap-code.css отображается в разделе Фрагменты CSS и включен.
  3. Убедитесь, что в cssclasses заметки указано именно wrap-code.
  4. Выключите и снова включите фрагмент, просматривая неизмененную тестовую заметку.
  5. При необходимости временно отключите другие фрагменты и сравните результат с темой Obsidian по умолчанию, чтобы выявить конфликт стилей.
  6. Повторите проверку на реальном примере, прежде чем считать задачу завершенной.

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

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

Источники