Редактор README помогает писать файлы README.md с живым предпросмотром в стиле GitHub, кликабельным оглавлением, списками задач, таблицами и блоками кода. Начните с примера README, форматируйте через панель инструментов или горячие клавиши и скачайте .md или самостоятельную HTML-страницу. Черновик сохраняется в браузере по мере набора.
Как пользоваться
- Пишите Markdown в редакторе или перетащите, откройте либо вставьте файл .md. Для начала загружен пример README.
- Панель и горячие клавиши добавляют жирный, курсив, заголовки, ссылки, списки, задачи, код, цитаты и таблицы.
- На вкладке «Просмотр» — результат в стиле GitHub с кликабельным содержанием, на вкладке HTML — готовый код.
- Скопируйте HTML, скачайте самостоятельную страницу .html со стилями или файл .md.
- Поддерживается GitHub Flavored Markdown: таблицы, списки задач, блоки кода, зачёркивание и автоссылки. Заголовки получают якоря как на GitHub.
- HTML очищается: скрипты и небезопасные атрибуты удаляются.
- Черновик автоматически сохраняется в этом браузере и будет на месте, когда вы вернётесь.
- На широком экране режим «Рядом» показывает редактор и просмотр одновременно.
Что должно быть в хорошем README
README — первое, что видят в репозитории, поэтому он должен быстро отвечать на три вопроса: что делает проект, как его установить и как им пользоваться. Обычный порядок: описание в одну строку, короткий пример или скриншот, установка, использование с блоком кода, настройка, как помочь проекту и лицензия. Первый абзац лучше писать без жаргона, детали — ниже.
Блоки кода с названием языка (```js, ```bash) на GitHub получают подсветку синтаксиса. Относительные ссылки вроде docs/setup.md работают внутри репозитория, а картинки могут ссылаться на его файлы.
GitHub Flavored Markdown
Предпросмотр следует GitHub Flavored Markdown (GFM) — расширению стандарта CommonMark. Кроме заголовков, списков, ссылок и выделения, в нём есть таблицы с вертикальными чертами, списки задач - [ ] и - [x], ~~зачёркивание~~, автоматические ссылки для голых URL и огороженные блоки кода. Каждый заголовок получает якорь в стиле GitHub, так что ссылка вида #установка ведёт к нужному разделу; на этом построено оглавление.
Частые вопросы
Как добавить оглавление в README?
Добавьте список ссылок на якоря заголовков, например - [Использование](#использование); GitHub обрабатывает их так же, как предпросмотр. Кликабельное оглавление в предпросмотре показывает каждый заголовок и его якорь.
Как сделать список задач?
Начните строку с - [ ] для открытой задачи или - [x] для выполненной. На GitHub такие списки в issues и pull requests можно отмечать прямо на странице.
Поддерживаются ли таблицы и блоки кода GitHub?
Да. В таблицах столбцы разделяются символом |, а под заголовком идёт строка дефисов; блоки кода начинаются и заканчиваются тремя обратными апострофами.
Сохраняется ли черновик?
Да, автоматически в этом браузере, и он на месте при следующем визите. Ничего не загружается.
Можно ли получить HTML?
Да. Переключитесь на вид HTML, чтобы скопировать сгенерированную очищенную разметку, или скачайте самостоятельную .html-страницу со стилями.