在提交到 github 之前，如何测试我的 readme.md 文件的外观？

Posted

技术标签:

【中文标题】在提交到 github 之前，如何测试我的 readme.md 文件的外观？【英文标题】：How can I test what my readme.md file will look like before committing to github? 【发布时间】：2012-03-09 00:45:41 【问题描述】：

我正在为我的 github 项目编写 .md 格式的自述文件。有没有办法在提交到 github 之前测试我的 readme.md 文件的外观？

【问题讨论】：

我作为评论来回答这个问题，因为线程已关闭，并且没有任何解决方案以与 github 相同的方式呈现管道表。似乎最接近的网络解决方案在这里：pandao.github.io/editor.md/en.html 使用 GitLab 13.0（2020 年 5 月），GitLab 的静态站点编辑器具有所见即所得的编辑器。见my answer below。 自 2021 年 11 月起，您还可以使用 GitHub Gist 的新 preview 功能来查看您的 Markdown 会是什么样子 在添加、提交和推送副本到您的本地存储库（并推送到您的 GitHub README.md）之前。见my answer below。 确保您使用的是README .md 而不是README**.rst** 用于**StackEdit*8 【参考方案1】：

多种方式：如果您使用的是 Mac，请使用 Mou。

如果您想在浏览器中进行测试，您可以尝试StackEdit，正如@Aaron 或Dillinger 所指出的，因为Notepag 现在似乎已关闭。我个人使用 Dillinger，因为它可以正常工作并将我的所有文档保存在浏览器的本地数据库中。

【讨论】：

dillinger.io 现在似乎也下降了，虽然它仍然是您在谷歌“markdown online viewer”时列出的第一个，所以它可能只是我。我成功使用stackedit.io 预览和编辑了我的readme.md。 Dillinger 没问题。大部分时间都还好。 StackEdit 是一个很棒的工具。谢谢！ StackEdit 格式化“定义列表”，github 没有。 StackEdit 将三个反引号代码块放在自己的行上（用于编号列表），github 没有。还有其他区别。唯一安全的赌注是反复试验一个要点并在完成后将其删除。 不幸的是，Mou 似乎不支持 MacOS Mojave (10.14)【参考方案2】：

Atom 开箱即用 - 只需打开 Markdown 文件并按 Ctrl+Shift+M 即可切换旁边的 Markdown 预览面板。它还处理 HTML 和图像。

【讨论】：

因为我有本地资源，比如应用程序的截图，所以这个解决方案效果最好。谢谢！ 我已经使用 atom 一年了，没想到它可以做到这一点！带出耻辱修女...... brew cask install atom perfs 已经安装了 Atom 只需键入 atom . 并右键单击自述文件 > Markdown Preview Ctrl+Shift+M 由于某种原因对我不起作用。必须打开命令面板（Ctrl+Shift+P）并从那里选择降价预览。谢谢！【参考方案3】：

Visual Studio Code 具有编辑和预览 md 文件更改的选项。由于 VS Code 独立于平台，因此适用于 Windows、Mac 和 Linux。

要在视图之间切换，请在编辑器中按 Ctrl+Shift+V。您可以与正在编辑的文件并排查看预览(Ctrl+K V)，并在您编辑时实时查看更改。

还有……

问：VS Code 是否支持 GitHub Flavored Markdown？

答：不，VS Code 使用 markdown-it 库针对 CommonMark Markdown 规范。 GitHub 正在朝着 CommonMark 规范发展。

预览按钮是这样的：

More details here

【讨论】：

很好！！我不必安装atom！！ 对了，我想测试一下GitHub（***.com/a/45860695/5362795）使用的title的链接，发现VS Code也支持！【参考方案4】：

这是一个相当古老的问题，但是由于我在搜索互联网时偶然发现了它，所以我的答案可能对其他人有用。 我刚刚发现了一个非常有用的 CLI 工具，用于渲染 GitHub 风格的 markdown：grip。它使用 GitHub 的 API，因此渲染效果很好。

坦率地说，grip 的开发者对这些非常相似的问题有更详尽的回答：

Is there a command line utility for rendering github flavored markdown? What's the best way to edit GitHub's Readme.md?

【讨论】：

谢谢！很高兴不必中断我的工作流程并打开其他编辑器或访问其他网站 这应该是公认的答案——完美！只需在编辑器和浏览器之间使用 alt-tab，它就会自动重新渲染 markdown，它看起来和 GitHub 上的完全一样。最后是一个可以接受的解决方案。【参考方案5】：

这个已经被证明是可靠的很长一段时间了：http://tmpvar.com/markdown.html

【讨论】：

这是一个良好的开端，但后来这个没有显示水平规则......在进一步测试之前被放弃了。 很高兴快速检查。【参考方案6】：

我一般直接在 GitHub 网站上编辑，然后点击编辑窗口上方的“预览”即可。

也许这是自发布此帖子以来添加的新功能。

【讨论】：

此解决方案的问题是 GitHub（到目前为止）显示了更改的内联差异，如果您想了解更改的外观而不是实际更改的内容，则预览非常不可用. @B12Toaster 您可以使用 GitHub 网站在存储库上创建一个新文件（无需保存）并将其命名为 xxx.md 并将您的代码粘贴到那里。文件扩展名为.md，因此您可以预览您的更改。您将更新您完成的 util，然后复制文件内容并将其粘贴到原始 readme.md 文件上。 另一个问题是它不能准确地显示所有内容。一个具体的例子：如果您使用<div align='center'><img ...></div> 将图像居中放在顶部，则它不会在预览中显示居中，而是左对齐。你必须保存它才能准确地看到它，这使得我认为预览不可信。【参考方案7】：

在网络中，使用Dillinger。太棒了。

【讨论】：

【参考方案8】：

我使用本地托管的 HTML 文件来预览 GitHub 自述文件。

我查看了几个现有选项，但决定推出自己的选项以满足以下要求：

单个文件 本地托管（Intranet）网址 无需浏览器扩展 没有本地托管的服务器端处理（例如，没有 php） 轻量级（例如，没有 jQuery） 高保真：使用 GitHub 渲染 Markdown，和相同的 CSS

我将 GitHub 存储库的本地副本保存在“github”目录下的同级目录中。

每个 repo 目录都包含一个 README.md 文件：

.../github/
           repo-a/
                  README.md
           repo-b/
                  README.md
           etc.

github 目录包含“预览”HTML 文件：

.../github/
           readme.html

要预览自述文件​​，我浏览 github/readme.html，在查询字符串中指定 repo：

http://localhost/github/readme.html?repo-a

或者，您可以将 readme.html 复制到与 README.md 相同的目录中，并省略查询字符串：

http://localhost/github/repo-a/readme.html

如果 readme.html 与 README.md 位于同一目录中，您甚至不需要通过 HTTP 提供 readme.html：您可以直接从文件系统中打开它。

HTML 文件使用GitHub API 在 README.md 文件中呈现 Markdown。有一个rate limit：在撰写本文时，每小时 60 个请求。

在 Windows 7 上的 Chrome、IE 和 Firefox 的当前生产版本中为我工作。

来源

这是 HTML 文件 (readme.html)：

<!DOCTYPE html>
<!--
     Preview a GitHub README.md.

     Either:

     -  Copy this file to a directory that contains repo directories,
        and then specify a repo name in the query string.

        For example:

          http://localhost/github/readme.html?myrepo

     or

     -  Copy this file to the directory that contains a README.md,
        and then browse to this file without specifying a query string.

        For example:

          http://localhost/github/myrepo/readme.html

        (or just open this file in your browser directly from
        your file system, without HTTP)
-->
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=Edge"/>
<meta name="author" content="Graham Hannington"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>GitHub readme preview</title>
<link rel="stylesheet" type="text/css" href="http://primercss.io/docs.css"/>
<script type="text/javascript">
//<![CDATA[
var HTTP_STATUS_OK = 200;
var URL_API_GITHUB_RENDER_MARKDOWN = "https://api.github.com/markdown/raw";
var README_FILE_NAME = "README.md";

var readmeURL;

var queryString = location.search.substring(1);

if (queryString.length > 0) 
  readmeURL = queryString + "/" + README_FILE_NAME;
 else 
  readmeURL = README_FILE_NAME;


// Get Markdown, then render it as HTML
function getThenRenderMarkdown(markdownURL) 
  var xhr = new XMLHttpRequest();
  xhr.open("GET", markdownURL, true);
  xhr.responseType = "text";
  xhr.onload = function(e) 
    if (this.status == HTTP_STATUS_OK) 
     // Response text contains Markdown
      renderMarkdown(this.responseText);
    
  
  xhr.send();


// Use the GitHub API to render Markdown as HTML
function renderMarkdown(markdown) 
  var xhr = new XMLHttpRequest();
  xhr.open("POST", URL_API_GITHUB_RENDER_MARKDOWN, true);
  xhr.responseType = "html";
  xhr.onload = function(e) 
    if (this.status == HTTP_STATUS_OK) 
      document.getElementById("readme").innerHTML = this.response;
    
  
  xhr.send(markdown);


window.onload = function() 
  getThenRenderMarkdown(readmeURL);

//]]>
</script>
</head>
<body>
<header class="masthead">
<div class="container">
<span class="masthead-logo"><span class="mega-octicon
octicon-mark-github"></span>GitHub readme preview</span>
</div>
</header>
<div class="container">
<div id="readme" class="markdown-body">
<p>Rendering markdown, please wait...</p>
</div>
<footer class="footer">Rendering by
<a href="https://developer.github.com/v3/markdown/">GitHub</a>,
styling by <a href="http://primercss.io/">Primer</a>.</footer>
</div>
</body>
</html>

开发者说明

通常，我将代码包装在 IIFE 中，但在这种情况下，我没有看到需要，并认为我会保持简洁 我没有费心支持低级 IE 为简洁起见，我省略了错误处理代码（你相信我吗？！） 欢迎 JavaScript 编程技巧

想法

我正在考虑为这个 HTML 文件创建一个 GitHub 存储库，并将该文件放在 gh-pages 分支中，以便 GitHub 将其作为“普通”网页提供服务。我会调整文件以接受自述文件（或任何其他 Markdown 文件）的完整 URL 作为查询字符串。我很想知道由 GitHub 托管是否会回避 GitHub API 请求限制，以及我是否遇到了跨域问题（使用 Ajax 请求从与提供 HTML 页面的域不同的域获取 Markdown） .

原始版本（已弃用）

出于好奇，我保留了原始版本的记录。 此版本存在以下问题，当前版本已解决：

需要下载一些相关文件 不支持放入与 README.md 相同的目录 它的 HTML 更脆弱；更容易受到 GitHub 变化的影响

github 目录包含“预览”HTML 文件和相关文件：

.../github/
           readme-preview.html
           github.css
           github2.css
           octicons.eot
           octicons.svg
           octicons.woff

我从 GitHub 下载了 CSS 和 octacons 字体文件：

https://assets-cdn.github.com/assets/github- ... .css
https://assets-cdn.github.com/assets/github2- ... .css
https://github.com/static/fonts/octicons/octicons.* (eot, woff, svg)

我重命名了 CSS 文件以省略原始名称中的长十六进制数字字符串。

我编辑了 github.css 以引用 occticons 字体文件的本地副本。

我检查了 GitHub 页面的 HTML，并复制了足够多的围绕自述文件内容的 HTML 结构，以提供合理的保真度；例如，约束的宽度。

用于自述内容的 GitHub CSS、occticons 字体和 HTML“容器”正在移动目标：我需要定期下载新版本。

我喜欢使用来自各种 GitHub 项目的 CSS。例如：

<link rel="stylesheet" type="text/css"
      href="http://rawgit.com/sindresorhus/github-markdown-css/gh-pages/github-markdown.css">

但最终决定使用 GitHub 本身的 CSS。

来源

这是 HTML 文件 (readme-preview.html)：

<!DOCTYPE html>
<!-- Preview a GitHub README.md.
     Copy this file to a directory that contains repo directories.
     Specify a repo name in the query string. For example:

     http://localhost/github/readme-preview.html?myrepo
-->
<html>
<head>
<title>Preview GitHub readme</title>
<meta http-equiv="X-UA-Compatible" content="IE=Edge"/>
<meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
<!-- Downloaded copies of the CSS files served by GitHub.
     In github.css, the @font-face for font-family:'octicons'
     has been edited to refer to local copies of the font files -->
<link rel="stylesheet" type="text/css" href="github.css"/>
<link rel="stylesheet" type="text/css" href="github2.css"/>
<style>
body 
  margin-top: 1em;

</style>
<script type="text/javascript">
//<![CDATA[
var HTTP_STATUS_OK = 200;
var URL_API_GITHUB_RENDER_MARKDOWN = "https://api.github.com/markdown/raw";
var README_FILE_NAME = "README.md";

var repo = location.search.substring(1);

// Get Markdown, then render it as HTML
function getThenRenderMarkdown() 
  var xhr = new XMLHttpRequest();
  xhr.open("GET", repo + "/" + README_FILE_NAME, true);
  xhr.responseType = "text";
  xhr.onload = function(e) 
    if (this.status == HTTP_STATUS_OK) 
     // Response text contains Markdown
      renderMarkdown(this.responseText);
    
  
  xhr.send();


// Use the GitHub API to render Markdown as HTML
function renderMarkdown(markdown) 
  var xhr = new XMLHttpRequest();
  xhr.open("POST", URL_API_GITHUB_RENDER_MARKDOWN, true);
  xhr.responseType = "html";
  xhr.onload = function(e) 
    if (this.status == HTTP_STATUS_OK) 
      document.getElementById("readme-content").innerHTML = this.response;
    
  
  xhr.send(markdown);


window.onload = getThenRenderMarkdown;
//]]>
</script>
</head>
<body>
<!-- The following HTML structure was copied from live GitHub page on 2015-12-01,
     except for the "readme-content" id of the article element,
     which was coined for this preview page.-->
<div class="main-content" role="main">
<div class="container repo-container new-discussion-timeline experiment-repo-nav">
<div class="repository-content">
<div id="readme" class="boxed-group flush clearfix announce instapaper_body md">
<h3><span class="octicon octicon-book"></span>README.md</h3>
<article class="markdown-body entry-content"
         itemprop="mainContentOfPage"
         id="readme-content"><p>Rendering markdown...</p></article>
</div>
</div>
</div>
</div>
</body>
</html>

【讨论】：

【参考方案9】：

适用于 Visual Studio 用户（不是 VS CODE）。

安装 Markdown Editor 扩展

这样，当您打开 README.md 时，您将在右侧看到实时预览。

【讨论】：

【参考方案10】：

你可能想看看这个：

https://github.com/kristjanjansen/md2html

【讨论】：

【参考方案11】：

Github或Bitbucket主题，可以使用在线编辑器ma​​ttstow，url：http://writeme.mattstow.com

【讨论】：

【参考方案12】：

只要在网上搜索就可以得到很多结果： https://stackedit.io/

【讨论】：

【参考方案13】：

SublimeText 2/3

安装包：Markdown Preview

选项：

在浏览器中预览。 导出为 html。 复制到剪贴板。

【讨论】：

这很好用，因为它支持 github、gitlab 和通用 markdown。虽然很难安装。【参考方案14】：

Markdown​Preview，之前评论中提到的Sublime Text插件不再兼容ST2，只支持Sublime Text 3（2018年春季起） .

它的优点是：它支持 GFM，GitHub Flavored Markdown，它可以比普通的 Markdown 做更多的事情。如果你想知道你的.mds 在 GH 上的样子，这很重要。 （包括这一点信息，因为OP自己没有添加GFM标签，其他寻找解决方案的人可能也不知道。）

如果您在线，您可以将它与 GitHub API 一起使用，但您应该为此目的获得 personal access token，因为未经身份验证的 API 调用受到限制。在插件的文档中有更多关于 Parsing GFM 的信息。

【讨论】：

【参考方案15】：

我正在使用 markdownlivepreview：https://markdownlivepreview.com/

这非常容易、简单和快速。

【讨论】：

【参考方案16】：

如果您使用的是 Pycharm（或其他 Jetbrains IDE，例如 Intellij、RubyMine、PHPStorm 等），您的 IDE 中有多个免费插件支持 Markdown，允许在编辑时进行实时预览。 Markdown Navigator 插件非常好。如果您在 IDE 中打开 .md 文件，最新版本将提供安装支持插件并显示列表。

【讨论】：

对于最新的 Pycharm，它似乎支持开箱即用（无需插件）。 正确 - 它现在已内置到 pycharm 中。【参考方案17】：

使用Jupyter Lab。

要安装 Jupyter Lab，请在您的环境中键入以下内容：

pip install jupyterlab

安装完成后，浏览到你的 Markdown 文件所在的位置，右键单击该文件，选择“打开方式”，然后单击“Markdown 预览”。

【讨论】：

【参考方案18】：

对于 Visual Studio Code，我使用

Markdown 预览增强扩展。

【讨论】：

【参考方案19】：

我知道这个问题很老了，也许有人在谷歌上搜索如何到达这里。 反正我就是这么看这个问题的。

即使在 github 样式中，您也可以使用 atom 文本编辑器和切换 markdown 预览。

按下

ctrl+shift+m

会弹出窗口或使用Packages-->Markdown Preview.

希望这对某人有所帮助。

【讨论】：

【参考方案20】：

一种方法是使用Pandoc（非常有用）。

    将您的 Markdown 纯文本复制到剪贴板

    运行：

    xsel -b | pandoc -s -f markdown -t html | xclip -selection clipboard -t text/html | xsel -b

    粘贴生成的格式化文本（例如在电子邮件或 LibreOffice 上）。

你说你是using Linux。您只需要安装 pandoc、xsel 和 xclip 包。

【讨论】：

【参考方案21】：

自 2012 年以来（创建此问题时）GitHub 本身可以：

在常规存储库中创建并显示 Markdown 文档的预览（它总是这样做，since Aug. 2011） 或者，如果您不想直接影响您的存储库，请对 gist (since Dec. 2020) 执行相同操作 即使没有提交要点，您也可以从 2021 年 11 月起预览您正在编辑（但尚未提交）的Markdown document in a Gist

一旦该 gist 的预览看起来不错，您可以将 markdown 从该 gist 复制到您的本地 README.md，添加、提交和推送。

【讨论】：

【参考方案22】：

MarkdownViewerPlusPlus 是一个“[...]Notepad++ 插件，用于查看即时呈现的 Markdown 文件 特点

具有当前选定文件/选项卡的呈现 HTML 的可停靠面板（切换） 符合 CommonMark (0.28) 同步滚动 自定义 CSS 集成 HTML 和 PDF 导出 记事本++ Unicode 插件 [...]”

【讨论】：

【参考方案23】：

我发现markdownlivepreview.com 非常接近原版 GitLab 降价。 其他查看者对命令的解释与 GitLab 略有不同。

【讨论】：

【参考方案24】：

我只是创建一个“功能”分支并将其推送到我进行更改的 github，这些更改将在 github 中完全可见。

然后，当我满意时，我会变基回到 main 或向 main 发出拉取请求，无论您碰巧使用的是哪个进程。

在使用 git 时，您很少需要在本地进行测试，除非您的存储库位于公司防火墙之后，或者需要离线工作。

在这种情况下，Atom 和 VScode 都有不错的 Markdown 渲染器，不足以显示您的更改在 github 上的外观，但足以查看您的更改是否朝着正确的方向发展。

【讨论】：

【参考方案25】：

您可以使用static site editor: 和GitLab 13.0 (May 2020)，它带有一个所见即所得的面板。

所见即所得的静态站点编辑器

Markdown 是一种用于创作 Web 内容的强大且高效的语法，但即使是经验丰富的 Markdown 内容作者也可能难以记住一些不常用的格式选项，或者从头开始编写中等复杂的表格。 使用富文本“所见即所得”(WYSIWYG) 编辑器可以更好地完成一些工作。

GitLab 13.0 为静态站点编辑器带来了所见即所得的 Markdown 创作体验，并提供了常见格式选项的格式选项，例如标题、粗体、斜体、链接、列表、块引用和代码块。

WYSIWYG 编辑器还可以让您以与编辑电子表格相同的方式直观地编辑表格行、列和单元格，从而消除了在 Markdown 中编辑表格的繁重任务。对于那些更喜欢用原始 Markdown 编写的人来说，甚至还有一个选项卡可以在所见即所得和纯文本编辑模式之间切换。

请参阅 documentation 和 issue。

同样，您只会使用它来编写您的 README：一旦它看起来不错，您可以将其报告回您的原始项目。 但重点是：您不再需要任何第三方 Markdown 预览插件。

还有GitLab 14.2（2021 年 8 月）

编辑时实时预览 Markdown

Markdown 是一种用于编写丰富的 Web 内容的快速且直观的语法。直到不是。 幸运的是，从 Preview 选项卡可以轻松预览 Markdown 的渲染输出，以确保标记的准确性。

不幸的是，在原始源代码和预览之间移动所需的上下文切换可能会很乏味并且会破坏您的流程。

现在，在 Web IDE 和单个文件编辑器中，Markdown 文件都有一个新的实时预览选项可用。右键单击编辑器并选择 Preview Markdown 或使用 Command/Control + Shift + P 切换 Markdown 内容的分屏实时预览。 预览会在您键入时刷新，因此您可以确信您的标记是有效的并且会按照您的预期呈现。

请参阅 Documentation 和 Epic。

见GitLab 14.6（2021 年 12 月）

无缝切换 wiki 编辑器

无缝切换 wiki 编辑器

使用新的丰富的 Markdown 编辑器编辑 wiki 页面使每个人都可以更轻松地做出贡献，无论他们对 Markdown 语法的了解程度如何。 在某些情况下，您可能还更喜欢编写原始 Markdown，但使用 WYSIWYG 界面来完成更复杂或繁琐的格式化任务，例如创建表格。

以前版本的 GitLab 要求您在丰富的 Markdown 编辑器和 Markdown 源之间切换之前保存更改，从而为您的编辑添加更多步骤和摩擦。

在 GitLab 14.6 中，您现在可以在两种编辑体验之间无缝切换，无需提交更改，随时选择适合您需求的编辑器。

请参阅 Documentation 和 Issue。

【讨论】：

【参考方案26】：

对于那些希望在 iPad 上进行开发的人，我喜欢 Textastic。从云端下载文档后，您可以在没有互联网连接的情况下编辑和预览 README.md 文件。

【讨论】：

以上是关于在提交到 github 之前，如何测试我的 readme.md 文件的外观？的主要内容，如果未能解决你的问题，请参考以下文章

github上测试服出现bug，如何回滚并获得合并之前的分支

如何在 GitHub Action 工作流程中推送或合并之前获取上一个提交？

如何区分 GitHub 中的两个分支？

提交时从 git 拉取到网站

如何根据提交 ID 在 GitHub 上发布项目？

如何将Android Studio项目提交（更新）到github