Работа с README.md на github.com [закрыто]

Я не слишком знаком с облегченным языком разметки, используемым 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 - Джефф Этвуд, Coding Horror и группа сообщества W3C Markdown .

Обновление 2014-09-09 : CommonMark - стандарт и спецификация уценки.

( Повторная публикация этого ответа с некоторыми изменениями.)

Немного поздно к игре, но я написал небольшой интерфейс командной строки на Python. Это называется Grip (мгновенный просмотр Github Readme) . В дополнение к ответу Патрика это позволит вам «просматривать мои документы локально в моем браузере».

Установите его с помощью:

$ 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

Примечательные особенности:

• Отображает страницы так, чтобы они выглядели так же, как на GitHub
• Огороженные блоки
• Python API
• Переход между связанными файлами
• Экспорт обработанного документа в файл

Надеюсь это поможет. Проверить это .

Здесь есть хороший онлайн-редактор:

http://jbt.github.io/markdown-editor/

Также есть Previewкнопка на GitHub.

На следующем снимке экрана видно, что эта кнопка появляется, когда я нажимаю «Изменить» README.md.

IMHO живой редактор лучше, чем текущий, доступный на GitHub.

ОБНОВИТЬ

Только что после поиска Markdownи Visual Studio я обнаружил, что если вы используете VS, вы можете установить Web Essentials и получить Markdownподдержку прямо из Visual Studio. Это классно!

Оно имеет:

• Подсветка синтаксиса => Полная раскраска синтаксиса Markdown
• Intellisense для встроенных языков ( W00T ) => Функция встроенного языка GitHub полностью поддерживается за счет поддержки синтаксиса языка.

• Окно предварительного просмотра => Просмотр бок о бок окно предварительного просмотра визуализированного HTML
• Скомпилировать в HTML => Щелкните правой кнопкой мыши любой файл Markdown и выберите Компилировать Markdown в HTML. Это создаст файл .html, вложенный в файл Markdown, и он будет синхронизироваться по мере изменения файла Markdown.
• Пользовательская таблица стилей => Вы можете добавить таблицу стилей для конкретного решения для управления стилями окна предварительного просмотра.

Подробности здесь .

Обратите внимание, что с февраля 2014 года с « Rendered Prose Diffs » вы также можете увидеть визуализированную версию diff в файле уценки:

Коммиты и запросы на вытягивание, включая файлы прозы, теперь содержат исходные и обработанные представления .

Нетекстовые изменения выделяются сдержанным подчеркнутым пунктиром. Наведите курсор на текст, чтобы увидеть, что изменилось:

Другой вариант - новый текстовый редактор Github, Atom, будет отображать уценку со вкусом github, когда вы его редактируете. См. Https://atom.io/

Я не уверен, будет ли оно бесплатным (как пиво) в долгосрочной перспективе.

С сегодняшнего дня вы можете предварительно просмотреть, как редактируете файл.

Я не нашел, что другие инструменты достаточно хороши - я хотел:

1. Возможность редактировать офлайн
2. Не просто обычная уценка, но и актуальная уценка, приправленная Github.

В конечном итоге я остановился на этом: 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опции приводит к обращению к Github API и использует текущий текущий CSS Github, поэтому никаких сюрпризов нет.