J'utilise un fichier HTML hébergé localement pour prévisualiser les fichiers Lisezmoi de GitHub.
J'ai examiné plusieurs options existantes, mais j'ai décidé de lancer la mienne pour répondre aux exigences suivantes:
- Un seul fichier
- URL hébergée localement (intranet)
- Aucune extension de navigateur requise
- Pas de traitement côté serveur hébergé localement (par exemple, pas de PHP)
- Léger (par exemple, pas de jQuery)
- Haute fidélité: utilisez GitHub pour rendre le Markdown et le même CSS
Je garde des copies locales de mes dépôts GitHub dans des répertoires frères sous un répertoire "github".
Chaque répertoire repo contient un fichier README.md:
.../github/
repo-a/
README.md
repo-b/
README.md
etc.
Le répertoire github contient le fichier HTML "prévisualisation":
.../github/
readme.html
Pour prévisualiser un fichier Lisezmoi, je parcours github / readme.html, en spécifiant le référentiel dans la chaîne de requête:
http://localhost/github/readme.html?repo-a
Vous pouvez également copier le fichier readme.html dans le même répertoire que le fichier README.md et omettre la chaîne de requête:
http://localhost/github/repo-a/readme.html
Si le fichier readme.html se trouve dans le même répertoire que README.md, vous n'avez même pas besoin de servir readme.html sur HTTP: vous pouvez simplement l'ouvrir directement à partir de votre système de fichiers.
Le fichier HTML utilise l' API GitHub pour rendre le Markdown dans un fichier README.md. Il y a une limite de taux : au moment de la rédaction, 60 demandes par heure .
Fonctionne pour moi dans les versions de production actuelles de Chrome, IE et Firefox sur Windows 7.
La source
Voici le fichier 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>
Notes aux développeurs
- En général, j'emballe mon code dans un IIFE, mais dans ce cas, je n'ai pas vu le besoin, et j'ai pensé que je resterais concis
- Je n'ai pas pris la peine de prendre en charge IE de niveau supérieur
- Par souci de concision, j'ai omis le code de gestion des erreurs (me croyez-vous?!)
- Je serais ravi des conseils de programmation JavaScript
Des idées
- J'envisage de créer un référentiel GitHub pour ce fichier HTML et de placer le fichier dans la branche gh-pages, afin que GitHub le serve de page Web "normale". Je modifierais le fichier pour accepter une URL complète - du fichier README (ou de tout autre fichier Markdown) - comme chaîne de requête. Je suis curieux de voir si être hébergé par GitHub contournerait la limite de demande d'API GitHub, et si j'exécute des problèmes inter-domaines (en utilisant une demande Ajax pour obtenir le Markdown à partir d'un domaine différent de celui qui sert la page HTML) .
Version originale (obsolète)
J'ai conservé cet enregistrement de la version originale pour une valeur de curiosité. Cette version avait les problèmes suivants qui sont résolus dans la version actuelle:
- Il a fallu télécharger certains fichiers associés
- Il ne supportait pas d'être déposé dans le même répertoire que le fichier README.md
- Son HTML était plus fragile; plus sensible aux changements dans GitHub
Le répertoire github contient le fichier HTML "prévisualisation" et les fichiers associés:
.../github/
readme-preview.html
github.css
github2.css
octicons.eot
octicons.svg
octicons.woff
J'ai téléchargé les fichiers de police CSS et octicons depuis 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)
J'ai renommé les fichiers CSS pour omettre la longue chaîne de chiffres hexadécimaux dans les noms d'origine.
J'ai édité github.css pour faire référence aux copies locales des fichiers de police octicons.
J'ai examiné le code HTML d'une page GitHub et j'ai reproduit suffisamment la structure HTML entourant le contenu du fichier Lisezmoi pour fournir une fidélité raisonnable; par exemple, la largeur contrainte.
Le CSS GitHub, la police octicons et le "conteneur" HTML pour le contenu du fichier Lisezmoi sont des cibles mobiles: je devrai télécharger périodiquement de nouvelles versions.
J'ai joué avec l'utilisation de CSS de divers projets GitHub. Par exemple:
<link rel="stylesheet" type="text/css"
href="http://rawgit.com/sindresorhus/github-markdown-css/gh-pages/github-markdown.css">
mais a finalement décidé d'utiliser le CSS de GitHub lui-même.
La source
Voici le fichier 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>
