Как пользоваться Markdown-редактором
- Введите или вставьте Markdown в редактор слева.
- Следите, как предпросмотр в реальном времени обновляется по мере набора; разметка обрабатывается по правилам GitHub-flavoured Markdown (GFM).
- Нажмите Копировать HTML, чтобы скопировать сгенерированный HTML для сайта, CMS или письма.
- Или скопируйте сам Markdown для README, issue, pull request или страницы документации.
Рендеринг выполняется в вашем браузере, ваш текст не загружается и не сохраняется. Отрисованный HTML очищается, поэтому скрипты и опасные атрибуты во вставленном содержимом удаляются до показа предпросмотра.
Что такое Markdown?
Markdown — облегчённый язык разметки, созданный Джоном Грубером в 2004 году. Для форматирования он использует знаки препинания в обычном тексте: # для заголовков, * или _ для выделения, - для списков. Исходник остаётся читаемым как простой текст, а рендерер превращает его в HTML.
Первоначальное описание оставляло многие крайние случаи неопределёнными, поэтому реализации расходились. CommonMark — подробная спецификация, устраняющая эти неоднозначности, а GitHub-flavoured Markdown — надмножество CommonMark, добавляющее возможности, которыми разработчики пользуются каждый день:
| Возможность GFM | Синтаксис |
|---|---|
| Таблицы | | Name | Value | со строкой-разделителем |---|---| |
| Списки задач | - [ ] todo и - [x] done |
| Зачёркивание | ~~removed~~ |
| Автоссылки | Простые URL, например https://example.com, становятся ссылками |
| Блоки кода с ограничителями (fenced) | Три обратные кавычки, за которыми по желанию следует название языка |
Краткий справочник по Markdown
# Heading 1
## Heading 2
**bold**, *italic*, `inline code`
- Bullet item
- Nested item (indent two spaces)
1. Numbered item
[Link text](https://example.com)
> A blockquote
```python
print("fenced code with a language")
```Частые проблемы с Markdown и как их решить
Заголовок не отображается. CommonMark требует пробел после решёток. #Title — обычный текст; # Title — заголовок.
Строки слиплись в один абзац. Одиночный перенос строки внутри абзаца воспринимается как пробел. Оставьте пустую строку, чтобы начать новый абзац, или закончите строку двумя пробелами либо обратной косой чертой для жёсткого переноса. (Комментарии на GitHub обрабатывают одиночные переносы строк иначе, чем файлы README, и это частая причина путаницы.)
Список или блок кода обрывается раньше времени. Содержимое, принадлежащее элементу списка, нужно сдвинуть так, чтобы оно выровнялось по тексту элемента. Для кода внутри списка сдвигайте весь блок с ограничителями:
1. Install the package:
```bash
npm install example
```
2. Run it.Таблица не отображается. Таблице GFM нужны строка заголовка, строка-разделитель как минимум с тремя дефисами на столбец и, как правило, пустая строка перед ней. Используйте двоеточия в разделителе (:---, :---:, ---:) для выравнивания столбцов.
Нежелательное форматирование. Символы вроде *, _ и # могут включать форматирование. Экранируйте их обратной косой чертой, например \*not italic\*, или заключайте в обратные кавычки.
Советы и лучшие практики
- Всегда добавляйте язык после открывающих обратных кавычек, чтобы блоки кода получали подсветку синтаксиса там, где она поддерживается.
- Пишите осмысленный альтернативный текст для изображений: его используют программы чтения с экрана, и он показывается, если изображение не загрузилось.
- В длинных документах пишите по одному предложению на строку: Markdown склеит их в абзацы, а сравнение версий (diff) станет намного чище.
- Сначала вставьте примеры JSON или YAML в инструмент Форматирование и валидация JSON или Форматирование и валидация YAML, чтобы блоки кода в вашей документации были корректными и аккуратными.
- Если вы вставляете сгенерированный HTML на веб-страницу, пропустите его через инструмент Форматирование HTML, чтобы аккуратно расставить отступы.
Часто задаваемые вопросы
В чём разница между Markdown и GitHub-flavoured Markdown?
GFM — надмножество CommonMark, определённое GitHub. Оно добавляет таблицы, списки задач, зачёркивание, расширенные автоссылки и некоторые ограничения на «сырой» HTML. Большинство README, написанных для GitHub, отображаются здесь так же.
Можно ли использовать HTML внутри Markdown?
Да, Markdown допускает встроенный HTML. В целях безопасности предпросмотр очищает вывод, поэтому теги вроде <script>, атрибуты обработчиков событий, такие как onclick, и ссылки javascript: удаляются.
Почему мой Markdown выглядит иначе на другом сайте?
Платформы используют разные диалекты Markdown и собственные таблицы стилей. Базовый синтаксис (заголовки, выделение, списки, ссылки, код) одинаков, но таблицы, переносы строк и расширения вроде сносок или формул отличаются в разных рендерерах.
Как преобразовать Markdown в HTML?
Напишите или вставьте Markdown, проверьте предпросмотр и нажмите Копировать HTML. На выходе получается простой семантический HTML (заголовки, абзацы, списки, таблицы) без оформления, поэтому он подхватит CSS той страницы, в которую вы его вставите.
Обновлено