Ich schreibe eine Readme für mein Github-Projekt im .md-Format. Gibt es eine Möglichkeit, wie ich testen kann, wie meine readme.md-Datei aussehen wird, bevor ich sie an Github übertrage?
Antworten
Zu viele Anzeigen?
Motin
Punkte
4312
Dieser hat sich seit geraumer Zeit als zuverlässig erwiesen: http://tmpvar.com/markdown.html
Juno Sprite
Punkte
111
Graham Hannington
Punkte
1451
Ich verwende eine lokal gehostete HTML-Datei zur Vorschau von GitHub-Readmes.
Ich habe mir mehrere vorhandene Optionen angesehen, mich dann aber entschieden, meine eigene Lösung zu entwickeln, um die folgenden Anforderungen zu erfüllen:
- Einzelne Datei
- Lokal gehostete (Intranet-)URL
- Keine Browsererweiterung erforderlich
- Keine lokal gehostete serverseitige Verarbeitung (z. B. kein PHP)
- Leichtgewichtig (zum Beispiel kein jQuery)
- Hohe Wiedergabetreue: Verwendung von GitHub zum Rendern des Markdown und des gleichen CSS
Ich bewahre lokale Kopien meiner GitHub-Repositories in Geschwisterverzeichnissen unter einem "github"-Verzeichnis auf.
Jedes Repo-Verzeichnis enthält eine README.md-Datei:
.../github/
repo-a/
README.md
repo-b/
README.md
etc.Das github-Verzeichnis enthält die HTML-Datei "preview":
.../github/
readme.htmlZur Vorschau einer Readme-Datei durchsuche ich github/readme.html, wobei ich das Repo im Query-String angebe:
http://localhost/github/readme.html?repo-aAlternativ können Sie die readme.html in dasselbe Verzeichnis wie die README.md kopieren und die Abfragezeichenfolge weglassen:
http://localhost/github/repo-a/readme.htmlWenn sich die Datei readme.html im gleichen Verzeichnis wie README.md befindet, müssen Sie readme.html nicht einmal über HTTP bereitstellen: Sie können sie einfach direkt von Ihrem Dateisystem aus öffnen.
Die HTML-Datei verwendet die GitHub-API um das Markdown in einer README.md-Datei wiederzugeben. Es gibt eine Preisgrenze zum Zeitpunkt der Erstellung dieses Berichts, 60 Anfragen pro Stunde .
Funktioniert bei mir in den aktuellen Produktionsversionen von Chrome, IE und Firefox unter Windows 7.
Quelle
Hier ist die HTML-Datei (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>Hinweise für Entwickler
- Normalerweise verpacke ich meinen Code in ein IIFE, aber in diesem Fall sah ich keine Notwendigkeit und dachte, ich würde es kurz halten
- Ich habe mir nicht die Mühe gemacht, Backlevel IE zu unterstützen.
- Der Kürze halber habe ich den Code für die Fehlerbehandlung weggelassen (können Sie mir das glauben?!)
- Ich würde Tipps zur JavaScript-Programmierung begrüßen
Ideen
- Ich erwäge, ein GitHub-Repository für diese HTML-Datei zu erstellen und die Datei in den gh-pages-Zweig zu stellen, damit GitHub sie als "normale" Webseite bereitstellt. Ich würde die Datei so anpassen, dass sie eine vollständige URL - der README (oder einer anderen Markdown-Datei) - als Abfragezeichenfolge akzeptiert. Ich bin neugierig zu sehen, ob durch GitHub gehostet würde umgehen die GitHub-API-Anfrage zu begrenzen, und ob ich in Konflikt mit Cross-Domain-Probleme (mit einem Ajax-Anfrage, um die Markdown von einer anderen Domäne als die Domäne, die die HTML-Seite dient) laufen.
Ursprüngliche Version (veraltet)
Ich habe diese Aufzeichnung der Originalversion aus Neugierde aufbewahrt. Diese Version hatte die folgenden Probleme, die in der aktuellen Version gelöst sind:
- Es mussten einige zugehörige Dateien heruntergeladen werden
- Es konnte nicht in dasselbe Verzeichnis wie die README.md abgelegt werden
- Sein HTML war brüchiger, anfälliger für Änderungen in GitHub
Das github-Verzeichnis enthält die HTML-Datei "preview" und zugehörige Dateien:
.../github/
readme-preview.html
github.css
github2.css
octicons.eot
octicons.svg
octicons.woffIch habe die CSS- und Octicons-Schriftdateien von GitHub heruntergeladen:
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)Ich habe die CSS-Dateien umbenannt, um die lange Kette von Hex-Ziffern in den ursprünglichen Namen wegzulassen.
Ich habe github.css bearbeitet, um auf die lokalen Kopien der octicons-Schriftartendateien zu verweisen.
Ich habe den HTML-Code einer GitHub-Seite untersucht und die HTML-Struktur, die den Readme-Inhalt umgibt, so weit reproduziert, dass sie einigermaßen originalgetreu ist, z. B. die eingeschränkte Breite.
Das GitHub-CSS, die Schriftart Octicons und der HTML-"Container" für die Readme-Inhalte sind bewegliche Ziele: Ich werde in regelmäßigen Abständen neue Versionen herunterladen müssen.
Ich habe mit der Verwendung von CSS aus verschiedenen GitHub-Projekten gespielt. Zum Beispiel:
<link rel="stylesheet" type="text/css"
href="http://rawgit.com/sindresorhus/github-markdown-css/gh-pages/github-markdown.css">beschloss aber schließlich, das CSS von GitHub selbst zu verwenden.
Quelle
Hier ist die HTML-Datei (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>
Guilherme de Jesus Santos
Punkte
4765
Für Benutzer von Visual Studio (nicht VS CODE).
Installieren Sie Markdown-Editor Erweiterung 
Auf diese Weise haben Sie beim Öffnen einer README.md eine Live-Vorschau auf der rechten Seite.
