GitHub readmes'ı önizlemek için yerel olarak barındırılan bir HTML dosyası kullanıyorum.
Mevcut birkaç seçeneğe baktım, ancak aşağıdaki gereksinimleri karşılamak için kendime karar vermeye karar verdim:
- Tek dosya
- Yerel olarak barındırılan (intranet) URL
- Tarayıcı uzantısı gerekmez
- Yerel olarak barındırılan sunucu tarafı işleme yok (örneğin, PHP yok)
- Hafif (örneğin, jQuery yok)
- Yüksek doğruluk: Markdown'u ve aynı CSS'yi oluşturmak için GitHub'ı kullanın
GitHub veri havuzlarımın yerel kopyalarını kardeş dizinlerinde bir "github" dizini altında tutuyorum.
Her repo dizini bir README.md dosyası içerir:
.../github/
repo-a/
README.md
repo-b/
README.md
etc.
Github dizini "önizleme" HTML dosyasını içerir:
.../github/
readme.html
Benioku önizlemek için, sorgu dizesinde repo belirterek, github / readme.html göz atın:
http://localhost/github/readme.html?repo-a
Alternatif olarak, readme.html dosyasını README.md ile aynı dizine kopyalayabilir ve sorgu dizesini atlayabilirsiniz:
http://localhost/github/repo-a/readme.html
Readme.html dosyası README.md ile aynı dizindeyse, readme.html dosyasını HTTP üzerinden sunmanıza bile gerek yoktur: doğrudan dosya sisteminizden açabilirsiniz.
HTML dosyası GitHub API'sını kullanır , Markdown'ı bir README.md dosyasında oluşturmak . Bir ücret limiti vardır : yazma sırasında saatte 60 istek .
Windows 7'de Chrome, IE ve Firefox'un mevcut üretim sürümlerinde benim için çalışıyor.
Kaynak
HTML dosyası (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>
Geliştirici notları
- Tipik olarak, kodumu bir IIFE'ye sarıyorum, ancak bu durumda, ihtiyacı görmedim ve kısa ve öz tutacağımı düşündüm
- Geri seviye IE'yi desteklemekten rahatsız olmadım
- Kısaca, hata işleme kodunu atladım (bana inanıyor musunuz ?!)
- JavaScript programlama ipuçlarını memnuniyetle kabul ederim
fikirler
- Bu HTML dosyası için bir GitHub havuzu oluşturmayı ve dosyayı gh-pages dalına koyarak GitHub'ın "normal" bir web sayfası olarak hizmet etmesini düşünüyorum. Sorgu dizesi olarak README'nin (veya başka bir Markdown dosyasının) tam bir URL'sini kabul etmek için dosyayı değiştiririm. GitHub tarafından barındırılmasının GitHub API istek sınırını kaldırıp kaldırmayacağını ve alanlar arası sorunlara karşı çok fazla çalışıp çalışmadığımı (Markdown'ı HTML sayfasını sunan alan adından farklı bir alan adından almak için bir Ajax isteği kullanarak) çalıştırıp çalıştırmadığımı merak ediyorum .
Orijinal sürüm (kullanımdan kaldırıldı)
Merak değeri için orijinal sürümün bu kaydını korudum. Bu sürüm, geçerli sürümde çözülen aşağıdaki sorunlara sahipti:
- İlgili bazı dosyaların indirilmesi gerekiyordu
- README.md ile aynı dizine bırakılmasını desteklemedi
- HTML'si daha kırılgandı; GitHub'daki değişikliklere daha duyarlı
Github dizini "önizleme" HTML dosyasını ve ilgili dosyaları içerir:
.../github/
readme-preview.html
github.css
github2.css
octicons.eot
octicons.svg
octicons.woff
GitHub'dan CSS ve octicons yazı tipi dosyalarını indirdim:
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)
Orijinal adlarda onaltılık basamakların uzun dizesini atlamak için CSS dosyalarını yeniden adlandırdım.
Octicons yazı tipi dosyalarının yerel kopyalarına başvurmak için github.css dosyasını düzenledim.
Bir GitHub sayfasının HTML kodunu inceledim ve makul doğruluk sağlamak için benioku içeriğini çevreleyen HTML yapısını yeterince çoğalttım; örneğin, sınırlandırılmış genişlik.
Benioku içeriği için GitHub CSS, octicons yazı tipi ve HTML "kapsayıcı" hareketli hedefler: Periyodik olarak yeni sürümler indirmem gerekecek.
Çeşitli GitHub projelerinden CSS kullanarak oynadım. Örneğin:
<link rel="stylesheet" type="text/css"
href="http://rawgit.com/sindresorhus/github-markdown-css/gh-pages/github-markdown.css">
ancak sonunda GitHub'ın kendisinden CSS kullanmaya karar verdi.
Kaynak
HTML dosyası (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>
