Uso un file HTML ospitato localmente per visualizzare l'anteprima dei readme di GitHub.
Ho esaminato diverse opzioni esistenti, ma ho deciso di creare il mio per soddisfare i seguenti requisiti:
- File singolo
- URL ospitato localmente (intranet)
- Nessuna estensione del browser richiesta
- Nessuna elaborazione lato server ospitata localmente (ad esempio, nessun PHP)
- Leggero (ad esempio, no jQuery)
- Alta fedeltà: usa GitHub per rendere Markdown e lo stesso CSS
Conservo copie locali dei miei repository GitHub nelle directory dei fratelli in una directory "github".
Ogni directory repo contiene un file README.md:
.../github/
repo-a/
README.md
repo-b/
README.md
etc.
La directory github contiene il file HTML "preview":
.../github/
readme.html
Per visualizzare l'anteprima di un file Leggimi, sfoglio github / readme.html, specificando il repository nella stringa di query:
http://localhost/github/readme.html?repo-a
In alternativa, è possibile copiare readme.html nella stessa directory di README.md e omettere la stringa di query:
http://localhost/github/repo-a/readme.html
Se readme.html si trova nella stessa directory di README.md, non è nemmeno necessario servire readme.html su HTTP: puoi semplicemente aprirlo direttamente dal tuo file system.
Il file HTML utilizza l' API GitHub per eseguire il rendering del markdown in un file README.md. C'è un limite di velocità : al momento della scrittura, 60 richieste all'ora .
Funziona per me nelle attuali versioni di produzione di Chrome, IE e Firefox su Windows 7.
fonte
Ecco il file 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>
Note per gli sviluppatori
- In genere, avvolgo il mio codice in un IIFE, ma in questo caso non ho visto la necessità e ho pensato di mantenerlo conciso
- Non mi sono preoccupato di supportare il backlevel IE
- Per semplicità, ho omesso il codice di gestione degli errori (mi credi ?!)
- Gradirei suggerimenti sulla programmazione JavaScript
idee
- Sto prendendo in considerazione la creazione di un repository GitHub per questo file HTML e l'inserimento del file nel ramo gh-pages, in modo che GitHub funzioni come una pagina Web "normale". Modificherei il file per accettare un URL completo - del file README (o qualsiasi altro file Markdown) - come stringa di query. Sono curioso di vedere se essere ospitato da GitHub eviterebbe il limite di richieste API GitHub e se avrò problemi di interdominio (usando una richiesta Ajax per ottenere il Markdown da un dominio diverso rispetto al dominio che serve la pagina HTML) .
Versione originale (obsoleta)
Ho conservato questo record della versione originale per valore di curiosità. Questa versione presentava i seguenti problemi risolti nella versione corrente:
- Richiedeva il download di alcuni file correlati
- Non supportava il rilascio nella stessa directory di README.md
- Il suo HTML era più fragile; più suscettibile ai cambiamenti in GitHub
La directory github contiene il file HTML "preview" e i file correlati:
.../github/
readme-preview.html
github.css
github2.css
octicons.eot
octicons.svg
octicons.woff
Ho scaricato i file dei font CSS e octicons da 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)
Ho rinominato i file CSS per omettere la lunga stringa di cifre esadecimali nei nomi originali.
Ho modificato github.css per fare riferimento alle copie locali dei file dei font Octicons.
Ho esaminato l'HTML di una pagina GitHub e riprodotto abbastanza della struttura HTML che circonda il contenuto del readme per fornire una ragionevole fedeltà; ad esempio, la larghezza vincolata.
Il CSS GitHub, il font octicons e il "contenitore" HTML per il contenuto del file Leggimi sono obiettivi mobili: dovrò scaricare periodicamente nuove versioni.
Ho giocato con l'utilizzo dei CSS da vari progetti GitHub. Per esempio:
<link rel="stylesheet" type="text/css"
href="http://rawgit.com/sindresorhus/github-markdown-css/gh-pages/github-markdown.css">
ma alla fine decise di usare il CSS dallo stesso GitHub.
fonte
Ecco il file 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>
