<!-- page:68371 -->
# Markdown

Markdown — широко поддерживаемый текстовый формат, который легко читается в любом редакторе и одинаково отображается в разных инструментах. Wikilayer хранит текст каждого узла в Markdown, разбирает его с помощью goldmark + GFM и добавляет несколько собственных расширений для перекрёстных ссылок и встроенных выносок.

<!-- block:68407 -->
## CommonMark и GFM

Всё из [CommonMark](https://commonmark.org/) и [GitHub-Flavored Markdown](https://github.github.com/gfm/), за одним исключением: [заголовок хранится в названии узла](block:68394) и выводится оттуда, поэтому строку-заголовок в тексте блока не принимают.

Поэтому в текстах бывают:

- Полужирный (`**text**`), курсив (`*text*`), зачёркнутый (`~~text~~`).
- Встроенный код (`` `text` ``) и блоки кода в тройных обратных кавычках с необязательной меткой языка.
- Маркированные списки (`-`, `*`, `+`), нумерованные списки (`1.`), вложенные списки отступом.
- Цитаты (`> `).
- Таблицы (синтаксис GFM с вертикальными чертами).
- Списки задач (`- [x]`, `- [ ]`).
- Горизонтальные линии (`---`).
- Ссылки (`[text](url)`) и изображения (`![alt](url)`).

<!-- block:68408 -->
## Расширения Wikilayer

При отображении Wikilayer преобразует несколько видов записи.

<!-- block:68456 -->
### Короткие ссылки

Короткая ссылка — это ссылка, записанная через id узла, которую Wikilayer преобразует в собственный адрес вики. Она переживает смену заголовка или slug, потому что id не меняется.

<!-- block:68494 -->
#### Короткие ссылки на страницы

`[text](page:N)` разрешается в канонический адрес целевой страницы: `/{owner}/{wiki}/{id}-{slug}`, а для страницы не на основном языке — `/{owner}/{wiki}/{lang}/{id}-{slug}`. При переименовании slug может смениться, id постоянен.

<!-- block:68495 -->
#### Короткие ссылки на блоки

`[text](block:N)` разрешается в якорь `#block-N`: на странице самого блока это ссылка внутри страницы, с любой другой страницы — адрес страницы блока с этим якорем.

<!-- block:68457 -->
### Выноски

Оформленные вставки, записанные цитатами `> [!KIND]` в синтаксисе выносок GitHub.

<!-- block:68496 -->
#### Текстовые выноски

Выноски в стиле GitHub отображаются оформленными блоками. Первая строка цитаты называет вид:

```
> [!NOTE]
> Текст абзаца.
```

Поддерживаемые виды: `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`. У каждого свой цвет и значок.

<!-- block:68497 -->
#### Выноски с картой

Выноска `[!MAP]` с `lat, lng` на следующей строке встраивает интерактивную карту. Третья строка, если она есть, становится подписью.

```
> [!MAP]
> 44.7866, 20.4489
> Белград, центр города.
```

<!-- block:68458 -->
### Встраивание изображений

Изображение сохраняется на сервере и вставляется по его пути `/s/`. Для загрузки есть два инструмента [MCP](page:68372):

- `upload_image` принимает публичный адрес `http` или `https` либо файл, прикреплённый к разговору. Сервер сам скачивает изображение, поэтому его байты не нужно передавать через контекст агента. Это подходит агенту в браузерном чате, у которого нет доступа к командной оболочке.
- `request_upload` выдаёт одноразовый адрес, на который агент с командной оболочкой отправляет локальный файл: `curl --data-binary @<file> -H 'Content-Type: <mime>' '<upload_url>'`.

В обоих случаях изображение преобразуется в JPEG с длинной стороной не больше 1600 px и сохраняется в вики. `upload_image` возвращает его путь; при `request_upload` путь возвращает POST-запрос. Путь вставляется прямо в текст, ровно в полученном виде: `![альтернативный текст](/s/images/…)`.

<!-- block:75215 -->
#### Рядом с текстом, с подписью

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

```
![Масляная лампа и каменная чаша возле открытой двери](/s/images/… "Дом в сумерках")
```

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

На экране шириной с телефон изображение занимает всю ширину; мобильные приложения показывают все изображения на всю ширину.

<!-- block:68498 -->
#### Без внешних хостингов

Изображение встраивается только из хранилища самой вики, по пути `/s/`. Запись с изображением с GitHub, Imgur или другого хостинга, с адресом `data:` или с полным адресом не принимается, а ранее вставленное внешнее изображение показывается ссылкой. Внешние изображения пропадают, упираются в ограничения частоты запросов и сообщают своему хостингу, кто читал страницу.

<!-- block:68499 -->
#### Без объектного хранилища обходного пути нет

Если ни `upload_image`, ни `request_upload` нет в списке инструментов, на этом сервере не настроено объектное хранилище и встраивание изображений недоступно; внешний хостинг его не заменяет.

---

## Links here

- [MCP](page:68372)
- [История](page:68373)

---

[All pages](https://wikilayer.org/smee-again/wikilayer-howto/ru/index.md)