是否有用于呈现 GitHub 风格的 Markdown 的命令行实用程序？

Posted 2023-02-19

【中文标题】是否有用于呈现 GitHub 风格的 Markdown 的命令行实用程序？

【英文标题】：Is there a command line utility for rendering GitHub flavored Markdown?

【发布时间】：2011-12-03 10:32:12

【问题描述】：

我想知道是否有用于获取GitHub flavored Markdown 文件并将其呈现为 html 的命令行实用程序。

我正在使用 GitHub wiki 来创建网站内容。我已经在我的服务器上克隆了存储库，然后想将它处理成常规的 HTML。对我来说重要的是，出现在 GitHub 上的内容正是它应该如何查找我的网站。我也很想使用带有~~~ 的围栏块，所以我宁愿不只使用标准的 Markdown 语法。

我对 javascript 实时预览进行了一些研究，认为我可以将它挂接到 Node.js，但他们说它已被弃用。我查看了 redcarpet 存储库，但它看起来没有命令行界面。

我推出了自己的解决方案，但是，由于这里没有任何解决方案明显比其他解决方案更好，所以我会留下没有选择答案的问题。

【问题讨论】：

RE: 更新：如果我添加了一个 --out 参数来显示 HTML 文件而不是浏览器，这可以接受吗？

@Joe 请添加该选项！

@McLeopold @bguiz 刚刚部署了 --export 选项，它将 GFM 及其样式呈现到单个文件中。这能回答问题吗？

@McLeopold，Joe 通过创建一个简单的可重复使用的解决方案将其从公园中淘汰出局，可能想给他答案。

Github 本身使用 Sundown。见***.com/a/7694931/632951

【参考方案1】：

要在我使用的终端中读取 README.md 文件：

pandoc README.md | lynx -stdin

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

效果很好：它填满了我的终端，快捷方式如下所示，我可以滚动浏览，链接有效！ 虽然只有一种字体大小，但颜色+缩进+对齐弥补了这一点。

安装：

apt：sudo apt-get install pandoc lynx 尼克斯：nix-shell -p pandoc lynx

【讨论】：

这个问题是关于命令行使用的。在编写自己的 ruby​​ 脚本（或 egad 节点服务器）之前，先试一试。

这在您的终端中确实有效。或者，如果您最喜欢的（桌面？）浏览器可以访问该文件夹，请使用 pandoc readme.md -o readme.md.html 并打开生成的文件。

@baerry-staes 是的，对不起，我希望你的答案是我最喜欢的答案。

@JustinMiddleton 是的，我明白了，谢谢。我的评论只是为桌面用户添加一些额外的信息。我想有一天有人阅读这篇文章可能会发现它很有用。

我已经尝试了大约 5-6 个其他控制台 md 阅读器，这是迄今为止最好的解决方案。我只是在我的配置中添加了最基本的功能，以使其使用起来更快一些。 function md pandoc $@ | lynx -stdin

【参考方案2】：

另一个选项是AllMark - markdown 服务器。 Docker 映像可用于即用型设置。

$ allmark serve .

注意：它递归地扫描目录以从降价文件中为网站提供服务。因此，为了更快地处理单个文件，请将其移至单独的目录。

【参考方案3】：

我将 Pandoc 与 --from=gfm 选项一起用于 GitHub Flavored Markdown，如下所示：

$ pandoc my_file.md   --from=gfm -t html -o my_file.html

【讨论】：

在 linux mint 18 上使用 pandoc 1.16.0.2 我得到一个错误：pandoc: Unknown reader: gfm。转到 2.2.1 可以解决此问题。

我用 Pandoc 2.1.2 测试过。

如何在ubuntu上安装2.2.1？

@AlexanderMills 你试过sudo apt install pandoc 吗？

【参考方案4】：

在this comment 的基础上，我写了一个单行来使用curl 和jq 来访问Github Markdown API。

将此 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"。

【参考方案5】：

我还没有为 GitHub 风格的 Markdown 找到快速简便的方法，但我找到了一个更通用的版本 - Pandoc。它可以转换成多种格式，包括 Markdown、Rest、HTML 等。

我还开发了一个Makefile 来将所有 .md 文件转换为 .html（主要是 Writing, Markdown and 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 $@

【讨论】：

我一直在使用“watch pandoc ...”将markdown文件不断转换为html，并使用chrome“live reload”扩展来获得实时“留在我滚动的地方”具有此功能，并且效果很好。 chrome.google.com/webstore/detail/livereload/…

Pandoc 可以很好地读取 GFM，但它不会生成与 GitHub 相同的 HTML —— 例如，如果您的 GFM 源代码中有一个多行 <pre/> 标签，Pandoc 将放置 <br/>标签用于换行，而 GitHub 的渲染器虽然去除了前导空格，但似乎不理会内容。

如何在生成的 HTML 上获得漂亮的样式？例如，我的输出仍然使用 Times New Roman 渲染。

Pandoc 安装说明为here。在 macOS 上：brew install pandoc

gfm 和 markdown_github 输入格式都不能正确呈现代码块之类的内容。

【参考方案6】：

为此，我设法使用了一个单行 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 没有帮助，这似乎在这个答案上失败了。

【讨论】：

我认为这是他们所有人的“最接近来源”的答案，因为这些工具是 github 使用的。

【参考方案7】：

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

它不处理 GitHub 扩展，但总比没有好。我相信你可以扩展模块来处理 GitHub 的添加。

【讨论】：

/usr/bin/python:markdown是一个包，不能直接执行

简单的 HTML 输出，没有花哨的标签。

严格来说，这是“John Gruber 的 Markdown”，而不是 GitHub 风格的 Markdown。

【参考方案8】：

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

【讨论】：

你们还支持这个吗？我今天尝试使用 NPM 安装，但没有骰子。 >下载 electron-v0.36.9-win32-x64.zip >错误：自签名证书

是的，我们是！您在哪个版本的 npm / node 上运行它？ - 随时在 GH 上提出问题，我们会看看这个。谢谢！

【参考方案9】：

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

【讨论】：

apt-get isntall pandoc 可以，不需要使用像 brew 这样不安全的本地东西。

@DominikGeorge 有一个错字，是 install，而不是 isntall

@DominikGeorge macOS 上没有 apt-get。

【参考方案10】：

后期添加，但showdownjs 有一个 CLI 工具，可用于将 MD 解析为 HTML。

【参考方案11】：

可能不是你想要的，但既然你提到了 Node.js：在将 GitHub Flavored Markdown 文档提交到 GitHub 之前，我找不到一个好的工具来预览本地驱动器上的 GitHub Flavored Markdown 文档，所以今天我创建了一个基于 Node.js 的工具。 js:https://github.com/ypocat/gfms

因此，如果您的问题仍然是实际的，也许您可​​以将其中的 showdown.js 重用于您的 Wiki。如果没有，也许与我面临同样问题的其他人会（就像我一样）找到这个问题和这个答案。

【讨论】：

干得好，伙计。让我在编写节点应用程序时不必求助于 Ruby 或 Python，这很棒。

【参考方案12】：

“快速而简单”的方法是使用 wget 实用程序下载 wiki HTML 页面，而不是克隆它。例如，这是我从 GitHub 下载 Hystrix wiki 的方式（我使用的是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

第一次调用将下载 wiki 入口页面及其所有依赖项。第二个将调用它上面的所有子页面。您现在可以打开 Netflix/Hystrix/wiki.1.html 浏览 wiki。

请注意，对wget 的两次调用都是必需的。如果您只运行第二个，那么您将错过一些正确显示页面所需的依赖项。

【参考方案13】：

这主要是对@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

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

【参考方案14】：

GitHub（此后）开发了一个很好的模块化文本编辑器，名为 Atom（基于 Chromium 并使用 Node.js 模块进行包）。

默认的预安装包Markdown Preview 允许您使用 Ctrl + Shift + M 在单独的选项卡中显示预览。

我还没有测试过它的完整语法，但由于它来自 GitHub，如果预览版的语法与他们的不同（使用~~~ 工作的隔离块），我会感到非常惊讶。

现在，虽然它在技术上不是基于命令行的，但它使用 Node.js 并输出到基于 DOM 的渲染器，这可能有助于任何尝试在基于 Node.js 的网络服务器上渲染基于 GitHub 语法的 HTML ，或者只是离线编辑她/他的 README.md。

【讨论】：

在 Atom 中，您可以安装一个名为 gfm-pdf (atom.io/packages/gfm-pdf) 的包，它将您的 markdown 文档导出为 HTML 和/或 PDF 文档。 wkhtmltopdf 库是必需的。

【参考方案15】：

GitHub 有 a Markdown API 你可以使用。

【讨论】：

jq --slurp --raw-input '"text": "\(.)", "mode": "markdown"' < README.md | curl --data @- https://api.github.com/markdown > README.html

@VebjornLjosa * that * 或 grip... 你选择了。 :P

grip 太棒了。但是，不幸的是，由于它的名称，如果您忘记了它的命名方式，就不可能轻易找到它。 （也不能通过 MacPorts 获得）。

【参考方案16】：

有一个非常好的和简单的工具来浏览 GFM Markdown 文档：

GFMS - Github Flavored Markdown Server

它简单轻量（无需配置）HTTP 服务器，您可以在任何包含 Markdown 文件的目录中启动以浏览它们。

特点：

完整的 GFM Markdown 支持 源代码语法高亮 浏览文件和目录 漂亮的输出（和可配置的 CSS 样式表） 导出为 PDF

【参考方案17】：

基于Jim Lim's answer，我安装了 GitHub Markdown gem。其中包括一个名为 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)

【讨论】：

我用 Ruby 和 Cucumber 的围栏块尝试了这个。虽然栅栏（ruby, cucumber 等）似乎被识别为栅栏（因为它们以固定宽度的文本呈现），但没有语法突出显示。知道为什么吗？

【参考方案18】：

我最近做了你想要的，因为我需要从 Markdown 文件生成文档，而且 GitHub 风格非常好。试试吧。它是用 Node.js 编写的。

gfm

【讨论】：

我知道，模块已经 9 个月没有更新了，你为什么要对旧帖子投反对票？

【参考方案19】：

我用 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 读取并导出到stdout在 3.0 中添加

希望这可以帮助这里的人。 Check it out.

【讨论】：

工作得非常好，对于 Pythonistas 来说，安装的简易性是无与伦比的！

这应该是“github markdown preview”的首选。其他一切都很复杂，不起作用，或者没有完成所有 GitHub 功能。 grip 开箱即用。

@Houdini 这个问题已经过时了。 Flask 确实支持 3.3，请参阅 flask.pocoo.org/docs/python3。这是关于 github.com/mitsuhiko/flask/issues/587 主题的最新 Github 主题。如果还有其他依赖项需要更新，请随时打开问题或拉取请求。

如果你每小时刷新超过 60 次，这个包需要有效的互联网连接和你的 github 身份验证凭据（在命令行中提供）。

如前所述，我不认为这是一个特别好的解决方案，因为它所做的所有事情都会转到 Github 并让 Github 呈现您的 Markdown。它需要一个可以访问 Github 的有效互联网连接，如果 Github 死了，那么这个工具就会停止工作。我宁愿有一个完全离线的解决方案。

【参考方案20】：

使用marked。它支持 GitHub Flavored Markdown，可以作为 Node.js 模块使用，也可以从命令行使用。

一个例子是：

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

【讨论】：

我注意到它不支持代码块的语法突出显示等功能和清单等新功能。但是，嘿，它得到了大部分的方式！

非常好，我唯一缺少的是表格的一些边框。好吧，至少我可以渲染它们，这正是我所需要的。管道在 GFM 中，管道输出 HTML :)

我对这个例子感到困惑，^D 是什么？

【参考方案21】：

我的最终解决方案是使用Python Markdown。我滚动了my ownextension，修复了栅栏块。

【参考方案22】：

我找到了一个可以为您执行此操作的网站：http://tmpvar.com/markdown.html。粘贴到您的 Markdown 中，它会为您显示它。它似乎工作得很好！

但是，它似乎没有处理代码的语法高亮选项；也就是说，~~~ruby 功能不起作用。它只是打印'ruby'。

【讨论】：

tmpvar 似乎不像表格那样做 GFM 版本增强

【参考方案23】：

为 elinks 的普通用户改进 @barry-stae 和 @Sandeep 的答案，您可以在 .bashrc 中添加以下内容：

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

别忘了安装 pandoc（和 elinks）。

【参考方案24】：

另见https://softwareengineering.stackexchange.com/a/128721/24257。

---

如果您对我们 [Github] 如何渲染 Markdown 文件感兴趣，您可能想查看Redcarpet，这是我们与 Sundown 库的 Ruby 接口。

使用Redcarpet 的Ruby-script 将是“命令行实用程序”，如果你有本地Ruby

【讨论】：

没有想法 - 我不写 Ruby，也没有阅读 Redcarpet 资源

@LazyBadger, Sundown 是实际的解析器（用 C 编写）。不需要红地毯。

这可以说是最好的解决方案，但您并没有给出具体的操作说明。所以在安装了 gem gem install redcarpet 之后，假设我们在一个包含 README.md 的目录中，接下来呢？

【参考方案25】：

改进@barry-stae 的解决方案。把这个 sn-p 放到 ~/.bashrc

function mdviewer()
  pandoc $* | lynx -stdin

然后我们可以从命令行快速查看文件。也可以通过 SSH/Telnet 会话很好地工作。

mdviewer README.md

【参考方案26】：

也许这会有所帮助：

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 执行它。请注意，如果不进行消毒，这在生产中使用是不安全的。

【讨论】：

谢谢吉姆，由于几乎不存在的例子，我被困在了要求步骤（用斜杠替换破折号）.. ;)

如果您已经在使用 NPM，那就太好了。我不得不使用它，因为 DOxygen 给我带来了特别是 github 风格的降价 + 导出到 HTML 的问题。

这是在本地运行还是将数据发送到 GitHub API？