Я не надто знайомий з легкою мовою розмітки, яку використовує github під час оновлення файлів README.
Де знаходяться ресурси, які я можу прочитати про те, як написати відповідний синтаксис розмітки для файлів README / wiki моєї бібліотеки з відкритим кодом?
І чи є інструмент, за допомогою якого я можу "переглядати свої документи локально у своєму браузері", перш ніж натискати оновлене README до мого сховища github?
Відповіді:
Розглянута розмітка випадково називається Markdown , створена Джоном Грубером, автором блогу Daring Fireball . Оригінальне джерело Markdown можна знайти у Daring Fireball - Markdown .
Існує багато діалектів Markdown, документацію для Github можна знайти на сторінці Github Flavored Markdown .
хороша порада з цієї сторінки:
натисніть M на будь-якій сторінці Github з редактором Markdown, щоб виявити шпаргалку.
Ви також можете скористатись сторінкою попереднього перегляду Github Markdown Live для тестування документів Markdown.
Оновлення 2012-11-08 : Ведуться зусилля для стандартизації синтаксису Markdown. Дивіться майбутнє Markdown - Jeff Atwood, Coding Horror та W3C Markdown Community Group .
Оновлення 2014-09-09 : CommonMark стандарт розмітки та специфікація була випущена.
( Повторна публікація цієї відповіді з деякими правками.)
Трохи пізно до гри, але я написав невеликий CLI в Python. Це називається Grip (Github Readme Instant Preview) . Додавши відповідь Патріка, це дозволить вам "переглянути мої документи локально в моєму браузері".
Встановіть його за допомогою:
$ pip install grip
І використовувати його просто:
$ grip
Потім перейдіть, localhost:5000щоб переглянути readme.mdфайл у цьому місці.
Ви також можете вказати власний файл:
$ grip CHANGES.md
І змінити порт:
$ grip 8080
Або поєднайте попередні два:
$ grip CHANGES.md 8080
Ви навіть можете надати GitHub-ароматизовану відмітку (тобто, як виводяться коментарі та проблеми), необов'язково з контекстом репо, щоб автоматично посилатися на гіперпосилання на інші проблеми:
$ grip --gfm --context=username/repo issue.md
Для стислості ознайомтесь з рештою варіантів та їх деталями, використовуючи довідку CLI:
$ grip -h
Помітні функції:
Сподіваюся, це допомагає. Перевірте це .
Тут є хороший редактор в режимі онлайн / в прямому ефірі:
http://jbt.github.io/markdown-editor/
На PreviewGitHub також є кнопка.
На наступному скріншоті дивіться, що ця кнопка з’являється, коли я натиснув «Редагувати» README.md.
IMHO живий редактор краще, ніж поточний, доступний у GitHub.
ОНОВЛЕННЯ
Щойно я дізнався після пошуку Markdownта Visual Studio, що якщо ви використовуєте VS, ви можете встановити Web Essentials і мати Markdownпідтримку прямо з Visual Studio. Круто!
Це має:
Детальніше про це тут .
Зауважте, що з лютого 2014 року за допомогою " Намальованої прозової різниці " ви також можете побачити відредаговану версію різниці у файлі розмітки:
Здійснює подання та витягнення запитів, включаючи прозові файли, тепер міститься джерело та відображені види .
Нетекстові зміни відображаються з підкресленим пунктирним підкресленням. Наведіть курсор на текст, щоб побачити, що змінилося:
Ще один варіант - новий текстовий редактор Github, Atom, відображатиме розмітку з ароматом github під час редагування. Дивіться https://atom.io/
Я не впевнений, чи буде це безкоштовно (як у пиві) у довгостроковій перспективі.
Я не виявив, що інші інструменти досить хороші - я хотів:
Це я врешті-решт вирішив: https://github.com/ypocat/gfms
> gfms
Github Flavored Markdown Server.
Run in your project's root directory.
Usage: gfms
Options:
-p, --port Port number to listen at. [required]
-h, --host Host address to bind to. [default: "localhost"]
--proxy if behind a proxy, proxy url.
-a, --api Render using Github API.
-n, --no-api-on-reload Disable usage of Github API when the doc is manually reloaded.
Тож я відчув:
alias gm='gfms -a -p 8070'
Використання -pопції звертається до API Github і використовує фактичний, поточний Github CSS, так що сюрпризів немає.