I am writing a readme for my github project in the .md format. Is there a way can I test what my readme.md file will look like before committing to github?
282
votes
I'm answering this as a comment because the thread is closed and none of the solutions were rendering pipe tables the same way that github was. The web solution that seems closest is here: pandao.github.io/editor.md/en.html
– Donnie D'Amato
With GitLab 13.0 (May 2020), the static site editor for GitLab has a WYSIWYG editor. See my answer below.
– VonC
25 Answers
166
votes
96
votes
Atom works nicely out of the box - just open the Markdown file and hit Ctrl+Shift+M to toggle the Markdown preview panel next to it. It handles HTML and images also.
42
votes
This is a pretty old question, however since I stumbled upon it while searching the internet maybe my answer is useful to others. I just found a very useful CLI tool for rendering GitHub flavored markdown: grip. It uses GitHub's API, thus renders quite well.
Frankly, the developer of grip, has a more elaborate answer on these very similar questions:
42
votes
Visual Studio Code has the option to edit and preview md file changes. Since VS Code is platform independent, this would work for Windows, Mac and Linux.
To switch between views, press Ctrl+Shift+V in the editor. You can view the preview side-by-side (Ctrl+K V) with the file you are editing and see changes reflected in real-time as you edit.
Also...
Q: Does VS Code support GitHub Flavored Markdown?
A: No, VS Code targets the CommonMark Markdown specification using the markdown-it library. GitHub is moving toward the CommonMark specification.
37
votes
32
votes
7
votes
5
votes
I use a locally hosted HTML file to preview GitHub readmes.
I looked at several existing options, but decided to roll my own to meet the following requirements:
- Single file
- Locally hosted (intranet) URL
- No browser extension required
- No locally hosted server-side processing (for example, no PHP)
- Lightweight (for example, no jQuery)
- High fidelity: use GitHub to render the Markdown, and same CSS
I keep local copies of my GitHub repositories in sibling directories under a "github" directory.
Each repo directory contains a README.md file:
.../github/
repo-a/
README.md
repo-b/
README.md
etc.
The github directory contains the "preview" HTML file:
.../github/
readme.html
To preview a readme, I browse github/readme.html, specifying the repo in the query string:
http://localhost/github/readme.html?repo-a
Alternatively, you can copy the readme.html into the same directory as the README.md, and omit the query string:
http://localhost/github/repo-a/readme.html
If the readme.html is in the same directory as README.md, you don't even need to serve readme.html over HTTP: you can just open it directly from your file system.
The HTML file uses the GitHub API to render the Markdown in a README.md file. There's a rate limit: at the time of writing, 60 requests per hour.
Works for me in current production versions of Chrome, IE, and Firefox on Windows 7.
Source
Here's the HTML file (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>
Developer notes
- Typically, I wrap my code in an IIFE, but in this case, I didn't see the need, and thought I'd keep it concise
- I haven't bothered supporting backlevel IE
- For conciseness, I have omitted the error handling code (do you believe me?!)
- I'd welcome JavaScript programming tips
Ideas
- I'm considering creating a GitHub repository for this HTML file, and putting the file in the gh-pages branch, so that GitHub serves it as a "normal" web page. I'd tweak the file to accept a complete URL - of the README (or any other Markdown file) - as the query string. I'm curious to see whether being hosted by GitHub would sidestep the GitHub API request limit, and whether I run afoul of cross-domain issues (using an Ajax request to get the Markdown from a different domain than the domain serving the HTML page).
Original version (deprecated)
I've preserved this record of the original version for curiosity value. This version had the following issues that are solved in the current version:
- It required some related files to be downloaded
- It didn't support being dropped into the same directory as the README.md
- Its HTML was more brittle; more susceptible to changes in GitHub
The github directory contains the "preview" HTML file and related files:
.../github/
readme-preview.html
github.css
github2.css
octicons.eot
octicons.svg
octicons.woff
I downloaded the CSS and octicons font files from GitHub:
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)
I renamed the CSS files to omit the long string of hex digits in the original names.
I edited github.css to refer to the local copies of the octicons font files.
I examined the HTML of a GitHub page, and reproduced enough of the HTML structure surrounding the readme content to provide reasonable fidelity; for example, the constrained width.
The GitHub CSS, octicons font, and HTML "container" for the readme content are moving targets: I will need to periodically download new versions.
I toyed with using CSS from various GitHub projects. For example:
<link rel="stylesheet" type="text/css"
href="http://rawgit.com/sindresorhus/github-markdown-css/gh-pages/github-markdown.css">
but eventually decided to use the CSS from GitHub itself.
Source
Here's the HTML file (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>
4
votes
For Visual Studio users (not VS CODE).
Install Markdown Editor extension
This way, when you open a README.md you'll have a live preview on right side.
3
votes
3
votes
2
votes
2
votes
2
votes
MarkdownPreview, the plugin for Sublime Text mentioned in an earlier comment is not compatible with ST2 any more, but only supports Sublime Text 3 (since spring 2018).
What's neat about it: it supports GFM, GitHub Flavored Markdown, which can do a bit more than regular Markdown. This is of relevance if you want to know what your .mds will look like on GH exactly. (Including this bit of info because the OP didn't add the GFM tag themselves, and others looking for a solution might not be aware of it either.)
You can use it with the GitHub API if you are online, though you should get a personal access token for this purpose because API calls without authentication are limited. There's more info on Parsing GFM in the plugin's docs.
1
votes
If you're using Pycharm (or another Jetbrains IDE like Intellij, RubyMine, PHPStorm, etc), there are multiple free plugins for Markdown support right in your IDE that allow real-time preview while editing. The Markdown Navigator plugin is quite good. If you open an .md file in the IDE, recent versions will offer to install supporting plugins and show you the list.
1
votes
Use Jupyter Lab.
To install Jupyter Lab, type the following in your environment:
pip install jupyterlab
After installation, browse to the location of your markdown file, right-click the file, select "Open With" then click "Markdown Preview".
1
votes
ReText is a good lightweight markdown viewer/editor.
ReText with Live Preview (source: ReText; click image for larger variant)
I found it thanks to Izzy who answered https://softwarerecs.stackexchange.com/questions/17714/simple-markdown-viewer-for-ubuntu (other answers mention other possibilities)
1
votes
1
votes
0
votes
MarkdownViewerPlusPlus is a "[...]Notepad++ Plugin to view a Markdown file rendered on-the-fly Features
- Dockable panel (toggle) with a rendered HTML of the currently selected file/tab
- CommonMark compliant (0.28)
- Synchronized scrolling
- Custom CSS integration
- HTML and PDF Export
- Notepad++ Unicode Plugin [...]"
0
votes
You could use the static site editor: with GitLab 13.0 (May 2020), it comes with a WYSIWYG panel.
WYSIWYG for the Static Site Editor
Markdown is a powerful and efficient syntax for authoring web content, but even seasoned authors of Markdown content can struggle to remember some of the less-frequently used formatting options or write even moderately-complex tables from scratch.
There are some jobs better accomplished with a rich text, “What You See Is What You Get” (WYSIWYG) editor.GitLab 13.0 brings a WYSIWYG Markdown authoring experience to the Static Site Editor with formatting options for common formatting options like headers, bold, italics, links, lists, blockquotes, and code blocks.
The WYSIWYG editor also removes the onerous task of editing tables in Markdown by letting you visually edit table rows, columns and cells in the same way you would edit a spreadsheet. For those more comfortable writing in raw Markdown, there’s even a tab for switching between WYSIWYG and plain text editing modes.
See documentation and issue.
Again, you would use it only to write your README: once it looks good, you can report it back to your original project.
But the point is: you don't need no more any thrid-party markdown preview plugin.
0
votes
I have found that markdownlivepreview.com is pretty close to vanilla GitLab markdown. Other viewers interpreted commands slightly differently than GitLab does.
0
votes
One way is using the Pandoc (very useful).
Copy your Markdown plaint text to clipboard
Run:
xsel -b | pandoc -s -f markdown -t html | xclip -selection clipboard -t text/html | xsel -bPaste the generated formatted text (for example on an email or LibreOffice).
You said you are using Linux. You'll need to just install pandoc package.
