Есть ли утилита командной строки для рендеринга GitHub со вкусом Markdown?

414

Мне интересно, есть ли утилита командной строки для получения файла Markdown со вкусом GitHub и рендеринга его в HTML.

Я использую вики GitHub для создания контента сайта. Я клонировал репозиторий на своем сервере и хотел бы обработать его в обычном HTML. Для меня важно, что то, что появляется на GitHub, именно так и должно выглядеть для моего сайта. Я также хотел бы использовать огороженные блоки с ~~~, поэтому я бы предпочел не использовать только стандартный синтаксис Markdown.

Я немного заглянул в предварительный просмотр JavaScript, думая, что смогу подключить его к Node.js, но они говорят, что он устарел. Я посмотрел на репозиторий redcarpet, но он не похож на интерфейс командной строки.

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

McLeopold
источник
2
RE: ОБНОВЛЕНИЕ: если бы я добавил --outаргумент в grip для рендеринга в файл HTML вместо браузера, это было бы приемлемо?
Джо
@ Джо, пожалуйста, добавь эту опцию!
bguiz
@McLeopold @bguiz только что развернул --exportопцию, которая отображает GFM и его стили в один файл. Это отвечает на вопрос?
Джо
3
@McLeopold, Джо выбил это из парка, создав простое многократно используемое решение, возможно, захочет дать ему ответ.
Джеймс МакМахон
1
Сам Github использует Sundown . См stackoverflow.com/a/7694931/632951
Pacerier

Ответы:

447

Я написал небольшой CLI на Python и добавил поддержку GFM. Это называется Grip (Github Readme Instant Preview) .

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

$ pip install grip

И использовать это просто:

$ grip

Тогда посетите localhost:5000 чтобы просмотреть readme.mdфайл в этом месте.

Вы также можете указать свой собственный файл:

$ grip CHANGES.md

И изменить порт:

$ grip 8080

И, конечно же, специально отображать GitHub-Flavored Markdown, опционально с контекстом репозитория:

$ grip --gfm --context=username/repo issue.md

Известные особенности:

  • Отображает страницы так же, как на GitHub
  • Огороженные блоки
  • Python API
  • Навигация между связанными файлами (спасибо, vladwing !) Добавлена ​​в 2.0
  • Экспорт в один файл (спасибо, iliggio !) Добавлен в 2.0
  • Новое: чтение stdinи stdout добавление в 3.0.

Надеюсь, это поможет кому-то здесь. Проверьте это .

Джо
источник
1
Работает очень хорошо, и вы не можете превзойти простоту установки для Pythonistas!
RichVel
29
Это должно быть первым хитом для «предварительного просмотра уценки github». Все остальное сложно, не работает или не выполняет все функции GitHub. gripработает прямо из коробки.
Bluu
1
@Houdini Эта проблема устарела. Flask поддерживает 3.3, см. Flask.pocoo.org/docs/python3 . Вот более свежая ветка Github по теме github.com/mitsuhiko/flask/issues/587 . Если есть другая зависимость, требующая обновления, не стесняйтесь открыть вопрос или запрос на извлечение.
Джо
3
Следует отметить, что для этого пакета требуется активное подключение к Интернету и ваши учетные данные для аутентификации на github (предоставляются в командной строке), если вы выполняете более 60 обновлений в час.
Лев
13
Как упоминалось ранее, я не думаю, что это особенно хорошее решение, потому что все, что он делает, отправляется на Github и заставляет Github визуализировать ваш Markdown. Требуется работающее интернет-соединение с доступом к Github, и если Github умирает, этот инструмент перестает работать. Я предпочел бы иметь полностью автономное решение.
Еж
114

Я не нашел быстрого и простого метода для Markdown со вкусом GitHub, но нашел немного более общую версию - Pandoc . Он конвертирует из / в ряд форматов, включая Markdown, Rest, HTML и другие.

Я также разработал Makefileдля преобразования всех файлов .md в .html (в значительной степени к примеру в Writing, Markdown и Pandoc ):

# 'Makefile'
MARKDOWN = pandoc --from gfm --to html --standalone
all: $(patsubst %.md,%.html,$(wildcard *.md)) Makefile

clean:
    rm -f $(patsubst %.md,%.html,$(wildcard *.md))
    rm -f *.bak *~

%.html: %.md
    $(MARKDOWN) $< --output $@
Алистер Булман
источник
4
я использовал «watch pandoc ...» для непрерывного преобразования файла уценки в html, а расширение «live reload» в chrome для получения в реальном времени функциональности «оставайся там, где меня прокручивают», и это прекрасно работает , chrome.google.com/webstore/detail/livereload/…
Брэд Паркс,
1
Pandoc хорошо читает GFM, но не генерирует тот же HTML, что и GitHub - например, если у вас есть многострочный <pre/>тег в исходном коде GFM, Pandoc будет вставлять <br/>теги для разрывов строк, в то время как GitHub отображает его. он удаляет пробелы, кажется, в противном случае оставляет содержимое в покое.
Дэвид Моулз
1
Как можно получить хорошее оформление результирующего HTML? Например, мой вывод все еще отображается с помощью Times New Roman.
Целостный разработчик
Инструкции по установке Pandoc находятся здесь . На macOS:brew install pandoc
Мастер уток
1
ни форматы ввода, gfmни markdown_githubвходные форматы правильно не отображают такие вещи, как блоки кода.
user5359531
29

Может быть, это может помочь:

gem install github-markdown

Документации не существует, но я получил ее из документации gollum . Глядя на rubydoc.info , похоже, что вы можете использовать:

require 'github/markdown'  
puts GitHub::Markdown.render_gfm('your markdown string')

в вашем коде Ruby. Вы можете легко обернуть это в скрипт, чтобы превратить его в утилиту командной строки:

#!/usr/bin/env ruby

# render.rb
require 'github/markdown'

puts GitHub::Markdown.render_gfm File.read(ARGV[0])

Выполните это с ./render.rb path/to/my/markdown/file.md. Обратите внимание, что это небезопасно для использования в производстве без очистки.

Джеймс Лим
источник
1
Благодаря Джиму, из-за практически несуществующих примеров, я застрял на этапе требуется (замена черты с косой чертой сделала это ..;)
plesatejvlk
Это замечательно, если вы уже используете NPM. Мне пришлось использовать его из-за того, что DOxygen вызывал у меня постоянные проблемы со специфической уценкой github + экспорт в HTML.
kayleeFrye_onDeck
это работает локально или отправляет данные в GitHub API?
user5359531
28
pip3 install --user markdown
python3 -m markdown readme.md > readme.html

Он не обрабатывает расширения GitHub, но это лучше, чем ничего. Я считаю, что вы можете расширить модуль для обработки дополнений GitHub.

Гринго Суаве
источник
1
/ usr / bin / python: разметка является пакетом и не может быть выполнена напрямую
Kazimieras Aliulis
2
Простой вывод HTML без причудливых тегов.
Халил Каскавальцы
23

Возможно, это не то, что вам нужно, но, поскольку вы упомянули Node.js: я не смог найти хороший инструмент для предварительного просмотра документации GitHub Flavored Markdown на моем локальном диске перед их фиксацией в GitHub, поэтому сегодня я создал один на основе Node.js: https : //github.com/ypocat/gfms

Так что, возможно, вы можете использовать showdown.js из него для своей Wiki, если ваш вопрос все еще актуален. Если нет, возможно, другие люди, столкнувшиеся с той же проблемой, что и я, найдут (как и я) этот вопрос и ответ на него.

youurayy
источник
Молодец, мужик. Спасает меня от необходимости прибегать к Ruby или Python, когда я пишу приложение для узла, и это здорово.
jedd.ahyoung
19

Для чтения файла README.md в терминале я использую:

pandoc README.md | lynx -stdin

Pandoc выводит его в формате HTML, который Lynx отображает в вашем терминале.

Он отлично работает: он заполняет мой терминал, ярлыки показаны ниже, я могу пролистать, и ссылки работают! Хотя есть только один размер шрифта, но цвета + отступы + выравнивание восполняют это.

Установка:

sudo apt-get install pandoc lynx
Барри Стес
источник
1
Вопрос конкретно об использовании командной строки. Прежде чем писать свой собственный скрипт ruby ​​(или сервер узла egad), сделайте это.
Кора Миддлтон
Именно это работает внутри вашего терминала. Или, если ваш любимый (настольный?) Браузер может получить доступ к этой папке, использовать pandoc readme.md -o readme.md.htmlи открыть полученный файл.
Барри Стейс
@ baerry-staes Да, извините, я надеюсь, было ясно, что ваш был моим любимым ответом.
Кора Миддлтон
@JustinMiddleton да, я понял, спасибо. Мой комментарий состоял в том, чтобы просто добавить дополнительную информацию для пользователей настольных компьютеров ... Я подумал, что кто-то когда-нибудь прочтет это, может оказаться полезным.
Барри Стес
1
Я пробовал около 5-6 других консольных md-ридеров, и это было лучшим решением. Я просто добавил самую основную функцию в мою конфигурацию, чтобы сделать ее немного быстрее в использовании. function md { pandoc $@ | lynx -stdin }
Расс Браун
17

GitHub имеет API Markdown, который вы можете использовать.

kehers
источник
5
jq --slurp --raw-input '{"text": "\(.)", "mode": "markdown"}' < README.md | curl --data @- https://api.github.com/markdown > README.html
Вебьорн Льоса
@VebjornLjosa * что * или grip... вы выбрали. : P
yyny
13

Используйте помеченные . Он поддерживает GitHub Flavored Markdown, может использоваться как модуль Node.js и из командной строки.

Примером может быть:

$ marked -o hello.html
hello world
^D
$ cat hello.html
<p>hello world</p>
zemirco
источник
1
Я заметил, что это не поддерживает такие функции, как подсветка синтаксиса для блоков кода и новые функции, такие как контрольные списки. Но эй, это проходит большую часть пути!
bguiz
Очень хорошо, единственное, чего мне не хватает - это какие-то границы для таблиц. Ну, по крайней мере, я могу сделать их вообще, это почти то, что мне нужно. Труба в GFM,
трубач
Я запутался в этом примере, что это ^D?
Мэтью
10

В основном это продолжение ответа @ barry-staes за использование Pandoc . У Homebrew это также есть, если вы на Mac:

brew install pandoc

Pandoc поддерживает GFM в качестве формата ввода через markdown_githubимя.

Вывод в файл

cat foo.md | pandoc -f markdown_github > foo.html

Открыть в рыси

cat foo.md | pandoc -f markdown_github | lynx -stdin # To open in Lynx

Откройте в браузере по умолчанию на OS X

cat foo.md | pandoc -f markdown_github > foo.html && open foo.html # To open in the default browser on OS X`

Интеграция TextMate

Вы всегда можете перенаправить текущий выбор или текущий документ к одному из вышеперечисленных, как позволяет большинство редакторов. Вы также можете легко настроить среду так, pandocчтобы она заменяла процессор Markdown по умолчанию, используемый в пакете Markdown .

Сначала создайте скрипт оболочки со следующим содержимым (я его назову ghmarkdown):

#!/bin/bash
# Note included, optional --email-obfuscation arg
pandoc -f markdown_github --email-obfuscation=references

Затем вы можете установить TM_MARKDOWNпеременную (в Предпочтения → Переменные) /path/to/ghmarkdown, и она заменит процессор Markdown по умолчанию.

Кора Миддлтон
источник
10

Я создал инструмент, аналогичный функциональности предварительного просмотра Atom, но как отдельное приложение. Не уверен, что это то, что вы ищете, но это может быть полезно. - https://github.com/yoshuawuyts/vmd

VMD

Йошуа Вуйц
источник
Вы, ребята, все еще поддерживаете это? Я попытался установить с NPM сегодня, но без игры в кости. > загрузка Electron-v0.36.9-win32-x64.zip> Ошибка: самозаверяющий сертификат
kayleeFrye_onDeck
1
Да, мы! На какой версии npm / node вы это запустили? - не стесняйтесь, чтобы открыть вопрос о GH, и мы посмотрим на это. Спасибо!
Йошуа Вуйц
8

pandocс browserхорошо работает для меня.

Применение: cat README.md | pandoc -f markdown_github | browser

Установка (при условии, что вы используете Mac OSX):

  • $ brew install pandoc

  • $ brew install browser

Или на Debian / Ubuntu: apt-get install pandoc browser

binarymason
источник
1
apt-get isntall pandocбудет делать, нет необходимости использовать небезопасные, местные вещи, такие как варево.
Доминик Джордж
1
@DominikGeorge есть опечатка, это установить , а не isntall
Федерико Томассетти
11
@DominikGeorge нет ничего подходящего для macOS.
Ричрад
6

Также см. Https://softwareengineering.stackexchange.com/a/128721/24257 .


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

Ruby-скрипт, использующий Redcarpet , будет «утилитой командной строки», если у вас будет локальный Ruby

Ленивый Барсук
источник
Понятия не имею - я не пишу Ruby и я не читал источники Redcarpet
Lazy Badger
@LazyBadger, Sundown - это фактический парсер (написанный на C). Красный карпет не нужен.
Pacerier
6

Основываясь на этом комментарии, я написал однострочник, чтобы поразить Github Markdown API, используя curlи jq.

Вставьте эту функцию bash в командную строку или в ваш ~/.bash_profile:

mdsee(){ 
    HTMLFILE="$(mktemp -u).html"
    cat "$1" | \
      jq --slurp --raw-input '{"text": "\(.)", "mode": "markdown"}' | \
      curl -s --data @- https://api.github.com/markdown > "$HTMLFILE"
    echo $HTMLFILE
    open "$HTMLFILE"
}

А затем, чтобы увидеть, как отображается обработанный HTML-код в браузере:

mdsee readme.md

Замените open "$HTMLFILE"на, lynx "$HTMLFILE"если вам нужно чистое терминальное решение.

notpeter
источник
4

GitHub (с тех пор) разработал хороший модульный текстовый редактор под названием Atom (на основе Chromium и использует Node.js). модули для пакетов).

Предварительно установленный по умолчанию пакет Markdown Preview позволяет отображать предварительный просмотр на отдельной вкладке с помощью Ctrl+ Shift+ M.

Я не проверял его полный синтаксис, но, поскольку он исходит от GitHub, я был бы очень удивлен, если бы синтаксис предварительного просмотра отличался от их (огражденные блоки используют ~~~work).

Теперь, хотя технически он не основан на командной строке, он использует Node.js и выводит его на DOM- рендерер, который может помочь любому, пытающемуся отобразить HTML на основе синтаксиса GitHub на веб-сервере на основе Node.js, или просто отредактировать ее. / его README.md не в сети.

Que
источник
1
В Atom вы можете установить пакет с именем gfm-pdf ( atom.io/packages/gfm-pdf ), который экспортирует ваш документ уценки в документ HTML и / или PDF. Требуется библиотека wkhtmltopdf .
spren9er
3

Существует действительно хороший и простой инструмент для просмотра документов GFM Markdown:

GFMS - Github ароматизированный сервер уценки

Это простой и легкий (не требующий настройки) HTTP-сервер, который вы можете запустить в любом каталоге, содержащем файлы уценки, чтобы просмотреть их.

Особенности:

  • Полная поддержка GFM Markdown
  • Подсветка синтаксиса исходного кода
  • Просмотр файлов и каталогов
  • Приятный внешний вид (и настраиваемые таблицы стилей CSS)
  • Экспорт в PDF
Павел Wiejacha
источник
3

Мне удалось использовать для этой цели однострочный скрипт Ruby (хотя он должен был находиться в отдельном файле). Сначала выполните эти команды один раз на каждой клиентской машине, с которой вы будете загружать документы:

gem install github-markup
gem install commonmarker

Затем установите этот скрипт в образе клиента и назовите его render-readme-for-javadoc.rb:

require 'github/markup'

puts GitHub::Markup.render_s(GitHub::Markups::MARKUP_MARKDOWN, File.read('README.md'))

Наконец, вызовите это так:

ruby ./render-readme-for-javadoc.rb >> project/src/main/javadoc/overview.html

ETA: Это не поможет вам с Markdown StackOverflow-flavour, который, похоже, не отвечает этому ответу.

Pr0methean
источник
Я думаю, что это самый близкий к источнику ответ из всех, поскольку эти инструменты используются github.
memoselyk
3

Я использую Pandoc с опцией --from=gfmдля GitHub Flavored Markdown следующим образом:

$ pandoc my_file.md   --from=gfm -t html -o my_file.html
Асме Просто
источник
С pandoc 1.16.0.2 на Linux Mint 18 Я получаю сообщение об ошибке: pandoc: Unknown reader: gfm. Переход к 2.2.1 исправляет это.
Kidmose
Я проверил это с Pandoc 2.1.2.
Asme Just
как установить 2.2.1 на Ubuntu?
Александр Миллс
@AlexanderMills Вы пробовали sudo apt install pandoc?
Asme Just
2

Улучшение решения @ barry-stae. Вставьте этот фрагмент в ~ / .bashrc

function mdviewer(){
  pandoc $* | lynx -stdin
}

Затем мы можем быстро просмотреть файл из командной строки. Также хорошо работает в сеансах SSH / Telnet.

mdviewer README.md
Sandeep
источник
2

Позднее добавление, но у showdownjs есть инструмент CLI, который вы можете использовать для анализа MD в HTML.

Tivie
источник
1

Я нашел сайт, который сделает это за вас: http://tmpvar.com/markdown.html . Вставьте свой Markdown, и он отобразит его для вас. Кажется, работает просто отлично!

Тем не менее, он, кажется, не обрабатывает опцию подсветки синтаксиса для кода; то есть ~~~rubyфункция не работает. Это просто печатает «рубин».

JESii
источник
Похоже, что tmpvar не делает улучшения версий GFM, такие как таблицы
Greg
0

Улучшая ответы @ barry-stae и @Sandeep для обычных пользователей elinks, вы добавили бы следующее .bashrc:

function mdviewer() {
  pandoc $* | elinks --force-html
}

Не забудьте установить pandoc (и elinks).

daBertl
источник
0

Основываясь на ответе Джима Лима , я установил гем GitHub Markdown. Это включало скрипт gfm, который принимает имя файла в командной строке и записывает эквивалентный HTML в стандартный вывод. Я немного изменил это, чтобы сохранить файл на диск, а затем открыть стандартный браузер с помощью launchy:

#!/usr/bin/env ruby

HELP = <<-help
  Usage: gfm [--readme | --plaintext] [<file>]
  Convert a GitHub-Flavored Markdown file to HTML and write to standard output.
  With no <file> or when <file> is '-', read Markdown source text from standard input.
  With `--readme`, the files are parsed like README.md files in GitHub.com. By default,
  the files are parsed with all the GFM extensions.
help

if ARGV.include?('--help')
  puts HELP
  exit 0
end

root = File.expand_path('../../', __FILE__)
$:.unshift File.expand_path('lib', root)

require 'github/markdown'
require 'tempfile'
require 'launchy'

mode = :gfm
mode = :markdown if ARGV.delete('--readme')
mode = :plaintext if ARGV.delete('--plaintext')

outputFilePath = File.join(Dir.tmpdir, File.basename(ARGF.path))  + ".html"

File.open(outputFilePath, "w") do |outputFile |
    outputFile.write(GitHub::Markdown.to_html(ARGF.read, mode))
end

outputFileUri = 'file:///' + outputFilePath

Launchy.open(outputFileUri)
gerrard00
источник
1
Я пробовал это с огороженными блоками для Ruby и Cucumber. Хотя заборы ( ruby, огурцы и т. Д.), По-видимому, распознаются как заборы (поскольку они отображаются в тексте с фиксированной шириной), подсветка синтаксиса отсутствует. Есть идеи почему?
Кит Беннетт
0

Подход «быстрый и грязный» заключается в загрузке HTML-страниц вики с помощью wgetутилиты, а не клонировании. Например, вот как я скачал вики Hystrix с GitHub (я использую Ubuntu Linux):

 $ wget -e robots=off -nH -E -H -k -K -p https://github.com/Netflix/Hystrix/wiki
 $ wget -e robots=off -nH -E -H -k -K -I "Netflix/Hystrix/wiki" -r -l 1 https://github.com/Netflix/Hystrix/wiki

Первый вызов загрузит страницу входа в вики и все ее зависимости. Второй вызовет все подстраницы на нем. Теперь вы можете просматривать вики, открывNetflix/Hystrix/wiki.1.html .

Обратите внимание, что оба вызова wgetнеобходимы. Если вы просто запустите второй, то пропустите некоторые зависимости, необходимые для правильного отображения страниц.

Луис Родеро-Мерино
источник
-1

Я недавно сделал то, что вы хотите, потому что мне нужно было сгенерировать документацию из файлов Markdown, и стиль GitHub довольно хорош. Попробуй это. Написано в Node.js.

GFM

Габриэль Ламас
источник
Я знаю, что модуль не обновлялся в течение 9 месяцев, почему вы понижаете старый пост?
Габриэль Ламас