Документация

Справочник по разметке

Всё, чем размечается текст страницы: блоки, начертания, наша нотация. Тело страницы хранится в markdown, поэтому почти всё набирается и с клавиатуры, и через /-меню.

Три способа получить один и тот же блок: пункт в слэш-меню (/ в пустой строке), markdown-сокращение прямо при наборе и селект типа блока в панели форматирования. Выбирайте любой.

Абзацы и переносы

Блок текста — абзац. Enter заканчивает абзац и начинает новый, Shift+Enter переносит строку внутри того же абзаца. Пустая строка отдельным блоком не нужна: отступы между абзацами рисует сама вёрстка.

Заголовки

Шесть уровней. Набирается решётками с пробелом:

# Заголовок 1 уровня
## Заголовок 2 уровня
### Заголовок 3 уровня
#### Заголовок 4 уровня
##### Заголовок 5 уровня
###### Заголовок 6 уровня

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

Оглавление сбоку собирается из заголовков, у каждого — якорь. Есть и сворачиваемые заголовки (/сворачиваемый) — раздел, который читатель раскрывает по клику.

Списки

Что Как набрать
Маркированный - или * в начале строки
Нумерованный 1. в начале строки
Список задач (с флажками) [] в начале строки
Сворачиваемый список пункт /сворачиваемый список

Tab и Shift+Tab внутри списка задают вложенность. Нумерация считается сама — за номерами следить не нужно.

Начертания

Начертание Набор Клавиши
Жирный **текст** Ctrl/Cmd + B
Курсив *текст* Ctrl/Cmd + I
Подчёркнутый — Ctrl/Cmd + U
Зачёркнутый ~~текст~~ Ctrl/Cmd + Shift + S
Код одинарные обратные кавычки Ctrl/Cmd + E

Цвет

В панели форматирования — палитра из двух половин: цвет текста и фон. Оттенков десять: авто, серый, коричневый, красный, оранжевый, жёлтый, зелёный, голубой, фиолетовый, розовый. Тот же набор доступен целому блоку из меню ручки слева.

Цвет переживает и тёмную тему, и экспорт. Но в markdown цвета нет, и хранится он нашим расширением — выгруженный .md цвета не сохранит. Смысл цветом не передавайте: то, что важно, должно читаться и в чёрно-белой распечатке.

Цитата, разделитель, разрыв страницы

  • Цитата — > в начале строки. Для чужих слов и замечания в сторону; для того, что читатель обязан заметить, есть плашка — она ниже.
  • Разделитель — --- в пустой строке. Горизонтальная черта между кусками текста.
  • Разрыв страницы — пункт /разрыв; виден только в экспорте в PDF и DOCX.

Плашки

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

Вид Про что Как вставить
Заметка нейтральное «стоит знать» /заметка, /инфо
Совет приём, который экономит время /совет, /идея
Важно без этого дальше не получится /важно
Предупреждение здесь легко ошибиться /предупреждение, /варнинг
Осторожно необратимое действие или потеря данных /опасно, /денжер

У плашки два поля. Заголовок — строка сверху, набирается прямо в ней; Enter переводит курсор в тело. Тело — обычный текст страницы: работают начертания, ссылки, вики-ссылки, #теги и чипы задач. Заголовок можно не писать — тогда плашка подпишется названием вида.

Команда, вызванная в строке с текстом, превращает в плашку эту строку: дописали абзац, поняли, что это предупреждение, — /предупреждение, и абзац станет её телом.

Как хранится

Цитатой, начатой маркером вида, — это алерт GitHub:

> [!WARNING]
> **Стёртое из корзины не вернуть**
> Чистка корзины — операция окончательная.

Маркеров пять: [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], [!CAUTION]. Своей нотации у плашки нет намеренно — ту же запись рисуют врезкой GitHub, GitLab и Obsidian. Поэтому выгруженный .md остаётся читаемым, а страница, написанная агентом или приехавшая импортом, станет плашкой при первом же открытии.

Где ещё видна

Где Что видно
Гость по ссылке, версия из истории, сайт документации плашка целиком, на чтение
Экспорт в HTML и печать плашка со своими цветами
Экспорт в PDF и DOCX врезка с заливкой и полосой сбоку; значка нет, поэтому вид называет заголовок
Экспорт в Markdown тот же алерт
Экспорт в TXT цитата, первой строкой — заголовок
Описание задачи обычная цитата: у описания задачи набор блоков стандартный

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

Код

Тройные обратные кавычки открывают блок кода; язык дописывается там же:

```python
def hello(name: str) -> str:
    return f"Привет, {name}"
```

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

Выбранный язык включает подсветку синтаксиса. В списке 46 языков и «Простой текст»: C, C++, C#, Java, Kotlin, Swift, Objective C, JavaScript, TypeScript, JSX, TSX, Python, Ruby, PHP, Rust, Scala, Haskell, Julia, Lua, R, SQL, Shell, HTML, CSS, SCSS, Sass, Less, PostCSS, XML, JSON, YAML, Markdown, MDX, LaTeX, GraphQL, Vue, Svelte, Pug, RegExp, WebAssembly и ещё несколько. Список закрытый: своего языка в него не вписать, но и потерять ничего нельзя — фенс с незнакомым языком переживает сохранение и выгрузку как есть, просто останется неподсвеченным.

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

Где Что видно
Страница, шаблон, гость по ссылке, версия из истории подсветка; у гостя селект показывает язык, но не переключается
Экспорт в HTML и печать цветов нет, но класс language-… в разметке остаётся — принимающая сторона подсветит сама
Экспорт в PDF и DOCX одноцветный моноширинный текст
Экспорт в Markdown и TXT текст, в markdown — вместе с языком в фенсе
Ответ ассистента в чате своя разметка, подсветки в ней нет

Внутри блока кода наша разметка не работает и не должна — решётка не станет тегом, … не станет ссылкой, ![…](…) не станет картинкой. Поэтому примеры разметки пишут именно так.

Диаграммы

Схема рисуется прямо в странице — слэш-меню, группа «Диаграммы», пять пунктов:

Пункт Про что
Диаграмма классов классы, поля и связи между ними
Диаграмма последовательности кто кого вызывает и в каком порядке
Диаграмма состояний состояния и переходы между ними
Схема данных (ER) сущности и связи между таблицами
Блок-схема шаги процесса и развилки

Вход в группу целиком — /uml или /диаграмма; конкретный вид достаётся своим словом: /классы, /последовательность, /состояния, /erd, /блок-схема.

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

Как правится

Блок показывает картинку, сверху — полоса с названием вида, переключателем «Схема | Код» и кнопкой копирования исходника. Полоса проявляется по наведению и по фокусу с клавиатуры, на тач-экране стоит всегда: схему чаще читают, чем правят, и в чтении ряд кнопок — шум.

Клик по схеме открывает её на весь экран — крупную схему так читать удобнее. Оттуда же её можно скопировать картинкой или скачать файлом PNG — например, для презентации.

В режиме «Код» под полем стоит сама диаграмма и пересчитывается через 400 мс после того, как вы перестали печатать: правите строку — видите результат. Не разобралось — вместо картинки строка с сообщением разборщика. Оно английское и называет номер строки (Parse error on line 4), этого хватает, чтобы найти опечатку. Escape возвращает из поля в текст страницы.

Отдельного поля «вид диаграммы» нет: вид задаёт первое слово исходника — classDiagram, sequenceDiagram, stateDiagram-v2, erDiagram, flowchart. Поменяли первое слово — поменялись и схема, и подпись в полосе.

Язык схем

Диаграммы пишутся на Mermaid — том же языке, который рисуют GitHub, GitLab и Obsidian. Пятью видами из меню он не ограничен: gantt, pie, journey, gitGraph и прочее нарисуются, если написать их руками, — их просто нет в меню.

Подписи пишите по-русски, идентификаторы — латиницей. Имя узла в mermaid это часть грамматики, и кириллица в нём местами не разбирается; подпись же — свободный текст, и с ней всё в порядке:

flowchart TD
    A[Запрос] --> B{Есть в кеше?}
    B -- да --> C[Отдать ответ]
    B -- нет --> D[Посчитать и положить в кеш]
    D --> C

Как хранится

Обычным блоком кода с языком mermaid — своей разметки у диаграммы нет. Поэтому выгруженный .md остаётся не просто читаемым, а рабочим: тот же фенс нарисуется схемой в GitLab, GitHub и Obsidian. Верно и обратное — импортированный файл или страница, написанная агентом, станут диаграммой при первом же открытии.

Хранится только исходник. Картинка — производная от него, и ни в базу, ни в файл она не попадает.

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

Где ещё видна

Где Что видно
Гость по ссылке, версия из истории, сайт документации картинка; исходник открывается переключателем, но правке не поддаётся
Экспорт в HTML и печать картинка внутри файла, снаружи ничего не подгружается
Экспорт в PDF и DOCX картинка
Экспорт в Markdown и TXT исходник текстом
Поиск и ассистент исходник как текст: по подписям на схеме страница находится, по картинке — нет
Описание задачи обычный блок кода

В любом выгруженном файле схема светлая, даже если вы работаете в тёмной теме: лист белый.

Таблицы

Пункт /таблица вставляет заготовку; строки и столбцы добавляются кнопками по краям, а меню у ручки строки или столбца делает её строкой (столбцом) заголовков. Таблицы переживают сохранение и выгрузку в markdown без потерь.

Таблица — для перечня однородных фактов. Абзац, разбитый на ячейки, читается хуже исходного абзаца.

Картинки и файлы

Пункт /картинка, перетаскивание файла в текст или Ctrl+V скриншота из буфера. Подпись под картинкой заполняется тут же. Подробности, форматы и ограничения — Картинки и вложения.

Ссылки

  • Обычная ссылка — Ctrl/Cmd + K на выделенном тексте или разметкой [подпись](адрес). Вставленный в текст голый адрес превращается в ссылку сам.
  • Ссылка на страницу базы знаний — двойные квадратные скобки; начните печатать название, и появится список:
[Быстрый старт](/5b632731-bd61-4004-a8e4-aba3a4e9113e)
[как это делается](/5b632731-bd61-4004-a8e4-aba3a4e9113e)
  • Тег — решётка со словом прямо в тексте: #релиз. Отдельный блок тегов есть и под названием страницы.
  • Задача — /task Что надо сделать или кнопка «Задача» на выделенном тексте; в тексте остаётся чип с живым состоянием.
  • Внешний документ — /gdoc, /gslides, /miro со ссылкой: в текст ляжет карточка, а сам документ уйдёт в индекс.
  • Секрет — ссылка на запись в менеджере паролей, /секрет или просто вставленный адрес знакомого хранилища: в тексте встанет ключ, а пароль останется в хранилище. Хранится ссылкой со знаком ключа — [🔑 прод-база](https://…). См. Хранение паролей.

Ссылки и теги — не украшение: из них собирается Граф связей, а по тегам фильтруют базу знаний. Подробно — Ссылки и теги.

Практики оформления

Название — это заголовок. Не дублируйте его первой строкой тела.

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

Заголовки по существу. «Что это», «Как включить», «Если не работает» находятся глазами и оглавлением; «Часть 2» не находится ничем.

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

Списком — перечисления, абзацем — рассуждение. Разбитый на пункты довод теряет связки «поэтому» и «зато», ради которых его и писали.

Схему — диаграммой, а не скриншотом. Картинка, нарисованная в чужом редакторе, устаревает молча, не ищется по подписям и правится только там, где её сделали. Диаграмма правится на месте и уезжает в выгрузку исходником.

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

Ссылайтесь вместо пересказа. Скопированный кусок чужой страницы устареет молча, ссылка — нет.

Пароль — ссылкой на менеджер паролей, а не текстом. Пароль в тексте уезжает в поиск, историю и выгрузки; ключ — нет.

Пишите даты полностью — «11.08.2026», а не «вчера»: документ читают через полгода.

Договорённости — задачей, а не абзацем. «Надо переписать раздел про оплату» в тексте забывается; та же фраза, выделенная и превращённая в задачу, остаётся видимой обеим сторонам.