Я не слишком хорошо знаком с легким языком разметки, используемым github при обновлении файлов README.
Где ресурсы, которые я могу прочитать о том, как написать соответствующий синтаксис разметки для моей библиотеки с открытым исходным кодом README/wiki?
И есть ли инструмент, который я могу "просмотреть мои документы локально в своем браузере", прежде чем нажимать обновленный README в мой репозиторий github?
Разметка, о которой идет речь, по совпадению называется Markdown, созданной автором статьи Daring Fireball Джоном Грубером. Оригинальный источник Markdown можно найти в Daring Fireball - Markdown.
Есть много диалектов Markdown, документацию для Github можно найти на странице Github Flavored Markdown.
хороший отзыв с этой страницы:
нажмите M на любой странице Github с помощью редактора Markdown, чтобы открыть чит-лист.
Вы также можете использовать страницу Github Markdown Live Preview для проверки своих документов Markdown.
Обновление 2012-11-08. В настоящее время предпринимаются усилия по стандартизации синтаксиса Markdown. См. Будущее Markdown - Джефф Этвуд, Ужас кодирования и Группа сообщества W3C Markdown.
Обновление 2014-09-09: CommonMark был выпущен стандарт уценки и спецификация.
(Повторно опубликовать этот ответ с некоторыми изменениями.)
Немного поздно в игре, но я написал небольшую CLI в Python. Он называется Grip (мгновенный просмотр Github Readme). Добавив к Патрику ответ, это позволит вам "просматривать мои документы локально в моем браузере".
Установите его с помощью:
$ pip install grip
И использовать его просто:
$ grip
Затем посетите localhost:5000, чтобы просмотреть файл readme.md в этом месте.
Вы также можете указать свой собственный файл:
$ grip CHANGES.md
И измените порт:
$ grip 8080
Или объедините предыдущие два:
$ grip CHANGES.md 8080
Вы даже можете отобразить GitHub-Flavored Markdown (то есть, как отображаются комментарии и проблемы), необязательно с контекстом репо для ссылок на гиперссылку на другие проблемы:
$ grip --gfm --context=username/repo issue.md
Для краткости ознакомьтесь с остальными вариантами и их деталями с помощью справки CLI:
$ grip -h
Известные функции:
Надеюсь, это поможет. Проверьте это.
Обратите внимание, что с февраля 2014 года с помощью Rendered Prose Diffs" вы также можете увидеть рендерную версию diff в файле уценки
Записывает и тянет запросы, в том числе прозаические файлы, теперь имеют источник и визуализированные представления.
Нетекстовые изменения появляются с подчеркнутым подчеркиванием с низким ключом. Наведите указатель мыши на текст, чтобы увидеть, что изменилось:
Здесь есть приятный онлайн-редактор:
http://jbt.github.io/markdown-editor/
В GitHub также есть кнопка Preview.
Смотрите на следующем снимке экрана, что эта кнопка появляется, когда я нажимал Edit на README.md.
IMHO live editor лучше, чем текущий, доступный в GitHub.
UPDATE
Только что я нашел после поиска Markdown и Visual Studio, что, если вы используете VS, вы можете установить Web Essentials и имеют Markdown поддержку прямо из Visual Studio. Это круто!
Он имеет:
Подробности об этом здесь.
Другой вариант - новый текстовый редактор Github, Atom, будет отображать уценку github при настройке. См. https://atom.io/
Я не уверен, будет ли он бесплатным (как в пиве) в долгосрочной перспективе.
Я не нашел, что другие инструменты были достаточно хороши - я хотел:
Вот что я в конечном итоге решил: https://github.com/ypocat/gfms
> gfms
Github Flavored Markdown Server.
Run in your project 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, поэтому нет никаких сюрпризов.
На сегодняшний день вы можете просматривать, когда вы редактируете файл.
