Sign in

Markdown

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

CommonMark и GFM

Всё из CommonMark и GitHub-Flavored Markdown, за одним исключением: заголовок хранится в названии узла и выводится оттуда, поэтому строку-заголовок в тексте блока не принимают.

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

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

Расширения Wikilayer

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

Короткие ссылки

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

Короткие ссылки на страницы

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

Короткие ссылки на блоки

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

Выноски

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

Текстовые выноски

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

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

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

Выноски с картой

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

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

Встраивание изображений

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

  • 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/…).

Рядом с текстом, с подписью

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

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

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

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

Без внешних хостингов

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

Без объектного хранилища обходного пути нет

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