Предпросмотр Markdown

Какой Markdown и зачем очищать HTML

Markdown — это семейство, а не одна спецификация, и здесь используется общепринятый набор GitHub-flavoured Markdown: заголовки, выделение, списки, ссылки, изображения, цитаты, таблицы, блоки кода с подсветкой синтаксиса, списки задач, зачёркивание, сноски и автоматические ссылки. Именно так пишут почти все, и именно это будет в README. Более экзотические диалекты и специальные плагины отдельных сайтов — блоки-предупреждения, шорткоды, шаблоны — не поддерживаются, поэтому в документе, написанном для конкретного генератора, часть синтаксиса может отобразиться как есть.

HTML отображается, но сначала очищается, и в этом стоит разобраться. Markdown намеренно допускает HTML внутри себя, а значит, Markdown-файл откуда угодно может содержать тег script, встроенный обработчик событий, iframe или ссылку javascript:. Если отобразить это как есть, в вашем сеансе выполнится чужой код — просто потому, что вы вставили чужой README, чтобы его посмотреть. Всё исполняемое удаляется до показа, так что оформление сохраняется, а код — нет.

Это общий урок, а не особенность этой страницы. Любая система, которая отображает Markdown от пользователей, — поле комментария, вики, тикет в поддержку — отображает пользовательский HTML, если не очищает его, и именно так эту проблему и упускают из виду: «это же просто Markdown». Преобразование Markdown не является границей безопасности; ею является очистка.

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

Если нужно другое

README, который вы сейчас пишете, смотрите там, где он будет жить. Собственный редактор GitHub показывает предпросмотр с точным отображением, расширениями и якорями, а GitHub CLI — gh markdown-preview — делает то же локально на том же движке. Для документации у самого генератора (MkDocs, Docusaurus, Hugo) есть предпросмотр с живой перезагрузкой, где видны настоящие стили и навигация — то, что увидит читатель.

Для редактирования, а не проверки, удобнее редактор Markdown с панелью живого предпросмотра — Obsidian, Typora, VS Code со встроенным предпросмотром: он обновляется по мере ввода, а файл остаётся на месте, и не нужно каждый раз вставлять текст на страницу. Эта страница — для чтения чужого Markdown или быстрого взгляда на то, что вам прислали.