How can I test what my readme.md file will look like before committing to github? [closed]
https://stackoverflow.com/questions/9331281
-
27-10-2019 - |
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
RussianQuestion
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?
OTHER TIPS
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.
This one has proven reliable for quite some time: http://tmpvar.com/markdown.html
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:
I usually just edit it on the GitHub website directly and click "Preview" just above the editing window.
Perhaps that's a new feature that's been added since this post was made.
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.
In the web, use Dillinger. It's awesome.
You may want to take a look at this one:
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>
Just searching the web gives many heres one: https://stackedit.io/
For Github or Bitbucket theme, could use online editor mattstow, url: http://writeme.mattstow.com
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.
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.
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.
SublimeText 2/3
Install package: Markdown Preview
Options:
- Preview in browser.
- Export to html.
- Copy to clipboard.
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".
For Visual Studio Code, I use
Markdown Preview Enhanced extension.
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)
I am using markdownlivepreview:
https://markdownlivepreview.com/
It is very easy, simple and fast.
For those who wish to develop on their iPads, I like Textastic. You can edit and preview the README.md files without an internet connection, once you have downloaded the document from the cloud.
