Что такое файл README в формате markdown на Github?

27

Мне неясно, что это за формат, есть ли систематические требования / требования командной строки для его создания и т. Д.

В основном, просто нужно знать спецификации и, если есть технические шаги для создания файла README.

github просчеты
источник
4
Нет, просто текстовый файл, который вы редактируете вручную. Что касается синтаксиса, en.wikipedia.org/wiki/Markdown
Андреа
3
это тот же формат wiki-edit-, который использует эта сторона.
k3b
+1 @ Андреа: Спасибо, хотя я могу придумать больше, чем несколько форматов уценки, какой формат и версия ожидается на Github? Кроме того, ваш комментарий читается как ответ, пожалуйста, опубликуйте его как полный ответ. Еще раз спасибо!
промахи
+1 @ K3b: Полагаю, вы к чему-то относитесь, вы говорите об использовании Github Голлума , который, например, позволяет относительные ссылки? Если это так, пожалуйста, опубликуйте это как ответ, так как я считаю, что это правильный ответ. Благодарность!
промахи

Ответы:

37

Markdown - это простой синтаксис для предоставления семантической информации и представления общего форматирования в виде простого текста. У Daring Fireball есть потрясающее руководство по синтаксису для стандартной уценки . Затем GitHub использует вариант этого, который они называют GitHub Flavored Markdown .

Для настройки вашего readme просто создайте текстовый файл и назовите его README (или README.md / README.markdown) и передайте его в корень вашего репозитория. GitHub примет это как readme проекта.

Ким Берджесс
источник
2
Я также создал видео, объясняющее, как использовать Markdown. Вы можете найти его здесь: mikemclin.net/markdown-syntax-language
Майк Маклин
9

Википедия - Markdown ссылается на страницу «GitHub Flavored Markdown - Введение» ( арх. )

Цитата со страницы:

GitHub использует то, что мы называем «GitHub Flavored Markdown» (GFH) для сообщений, проблем и комментариев. Он отличается от стандартной Markdown (SM) несколькими существенными отличиями и добавляет некоторые дополнительные функции.

На странице также дается описание отличий от стандартной уценки.

Также есть больше информации о том, как на самом деле Markdown отображается в GitHub:

Если вы заинтересованы в том, как мы отображаем файлы Markdown, вы можете попробовать Redcarpet , наш интерфейс Ruby для библиотеки Sundown .

(Судя по всему, Sundown - это фактический анализатор Markdown, который используется за занавесом.)

Чтобы добавить еще один уровень абстракции, Sundown - это форк даже еще одного анализатора Markdown :-)
Цитата со страницы Sundown на GitHub :

Sundown - это анализатор Markdown, основанный на оригинальном коде библиотеки Upskirt от Natacha Porté.

Кристиан Шпехт
источник
1

Это очень странно, но похоже, что GitHub не использует GitHub-Flavored Markdown (GFM) при рендеринге файла README.

GitHub использует «GitHub Flavored Markdown», или GFM, по всему сайту - в вопросах, комментариях и запросах по запросу.

Вместо этого он использует версию redcarpet как часть проекта разметки GitHub . Они также поддерживают несколько других форматов разметки, включая MediaWiki. Просто используйте правильное расширение файла, и GitHub отобразит разметку.

Если вы хотите увидеть различия между двумя различными разновидностями Markdown, прочтите описание GFM и его дополнительные функции .

Дон Киркби
источник
1
redcarpet и Github Flavored Markdown - это две разные, но дополняющие друг друга концепции, а не конкурирующие реализации одной и той же вещи. redcarpet в основном компилятор , который принимает вещи , написанные в Github ароматизированного Markdown языка и выводит HTML или XHTML.
8bittree