我正在以.md格式为我的Github项目编写自述文件。有没有办法在提交到Github之前测试我的readme.md文件的外观呢？
28个回答
189
- three
8
5尽管在谷歌搜索“markdown在线查看器”时dillinger.io仍然是第一个显示的，但它似乎现在也无法使用，所以可能只是我遇到了这个问题。我成功地使用https://stackedit.io/来预览和编辑我的readme.md。 - Aaron
1Dillinger还不错。大部分时间都很好用。 - three
1StackEdit是一个很棒的工具。谢谢！ - Olkunmustafa
1StackEdit格式化“定义列表”，GitHub不支持。StackEdit将三重反引号代码块放在它们自己的行上（对于使用编号列表非常有用），而GitHub不支持。还有其他的差异。唯一的安全方法是使用gist进行尝试和错误，并在完成后删除它。 - Bruno Bronosky
2很不幸，它看起来并不支持MacOS Mojave（10.14）的Mou。 - Chris Priest
显示剩余3条评论
106
Atom 可以轻松地执行操作 - 只需打开Markdown文件，按下Ctrl+Shift+M即可切换到旁边的Markdown预览面板。 它还支持处理HTML和图像。
- Brian Burns
7
3由于我拥有本地资源，例如应用程序截图，因此这个解决方案最为有效。谢谢！ - Emadpres
8我已经使用Atom一年了，但不知道它可以做到那个！请带来耻辱的修女... - PaulB
brew cask install atom - jmgarnier
perfs已经安装了Atom，只需键入
atom .并右键单击readme文件>Markdown预览。 - austin1Ctrl+Shift+M 对我来说无法使用，不知何故。只能打开命令面板（Ctrl+Shift+P），然后从中选择Markdown预览。谢谢！ - Spikatrix
显示剩余2条评论
101
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规范转移。
预览按钮如下图所示：
- Nikhil Agrawal
4
8好的！我不必安装Atom了！！ - aerin
2顺便说一下，我想测试GitHub使用的标题链接（https://dev59.com/KG435IYBdhLWcg3wmxXz#45860695），结果发现它也被VS Code支持！ - Nagev
1这个解决方案应该被接受为答案。 - RPaladin
典型的VS Code体验。我打开文件，除了文件什么都看不到。然后我安装了插件，还是什么都没有。最后，有人告诉我哪个按钮可以打开它！ - undefined
55
- aleimba
2
2谢谢！不用打破我的工作流程并打开另一个编辑器或转到另一个网站真是太好了。 - oneWorkingHeadphone
5这应该是被采纳的答案 - 完美！只需在编辑器和浏览器之间切换，它就会自动重新呈现Markdown，并且它看起来与GitHub上的完全一样。最终一个可接受的解决方案。 - Upio
37
我通常直接在 GitHub 网站上进行编辑，并单击编辑窗口上方的“预览”。
也许这是自此帖子发布以来新增的新功能。
- Justin Harris
3
8这个解决方案的问题在于，GitHub（截至目前）显示更改的行内差异，在预览时如果想要了解更改的外观而非实际更改内容，则会变得难以使用。 - Felix K.
3@B12Toaster，您可以使用GitHub网站创建一个新文件（而不保存它），并将其命名为
xxx.md，然后将您的代码粘贴到其中。
文件扩展名为.md，因此您可以预览更改。
在完成更新之前，您将一直更新该文件，然后复制文件内容并将其粘贴到原始的readme.md文件上。 - Mahmoud另一个问题是它不能准确地显示所有内容。一个具体的例子：如果你使用
<div align='center'><img ...></div> 将图片居中对齐，预览时它不会居中显示，而是左对齐。你必须保存才能准确地看到它，这使得预览在我看来不可靠。 - AFOC37
这个链接已经被证实是相当可靠的：http://tmpvar.com/markdown.html
- Motin
2
开始还不错，但是这个没有显示水平线...在进一步测试之前就被放弃了。 - Ben
1虽然不错，但只适合快速检查。 - Nikos Alexandris
12
VS Code
Mac: 命令 + Shift + V
Windows: Ctrl + Shift + V
详细说明
在 VS Code 中打开 .md 文件，选择文件后使用上述键盘快捷键。
- Juno Sprite
6
我使用本地托管的HTML文件来预览GitHub自述文件。
我查看了几个现有选项，但决定自己动手满足以下要求：
每个存储库目录都包含一个README.md文件：
为了预览readme，我浏览github/readme.html，在查询字符串中指定repo：
如果readme.html与README.md在同一个目录中，您甚至不需要通过HTTP服务来提供readme.html：您可以直接从文件系统中打开它。
HTML文件使用GitHub API来呈现README.md文件中的Markdown。有一个速率限制：在撰写本文时，每小时60个请求。
在Windows 7上的当前生产版本的Chrome、IE和Firefox中对我有效。
我将CSS文件重命名以省略原始名称中的一长串十六进制数字。
我编辑了github.css，以引用本地副本的octicons字体文件。
我检查了GitHub页面的HTML，并复制了足够的HTML结构来围绕readme内容提供合理的保真度；例如，受限宽度。
GitHub的CSS、octicons字体和readme内容的HTML“容器”是不断变化的目标：我需要定期下载新版本。
我试图使用来自各种GitHub项目的CSS。例如：
我查看了几个现有选项，但决定自己动手满足以下要求：
- 单文件
- 本地托管（内部网络）URL
- 无需浏览器扩展程序
- 无需本地托管服务器端处理（例如，没有PHP）
- 轻量级（例如，没有jQuery）
- 高保真度：使用GitHub渲染Markdown，并使用相同的CSS
每个存储库目录都包含一个README.md文件：
.../github/
repo-a/
README.md
repo-b/
README.md
etc.
GitHub目录包含“预览”HTML文件：
.../github/
readme.html
为了预览readme，我浏览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将其作为“正常”的网页提供。我会调整文件以接受完整的URL - README（或任何其他Markdown文件） - 作为查询字符串。我很好奇是否由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和Octicons字体文件:
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，以引用本地副本的octicons字体文件。
我检查了GitHub页面的HTML，并复制了足够的HTML结构来围绕readme内容提供合理的保真度；例如，受限宽度。
GitHub的CSS、octicons字体和readme内容的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>
- Graham Hannington
4
- Guilherme de Jesus Santos
网页内容由stack overflow 提供, 点击上面的可以查看英文原文，
原文链接
原文链接
README.md）之前查看其外观。请参见下面的答案。 - VonCREADME.md而不是README.rst。 - DanielBell99