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

Question

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

score 176 · Accepted Answer

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

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

score 103 · Accepted Answer

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

score 58 · Accepted Answer

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

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

还...

问：VS Code 是否支持 GitHub 风格的 Markdown？

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

预览按钮是这样的：

更多细节在这里

score 45 · Accepted Answer

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

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

score 37 · Accepted Answer

37

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

于 2012-11-11T01:21:09.697 回答

score 34 · Accepted Answer

我通常只是直接在 GitHub 网站上编辑它，然后单击编辑窗口上方的“预览”。

也许这是自从发表这篇文章以来添加的一项新功能。

score 7 · Accepted Answer

7

在网络中，使用Dillinger。这很棒。

于 2015-01-12T23:56:35.980 回答

score 5 · Accepted Answer

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

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

单个文件
本地托管（Intranet）URL
无需浏览器扩展
没有本地托管的服务器端处理（例如，没有 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。有一个速率限制：在撰写本文时，每小时 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>

score 4 · Accepted Answer

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

安装Markdown 编辑器扩展

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

score 3 · Accepted Answer

3

你可能想看看这个：

https://github.com/kristjanjansen/md2html

于 2012-07-03T10:38:46.500 回答

score 3 · Accepted Answer

对于Github或Bitbucket主题，可以使用在线编辑器mattstow，网址：http ://writeme.mattstow.com

score 2 · Accepted Answer

崇高文本 2/3

安装包：Markdown Preview

选项：

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

score 2 · Accepted Answer

MarkdownPreview ，之前评论中提到的Sublime Text的插件已经不再兼容 ST2，只支持Sublime Text 3（从 2018 年春季开始）。

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

如果您在线，您可以将它与 GitHub API 一起使用，但您应该为此目的获得一个个人访问令牌，因为未经身份验证的 API 调用是有限的。在插件的文档中有更多关于Parsing GFM的信息。

score 2 · Accepted Answer

2

只需在网上搜索就可以得到许多继承人： https ://stackedit.io/

于 2015-10-09T18:09:09.070 回答

score 2 · Accepted Answer

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

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

score 1 · Accepted Answer

1

对于 Visual Studio Code，我使用

Markdown 预览增强扩展。

于 2018-07-07T11:50:16.657 回答

score 1 · Accepted Answer

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

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

跑：

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

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

你说你正在使用 Linux。你只需要安装 pandoc、xsel 和 xclip 包。

score 1 · Accepted Answer

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

在常规存储库中创建并显示 Markdown 文档的预览（自 2011 年 8 月以来一直如此）
或者，如果您不想直接影响您的存储库，请对gist执行相同操作（自 2020 年 12 月起）
即使没有提交 gist，您也可以从 2021 年 11 月起在您正在编辑的 Gist 中预览 Markdown 文档（但尚未提交）

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

score 1 · Accepted Answer

使用Jupyter 实验室。

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

pip install jupyterlab

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

score 1 · Accepted Answer

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

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

按

ctrl+shift+m

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

希望这可以帮助某人。

score 1 · Accepted Answer

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

score 0 · Accepted Answer

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

score 0 · Accepted Answer

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

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

score 0 · Accepted Answer

您可以使用静态站点编辑器：使用GitLab 13.0（2020 年 5 月），它带有一个所见即所得的面板。

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

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

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

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

请参阅文档和问题。

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

以及GitLab 14.2（2021 年 8 月）

编辑时实时预览 Markdown

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

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

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

请参阅文档和史诗。

见GitLab 14.6（2021 年 12 月）

无缝切换 wiki 编辑器

无缝切换 wiki 编辑器

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

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

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

请参阅文档和问题。

score 0 · Accepted Answer

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

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

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

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

score -1 · Accepted Answer

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

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

26 回答 26

资源

开发人员说明

想法

原始版本（已弃用）

资源

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

编辑时实时预览 Markdown

无缝切换 wiki 编辑器

Related

Reference