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

106

Я не слишком знаком с облегченным языком разметки, используемым github при обновлении файлов README.

Где находятся ресурсы, которые я могу прочитать о том, как написать соответствующий синтаксис разметки для файлов README / wiki моей библиотеки с открытым исходным кодом?

И есть ли инструмент, с помощью которого я могу «просматривать мои документы локально в моем браузере», прежде чем отправлять обновленный README в свой репозиторий github?

Кальвин Ченг
источник

Ответы:

127

Разметка, о которой идет речь, случайно называется 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 - стандарт и спецификация уценки.

Патрик Клингеманн
источник
8
Спасибо за подсказку!
Jedidja 08
2
Предварительный просмотр Github Markdown Live Preview не отображает таблицы ...
Рубенс Мариуццо,
2
Если вы предпочитаете видео-скринкаст, я создал один, объясняющий Markdown, здесь: mikemclin.net/markdown-syntax-language
Mike McLin
2
@Mike McLin Отличное видео, объясняющее синтаксис и концепции! Отличное вступление для новичка в уценке, такого как я :)
Брок
1
Предварительный просмотр в реальном времени с уценкой также, похоже, не подчиняется правилам github о подчеркивании в середине слов, например my_setup_script.py не будет выделять курсивом «setup» в github, но будет в средстве предварительного просмотра. Это полезно, но чтобы люди знали.
user2428107
11

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

Немного поздно к игре, но я написал небольшой интерфейс командной строки на 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
  • Переход между связанными файлами
  • Экспорт обработанного документа в файл

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

Джо
источник
5

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

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.
  • Пользовательская таблица стилей => Вы можете добавить таблицу стилей для конкретного решения для управления стилями окна предварительного просмотра.

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

Лениэль Маккаферри
источник
4

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

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

https://f.cloud.github.com/assets/17715/1999080/7f0c15a2-853e-11e3-95dc-1d7737e1ec20.png

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

https://f.cloud.github.com/assets/17715/2005588/714cb5ea-86ef-11e3-9e92-a0d11ba6084f.png

VonC
источник
1

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

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

user2428107
источник
1

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

введите описание изображения здесь

Рубин
источник
0

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

  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, поэтому никаких сюрпризов нет.

шимми
источник