是否有一个命令行实用工具可以渲染GitHub风格的Markdown?

456

我想知道是否有一个命令行实用程序可以将GitHub flavored Markdown文件渲染为HTML。

我正在使用GitHub wiki创建网站内容。 我已经在我的服务器上克隆了存储库,然后想将其处理为常规HTML。 对我来说,重要的是在GitHub上显示的内容与我的网站上的内容完全一样。 我也非常想使用带有~~~的围栏块,因此我不想仅使用标准Markdown语法。

我研究了一下JavaScript实时预览,以为可以将其连接到Node.js,但他们说它已被弃用。 我看了一下redcarpet存储库,但它似乎没有命令行界面。

我自己开发了一个解决方案,但由于这里没有明显优于其他解决方案的解决方案,所以我会将问题留在没有选定答案的状态。


2
回复:更新:如果我给grip添加一个“--out”参数,以便将渲染输出到HTML文件而不是浏览器,这样是否可以接受? - Joe
1
@McLeopold @bguiz 刚刚部署了 --export 选项,它将 GFM 及其样式渲染为单个文件。这回答了你的问题吗? - Joe
@Joe,好的,我会去看看! - bguiz
3
@McLeopold,Joe通过创建一个简单可重用的解决方案成功地完成了这项工作,你可能想要接受他的答案。 - James McMahon
1
Github本身使用Sundown。请参见https://dev59.com/D2sz5IYBdhLWcg3wuKe7#7694931。 - Pacerier
显示剩余6条评论
26个回答

491

我用Python编写了一个小型CLI,并添加了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读取并导出到stdout3.0版本中添加

查看详情


36
这应该是搜索“github markdown预览”的首选结果。其他东西都很复杂,无法使用或无法实现所有GitHub功能。grip可以直接使用。 - Bluu
1
@Houdini 那个问题已经过时了。Flask支持3.3,参见http://flask.pocoo.org/docs/python3/。这里有一个更近期的Github讨论主题https://github.com/mitsuhiko/flask/issues/587。如果还有其他需要更新的依赖项,请随时打开一个问题或拉取请求。 - Joe
4
请注意,此软件包需要保持活动的互联网连接,并在每小时刷新超过60次时提供您的GitHub身份验证凭据(通过命令行提供)。 - leo
1
这对于创建Github维基的本地镜像非常好。首先,通过运行此命令克隆您的Wiki(将.git替换为.wiki)git clone https://github.com/user/project.wiki。然后,您可以使用Grip在本地托管它,实现杀手级组合 :) - Gourneau
17
如前所述,我认为这不是一个特别好的解决方案,因为它只是跳转到Github并让Github渲染你的Markdown。它需要一个能够访问Github的工作互联网连接,如果Github出现问题,那么这个工具就无法使用。我更喜欢完全离线的解决方案。 - Jez
显示剩余16条评论

121

我还没有找到一种适用于GitHub风格Markdown的快速简便方法,但我找到了一个稍微通用一些的方法-Pandoc。它可以将多种格式进行相互转换,包括Markdown,Rest,HTML和其他格式。

我还开发了一个Makefile,将所有的.md文件转换为.html文件(这在很大程度上得益于编写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…”将Markdown文件持续转换为HTML,并使用Chrome浏览器的“live reload”扩展程序,以实现实时的“停留在我所滚动到的位置”功能,效果非常好。https://chrome.google.com/webstore/detail/livereload/jnihajbhpnppcggbcgedagnkighmdlei?utm_source=gmail - Brad Parks
3
Pandoc可以很好地读取GFM,但它不能生成与GitHub相同的HTML代码。例如,如果你在GFM源代码中有一个多行的<pre/>标签,Pandoc会将<br/>标签插入其中以进行换行,而GitHub的渲染器虽然会去掉前导空白,但似乎其他方面不会对内容进行修改。 - David Moles
1
如何使生成的HTML具有良好的样式?例如,我的输出仍然使用Times New Roman 渲染。 - Holistic Developer
1
Pandoc的安装说明在这里。在macOS上:brew install pandoc - Master of Ducks
2
无论是 gfm 还是 markdown_github 输入格式都无法正确呈现代码块。 - user5359531
显示剩余2条评论

31
pip3 install --user markdown
python3 -m markdown readme.md > readme.html

它不能处理GitHub扩展,但总比没有好。我相信你可以扩展这个模块,以处理GitHub的扩展。


1
/usr/bin/python:markdown是一个包,不能直接执行。 - Kazimieras Aliulis
2
简单的HTML输出,没有花哨的标签。 - Halil
1
严格来说,这是“John Gruber的Markdown”,而不是GitHub风格的Markdown。 - user3064538

29

也许这可以帮助你:

gem install github-markdown

没有文档,但我从gollum文档中获取了它。查看rubydoc.info,似乎可以使用以下内容:

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

在您的Ruby代码中,您可以轻松地将其包装在脚本中,以将其转换为命令行实用程序:

在您的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
谢谢Jim,由于几乎没有例子,我在require步骤卡住了(将破折号替换为斜杠解决了它).. ;) - plesatejvlk
如果你已经在使用NPM,这很好。因为DOxygen给我造成了很多问题,特别是在处理github风格的markdown+导出到HTML方面。所以我不得不使用它。 - kayleeFrye_onDeck
1
这是在本地运行还是向GitHub API发送数据? - user5359531

26

在终端中阅读README.md文件,我使用以下命令:

pandoc README.md | lynx -stdin

Pandoc以HTML格式输出,Lynx在终端中呈现它。

效果很好:它填满了我的终端,快捷键显示在下面,我可以通过滚动来操作,链接也可以使用!虽然只有一种字体大小,但颜色+缩进+对齐方式弥补了它的不足。

安装:

  • apt: sudo apt-get install pandoc lynx
  • nix: nix-shell -p pandoc lynx

1
这个问题特别涉及命令行使用。在编写自己的 Ruby 脚本(或者诸如 Node 服务器之类的东西)之前,请先尝试一下这个方法。 - Cora Middleton
这个在你的终端里可以正常工作。或者,如果你喜欢使用(桌面?)浏览器访问那个文件夹,可以使用 pandoc readme.md -o readme.md.html 命令并打开生成的文件。 - Barry Staes
@baerry-staes 是的,抱歉,希望我的回答清楚地表明了你是我最喜欢的答案。 - Cora Middleton
@JustinMiddleton 是的,我明白了,谢谢。我的评论只是为桌面用户添加一些额外信息...我想有一天某人阅读这个可能会觉得有用。 - Barry Staes
1
我尝试了大约5-6个其他的控制台md阅读器,这绝对是最好的解决方案。我只是在我的配置文件中添加了最基本的功能,使它更快速地使用。function md { pandoc $@ | lynx -stdin } - Russ Brown

24

也许不是你想要的,但是因为你提到了Node.js:在将 GitHub Flavored Markdown 文档提交到 GitHub 之前,我无法找到一款好用的工具来预览本地驱动器上的文档。所以今天我基于 Node.js 创建了一个工具:https://github.com/ypocat/gfms

因此,如果你的问题仍然存在,或许你可以从中重用 showdown.js 用于你的 Wiki。如果不是,那么面临同样问题的其他人(就像我一样)可能会找到这个问题以及对它的回答。


1
干得好,伙计。这让我在编写Node应用程序时不必求助于Ruby或Python,这太棒了。 - user677526

19

8
使用jq命令将README.md文件中的文本读入,并使用Markdown模式,将其保存到JSON格式的对象中。然后使用curl命令将该对象发送到GitHub的Markdown API,并将结果保存到README.html文件中。 - Vebjorn Ljosa
1
@VebjornLjosa 你选择使用 that 还是 grip... 你决定。 :P - yyny
"grip" 真是太棒了。但不幸的是,由于它的名字,如果你忘记它的名称,很难找到它。(在 MacPorts 也不可用)。 - Alexander Kucheryuk

14

使用 marked 。它支持GitHub Flavored Markdown,可以作为Node.js模块和命令行中使用。

一个示例:

$ marked -o hello.html
hello world
^D
$ cat hello.html
<p>hello world</p>

2
我注意到这个不支持代码块的语法高亮和新功能,比如清单。但是它已经完成了大部分工作! - bguiz
非常好,唯一缺少的是一些表格边框。好吧,至少我可以渲染它们,这基本上就是我需要的。在 GFM 中进行管道处理,输出 HTML :) - Xandaros
我对这个例子感到困惑,^D是什么? - Matthew
使用以下命令:marked -o out.html -i in.md --gfm - Gagan

13

我创建了一个类似于Atom预览功能但作为独立应用程序的工具。不确定这是否符合您的要求,但它可能会有所帮助。--https://github.com/yoshuawuyts/vmd

vmd


你们还在支持这个吗?我今天试着用NPM安装,但是失败了。>正在下载electron-v0.36.9-win32-x64.zip
错误:自签名证书。
- kayleeFrye_onDeck
1
是的,我们是!你在哪个版本的npm / node上运行了这个?- 随时在GH上打开一个问题,我们会看一下。谢谢! - Yoshua Wuyts

11

这主要是对 @barry-staes 的答案的继续,用于使用 Pandoc。如果您使用的是 Mac,Homebrew 也有它:

brew install pandoc

Pandoc支持通过markdown_github名称将GFM作为输入格式。

输出到文件

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

Lynx中打开

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

在Mac 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处理器。

首先,创建一个带有以下内容的Shell脚本(我将其称为ghmarkdown):

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

您可以在首选项→变量中设置TM_MARKDOWN变量,将其设置为/path/to/ghmarkdown,这将替换默认的Markdown处理器。


网页内容由stack overflow 提供, 点击上面的
可以查看英文原文,
原文链接