Utilizo un archivo HTML alojado localmente para obtener una vista previa de los archivos Léame de GitHub.
Miré varias opciones existentes, pero decidí desarrollar las mías para cumplir con los siguientes requisitos:
- Fila india
- URL alojada localmente (intranet)
- No se requiere extensión del navegador
- Sin procesamiento del lado del servidor alojado localmente (por ejemplo, sin PHP)
- Ligero (por ejemplo, no jQuery)
- Alta fidelidad: use GitHub para representar el Markdown y el mismo CSS
Guardo copias locales de mis repositorios de GitHub en directorios hermanos bajo un directorio "github".
Cada directorio de repos contiene un archivo README.md:
.../github/
repo-a/
README.md
repo-b/
README.md
etc.
El directorio github contiene el archivo HTML "vista previa":
.../github/
readme.html
Para obtener una vista previa de un archivo Léame, busco github / readme.html, especificando el repositorio en la cadena de consulta:
http://localhost/github/readme.html?repo-a
Alternativamente, puede copiar el archivo readme.html en el mismo directorio que README.md y omitir la cadena de consulta:
http://localhost/github/repo-a/readme.html
Si readme.html está en el mismo directorio que README.md, ni siquiera necesita servir readme.html a través de HTTP: simplemente puede abrirlo directamente desde su sistema de archivos.
El archivo HTML utiliza la API de GitHub para representar el Markdown en un archivo README.md. Hay un límite de velocidad : al momento de escribir, 60 solicitudes por hora .
Funciona para mí en las versiones de producción actuales de Chrome, IE y Firefox en Windows 7.
Fuente
Aquí está el archivo 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>
Notas del desarrollador
- Por lo general, envuelvo mi código en un IIFE, pero en este caso, no vi la necesidad y pensé en mantenerlo conciso
- No me he molestado en admitir IE de nivel de fondo
- Para ser concisos, he omitido el código de manejo de errores (¡¿me crees ?!)
- Agradecería los consejos de programación de JavaScript
Ideas
- Estoy considerando crear un repositorio de GitHub para este archivo HTML y colocar el archivo en la rama gh-pages, para que GitHub lo sirva como una página web "normal". Ajustaría el archivo para aceptar una URL completa, del archivo README (o cualquier otro archivo Markdown), como la cadena de consulta. Tengo curiosidad por ver si ser alojado por GitHub eludiría el límite de solicitud de API de GitHub y si me encuentro con problemas de dominio cruzado (usando una solicitud de Ajax para obtener el Markdown desde un dominio diferente al dominio que sirve la página HTML) .
Versión original (en desuso)
He conservado este registro de la versión original por valor de curiosidad. Esta versión tenía los siguientes problemas que se resuelven en la versión actual:
- Se requirieron algunos archivos relacionados para descargar
- No admitía que se soltara en el mismo directorio que README.md
- Su HTML era más frágil; más susceptible a los cambios en GitHub
El directorio github contiene el archivo HTML de "vista previa" y archivos relacionados:
.../github/
readme-preview.html
github.css
github2.css
octicons.eot
octicons.svg
octicons.woff
Descargué los archivos de fuente CSS y octicons de 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)
Cambié el nombre de los archivos CSS para omitir la larga cadena de dígitos hexadecimales en los nombres originales.
Edité github.css para referirme a las copias locales de los archivos de fuente de octicons.
Examiné el HTML de una página de GitHub y reproduje suficiente estructura HTML que rodea el contenido del archivo Léame para proporcionar una fidelidad razonable; por ejemplo, el ancho restringido.
El CSS de GitHub, la fuente de octicons y el "contenedor" HTML para el contenido del archivo Léame son objetivos móviles: necesitaré descargar periódicamente nuevas versiones.
Jugué con el uso de CSS de varios proyectos de GitHub. Por ejemplo:
<link rel="stylesheet" type="text/css"
href="http://rawgit.com/sindresorhus/github-markdown-css/gh-pages/github-markdown.css">
pero finalmente decidió usar el CSS de GitHub.
Fuente
Aquí está el archivo 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>
