Markdown Preview

Что такое Markdown?

Markdown — это легковесный язык разметки, созданный Джоном Грубером в 2004 году. Он использует символы форматирования в виде обычного текста — звёздочки, решётки и тире — для обозначения структуры: заголовков, жирного начертания, курсива, списков, ссылок и блоков кода. Инструмент предпросмотра Markdown преобразует этот текст в отформатированный HTML, позволяя увидеть, как итоговый документ будет выглядеть перед публикацией. Исходная спецификация Markdown описана в документации Daring Fireball Джона Грубера, а сам формат впоследствии был стандартизован в виде CommonMark.

Markdown стал форматом по умолчанию для документации разработчиков, файлов README, генераторов статических сайтов (Jekyll, Hugo, Astro), вики и баз знаний. GitHub, GitLab, Bitbucket, Stack Overflow, Reddit и Notion поддерживают Markdown нативно. Поскольку исходник представляет собой обычный текст, Markdown-файлы легко версионировать с помощью Git, сравнивать между ветками и сливать без конфликтов в непересекающихся секциях файла.

Инструмент предпросмотра Markdown разбирает входные данные и преобразует их в HTML в реальном времени. Это позволяет обнаружить ошибки форматирования, битые ссылки и неожиданную вложенность до того, как файл будет сохранён или страница опубликована. Данный инструмент работает полностью в браузере без обращения к серверу, поэтому можно работать с конфиденциальной документацией, не передавая содержимое по сети.

Зачем использовать онлайн-инструмент предпросмотра Markdown?

Написание Markdown в обычном редакторе без предпросмотра означает, что результат приходится угадывать. Живой предпросмотр мгновенно закрывает этот пробел обратной связи.

Сценарии использования Markdown Preview

Справочник по синтаксису Markdown

В таблице ниже показано соответствие распространённого синтаксиса Markdown его отрисованному результату и соответствующему HTML-элементу. Это охватывает базовый CommonMark, который поддерживает практически каждый парсер Markdown.

Сравнение вариантов Markdown

Разные платформы расширяют оригинальную спецификацию Markdown дополнительными возможностями. Знание того, на какой вариант вы ориентируетесь, помогает избежать синтаксиса, который молча не работает в другом рендерере.

Примеры кода: программная отрисовка Markdown

Когда требуется отрисовать Markdown внутри приложения, а не в браузерном инструменте, используйте одну из этих библиотек. Каждый пример преобразует строку Markdown в строку HTML.

import { marked } from 'marked'

const md = '# Hello\n\nThis is **Markdown**.'
const html = marked(md)
// → "<h1>Hello</h1>\n<p>This is <strong>Markdown</strong>.</p>\n"

// With options
marked.setOptions({ gfm: true, breaks: true })
const gfmHtml = marked('Line one\nLine two')
// → "<p>Line one<br>Line two</p>\n"

import markdown

md = '# Hello\n\nThis is **Markdown**.'
html = markdown.markdown(md)
# → '<h1>Hello</h1>\n<p>This is <strong>Markdown</strong>.</p>'

# With extensions
html = markdown.markdown(md, extensions=['fenced_code', 'tables'])

# Convert a file
with open('README.md') as f:
    html = markdown.markdown(f.read(), extensions=['extra'])

package main

import (
	"bytes"
	"fmt"
	"github.com/yuin/goldmark"
)

func main() {
	source := []byte("# Hello\n\nThis is **Markdown**.")
	var buf bytes.Buffer
	if err := goldmark.Convert(source, &buf); err != nil {
		panic(err)
	}
	fmt.Println(buf.String())
	// → <h1>Hello</h1>
	// → <p>This is <strong>Markdown</strong>.</p>
}

# Convert Markdown file to HTML
pandoc README.md -f markdown -t html -o output.html

# Convert with GitHub Flavored Markdown
pandoc README.md -f gfm -t html --standalone -o output.html

# Pipe from stdin
echo '# Hello **world**' | pandoc -f markdown -t html
# → <h1>Hello <strong>world</strong></h1>

Часто задаваемые вопросы