Obsidian Markdown

Справка, представленная ниже не затрагивает правила разметки CommonMark и Git Flavored Markdown, а посвящена лишь специфике внутренней разметки заметок Obsidian.

Ключевые понятия

Выноска (Callout) — блок пояснительного текста, выделенный цветом и графическим элементом для отличия от основного текста.

Obsidian Markdown

Obsidian Markdown — это дополнение к широко распространённым диалектам CommonMark и Git Flavored Markdown. Этот диалект применяют для внутренней разметки текста заметок.

Отличительный синтаксис имеют следующие элементы Obsidian Markdown:

• метаданные заметки (frontmatter):
  • теги в метаданных заметки;
• внутренняя ссылка на другие заметки (wikilinks):
  • внутренняя ссылка на блок;
• вложение заметки (embed);
• выноска (callouts):
  • базовая выноска;
  • сворачиваемая выноска;
  • вложенная выноска;
  • выноска пользователя;
• комментарий;
• фоновое подчёркивание;
• внутристроковые и концевые сноски;
• проверочный список.

Метаданные

Метаданные по умолчанию:

• tags — теги по которым можно осуществлять поиск и которые видны на графе;
• aliases — альтернативные наименования (псевдонимы) заметки, которые часто используют в подсказках к ссылкам.
• cssclasses — класс CSS, который применим к заметке в режиме чтения и редактирования.

Теги метаданных

В значении тега допустимо использовать следующие символы:

• буквы любого языка;
• числа, кроме первого символа строки;
• символ подчёркивания (_);
• дефис (-);
• обратный слэш (/) для обозначения вложенных тегов.

Метаданные могут содержать список тегов:

---
tags:
  - тег1
  - вложенный/тег2
---

Пример всех типов встроенных метаданных, которыми оперирует Obsidian:

---
title: "Наименование заметки"
date: 2027-01-15
tags:
  - проект
  - important
aliases:
  - "Сокращение"
  - "Альтернативное наименование"
cssclasses:
  - custom-class
status: ожидает
rating: 4.5
completed: false
due: 2029-02-01T14:30:00
---

Внутренняя ссылка

В приложении Obsidian внутренние ссылки применяют для:

• выстраивания отношений между заметками;
• автоматизации изменения всей цепочки взаимных ссылок при переименовании заметки.

Синтаксис внутренних ссылок (wikilink):

• [[Наименование заметки]] — ссылка на другую заметку;
• [[Note Name|Display Text]] — ссылка на другую заметку с текстом пользователя;
• [[Note Name#Heading]] — ссылка на заголовок заметки;
• [[Note Name#Заголовок#Подзаголовок]] — ссылка на подзаголовок заметки (заголовок второго уровня, для последующих уровней — аналогично);
• [[Note Name#^block-id]] — ссылка на блок (якорь);
• [[#Heading in same note]] — ссылка на внутренний заголовок этой же заметки;
• [[## заголовок]] — поиск заголовка в файлах хранилища.

[!] Недопустимые символы Не включайте в строку специальные символы: # | ^ : %% [[ ]]. Это приводит к ошибкам обработки ссылок!

Внутренняя ссылка на блок

Под «блоком» в Obsidian понимают: абзац, список, цитату. Блоку присваивают идентификатор (block ID) в форме ^block-id. Например:

Абзац текста, в конце которого добавлен идентификатор (якорь). ^block-id

В списках и цитатах идентификатор разделяют пустой строкой. Например цитата:

> Абзац текста с цитатой и добавленным идентификатором (якорем).

^block-id

Пример идентификатора списка:

- Пункт 1
- Пункт 2
- Пункт 3

^block-id

Пример идентификатора в пункте списка:

- Пункт 1 с идентификатором ссылки.
	^block-id  
- Пункт 2
- Пункт 3

При создании ссылки для поиска блока по всем файлам хранилища используйте синтаксис:  [[^^первое слово блока]].

Вложение

Для вложений существует приставка (префикс) в виде восклицательного знака (!).

Различают синтаксис вложений для заметок, изображений, аудио, видео, документов в формате PDF.

Синтаксис вставки заметок:

• ![[Note Name]] — вставить весь текст другой заметки;
• ![[Note Name#Heading]] — вставить раздел другой заметки, текст между двумя заголовками;
• ![[Note Name#^block-id]] — вставить блок текста с указанным идентификатором (якорем) block-id из другой заметки.

Синтаксис вставки изображений из того же хранилища:

• ![[image.png]] — вставить изображение;
• ![[image.png|1280]] — вставить изображение указанной ширины в пикселях (px), высотав будет вычислена автоматически;
• ![[image.png|1280x960]] — вставить изображение указанной ширины и высоты в пикселях (px).

Синтаксис вставки изображений из внешних источников:

• ![Альтернативный текст](https://example.com/image.png) — вставить изображение из внешнего источника по указанному URL;
• ![Альтернативный текст|1280](https://example.com/image.png) — вставить изображение указанной ширины в пикселях (px), высота будет вычислена автоматически;
• ![Альтернативный текст|1280x960](https://example.com/image.png) — вставить изображение указанной ширины и высоты в пикселях (px).

Синтаксис вставки базы данных:

• ![[BaseFile.base]] — вставка файла в формате .base, расположенного в этом же хранилище;
• ![[BaseFile.base#View Наименование]] — вставка представления базы данных с наименованием «Наименование»

Синтаксис вставки результата поиска:

tag:#project status:done

Синтаксис вставки документа в формате PDF:

• ![[document.pdf]] — вставить документ полностью (все страницы);
• ![[document.pdf#page=3]] — вставить указанную страницу документа;
• ![[document.pdf#height=400]] — вставить страницу указанной высоты;
• ![[document.pdf#page=3#height=400]] — вставить указанную страницу документа указанной высоты.

Выноска

Выноска (Callout) — блок пояснительного текста, выделенный цветом и графическим элементом для отличия от основного текста.

Типы выносок

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

• общая (базовая) выноска (Basic Callout);
• сворачиваемая выноска (Foldable Callout);
• вложенная выноска (Nested Callout);
• пользовательская выноска (Custom Callout).

Поскольку у выносок существует множество альтернативных названий (псевдонимов), приводим сводную таблицу основных и дополнительных наименований.

Уникальные для Obsidian Markdown типы выносок:

Выноски Obsidian, совместимые с другими диалектами Markdown:

Базовая выноска

Общая (базовая) выноска (Basic Callout) — выноска общего применения в основном тексте.

Выноска для примечания, комментария к основному тексту:

> [!NOTE] Примечание (заголовок выноски)
> Текст выноски под заголовком.

Выноска для дополнительных сведений к основному тексту:

> [!INFO] Дополнительные сведения (заголовок выноски)
> Текст выноски под заголовком.

Выноска, состоящая только из заголовка:

> [!TIP] Совет (текст выноски).

Сворачиваемая выноска

Сворачиваемая выноска (Foldable Callouts) — выноска, содержание которой можно свернуть и развернуть.

Сворачиваемая выноска закрытая по умолчанию:

> [!FAQ]- Ответы на вопросы (видимый заголовок выноски)
> Скрытый текст выноски, который можно развернуть.

Сворачиваемая выноска открытая по умолчанию:

> [!FAQ]+ Ответы на вопросы (видимый заголовок выноски)
> Открытый текст выноски, который можно при желании свернуть.

Вложенная выноска

Вложенная выноска (Nested Callouts) — выноска, которая содержит в себе другие выноски.

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

• Всегда добавлять пробел после символа >. Например:
  • текст внешней выноски — >;
  • текст вложенной выноски — > >.
• При необходимости добавлять символы сворачиваемой выноски (+ или -). Например, для закрытой вложенной выноски: [!note]-.
• Для того, чтобы поместить несколько вложенных выносок внутри внешней выноски, следует :
  • выровнять уровень отступа для каждого вложенного блока;
  • вставить пустые строки, которые содержат только > >, для отделения одного блока от другого.

> [!QUESTION] Внешняя выноска
> Текст внешней выноски. 
> 
> > [!NOTE] Первая внутренняя выноска
> > Содержание внутренней выноски. 
> 
> > [!INFO] Вторая внутренняя выноска
> > Внутренняя выноска, содержащая вложенную выноску.
> > 
> > > [!TIP] Внутренняя выноска с ценным советом.

Выноска пользователя

Выноска пользователя (Custom Callouts) — выноска, внешний вид (стиль оформления) которой определён пользователем с помощью фрагментов кода CSS.

Для того, чтобы создать собственный тип выноски, необходимо создать CSS-фрагмент (CSS snippet):

1. Открыть «Настройки (Settings) → Внешний вид (Appearance)».
2. Перейти в раздел CSS-фрагменты (CSS snippets).
3. Нажать на кнопку справа с изображением папки.
4. В открытой папке создать текстовый файл и назвать его, например, custom-callouts.css. Проверьте, что расширение файла именно .css, а не .txt.
5. В любом текстовом редакторе откройте созданный файл custom-callouts.css и опишите стилевой класс. Например:

/* Обязательный элмент определения класса  */
.callout[data-callout="custom-type"] {
	/* Цвет в формате RGB. Красит пиктограмму, левую вертикальную полосу и заголовок. */
  --callout-color: 255, 0, 0;
	/* Пиктограмма из библиотеки Lucide */
  --callout-icon: lucide-alert-circle; 

	/* Дополнительные элементы оформления */ 
	border-left: 5px solid rgb(var(--callout-color)); 
	border-radius: 6px; 
	background-color: rgba(var(--callout-color), 0.08); }
}

/* Задать цвет заголовка выноски */
 .callout[data-callout="custom-type"] .callout-title {
	 font-weight: 700; 
	 letter-spacing: 0.5px; 
 }

Включить фрагмент стиля в Obsidian: 6. Открыть «Настройки (Settings) → Внешний вид (Appearance)». 7. Нажать кнопку «Обновить» (Refresh). 8. Включить тумблер фрагмента custom-callouts.

После всего этого в заметках можно использовать созданную выноску как и все остальные. Например:

> [!custom-type] Заголовок выноски пользователя
> Текст выноски пользователя.

Комментарий

Синтаксис строкового и блокового комментария:

Строковый комментарий, в котором %%часть текста скрыта%%, часть текста видимая.

%%
Блоковый комментарий для скрытия блока (списка, цитаты, абзаца).
%%

Фоновое подчёркивание

Синтаксис фонового подчёркивания (Highlight) строки текста: = =Highlighted text= =.

Сноска

В разметке различают:

• внутристроковые сноски;
• концевые сноски.

Синтаксис внутристроковой сноски:

• ^[текст сноски]

Синтаксис концевой сноски:

• Отметка сноски в строке текста: [^1].
• [^1]: Содержание сноски внизу страницы.

Проверочный список

В проверочном списке различают:

• невыполненные пункты;
• выполненные пункты.

Правила оформления невыполненного пункта проверочного списка:

• первый символ дефис (-);
• пробел;
• квадратные скобки с пробелом внутри ([ ]).

Правила оформления выполненного пункта проверочного списка:

• первый символ дефис (-);
• пробел;
• квадратные скобки с любым символом (кроме пробела) внутри ([x]).

Синтаксис проверочного списка:

- [ ] Пример невыполенного пункта списка.
- [☑] Пример выполненного пункта списка.

Дополнительные сведения

Документация. Obsidian Flavored Markdown.