मैं GitHub रीडम्स का पूर्वावलोकन करने के लिए स्थानीय रूप से होस्ट की गई HTML फ़ाइल का उपयोग करता हूं।
मैंने कई मौजूदा विकल्पों पर ध्यान दिया, लेकिन निम्नलिखित आवश्यकताओं को पूरा करने के लिए अपना स्वयं का रोल करने का निर्णय लिया:
- एक दस्तावेज
- स्थानीय रूप से होस्ट किया गया (इंट्रानेट) URL
- कोई ब्राउज़र एक्सटेंशन की आवश्यकता नहीं है
- कोई स्थानीय रूप से होस्ट किया गया सर्वर-साइड प्रोसेसिंग (उदाहरण के लिए, कोई PHP)
- लाइटवेट (उदाहरण के लिए, कोई jQuery)
- उच्च निष्ठा: मार्कडाउन और उसी CSS को प्रस्तुत करने के लिए GitHub का उपयोग करें
मैं अपने गिथब रिपॉजिटरी की स्थानीय प्रतियों को एक "जीथब" निर्देशिका के तहत सिबलिंग निर्देशिका में रखता हूं।
प्रत्येक रेपो डायरेक्टरी में README.md फाइल होती है:
.../github/
repo-a/
README.md
repo-b/
README.md
etc.
Github निर्देशिका में "पूर्वावलोकन" HTML फ़ाइल है:
.../github/
readme.html
रीडमी का पूर्वावलोकन करने के लिए, मैं github / readme.html ब्राउज़ करता हूं, जो क्वेरी स्ट्रिंग में रेपो को निर्दिष्ट करता है:
http://localhost/github/readme.html?repo-a
वैकल्पिक रूप से, आप README.md के समान readme.html को उसी निर्देशिका में कॉपी कर सकते हैं, और क्वेरी स्ट्रिंग को छोड़ सकते हैं:
http://localhost/github/repo-a/readme.html
यदि readme.html README.md के समान निर्देशिका में है, तो आपको HTTP पर readme.html की सेवा करने की भी आवश्यकता नहीं है: आप इसे सीधे अपने फ़ाइल सिस्टम से खोल सकते हैं।
HTML फ़ाइल README.md फ़ाइल में मार्कडाउन को रेंडर करने के लिए GitHub API का उपयोग करता है । एक दर सीमा है : लेखन के समय, प्रति घंटे 60 अनुरोध ।
विंडोज 7 पर क्रोम, IE और फ़ायरफ़ॉक्स के वर्तमान उत्पादन संस्करणों में मेरे लिए काम करता है।
स्रोत
यहाँ 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>
डेवलपर नोट्स
- आमतौर पर, मैं अपना कोड IIFE में लपेटता हूं, लेकिन इस मामले में, मुझे इसकी आवश्यकता नहीं दिखी, और मैंने सोचा कि मैं इसे संक्षिप्त रखूंगा
- मैंने बैकलेवल IE का समर्थन करने की जहमत नहीं उठाई है
- संक्षिप्तता के लिए, मैंने त्रुटि हैंडलिंग कोड को छोड़ दिया है (क्या आप मुझ पर विश्वास करते हैं ?!
- मैं जावास्क्रिप्ट प्रोग्रामिंग सुझावों का स्वागत करता हूँ
विचार
- मैं इस HTML फ़ाइल के लिए GitHub रिपॉजिटरी बनाने, और फ़ाइल को g-Pages शाखा में डालने पर विचार कर रहा हूं, ताकि GitHub इसे "सामान्य" वेब पेज के रूप में कार्य करे। मैं एक पूर्ण URL - README (या किसी अन्य मार्काडाउन फ़ाइल) - क्वेरी स्ट्रिंग के रूप में स्वीकार करने के लिए फ़ाइल को ट्विक करूँगा। मुझे यह देखने की उत्सुकता है कि क्या GitHub द्वारा होस्ट किया जा रहा है GitHub API अनुरोध सीमा को रोक देगा, और क्या मैं क्रॉस-डोमेन समस्याओं से दूर चला जाऊंगा (HTML पृष्ठ की सेवा करने वाले डोमेन की तुलना में अलग डोमेन से Markdown प्राप्त करने के लिए एक Ajax अनुरोध का उपयोग करके) ।
मूल संस्करण (पदावनत)
मैंने जिज्ञासा मूल्य के लिए मूल संस्करण के इस रिकॉर्ड को संरक्षित किया है। इस संस्करण में निम्नलिखित समस्याएं थीं जो वर्तमान संस्करण में हल की गई हैं:
- इसे डाउनलोड करने के लिए कुछ संबंधित फाइलों की आवश्यकता थी
- यह README.md के समान निर्देशिका में गिराए जाने का समर्थन नहीं करता था
- इसका HTML अधिक भंगुर था; GitHub में परिवर्तन के लिए अधिक अतिसंवेदनशील
जीथब निर्देशिका में "पूर्वावलोकन" HTML फ़ाइल और संबंधित फाइलें हैं:
.../github/
readme-preview.html
github.css
github2.css
octicons.eot
octicons.svg
octicons.woff
मैंने GitHub से CSS और ऑक्टिकन्स फ़ॉन्ट फ़ाइलों को डाउनलोड किया:
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)
मैंने मूल नामों में हेक्स अंकों की लंबी स्ट्रिंग को छोड़ने के लिए सीएसएस फ़ाइलों का नाम बदला।
मैंने ऑक्टिकॉन फ़ॉन्ट फ़ाइलों की स्थानीय प्रतियों को संदर्भित करने के लिए github.css का संपादन किया।
मैंने GitHub पृष्ठ के HTML की जांच की, और उचित निष्ठा प्रदान करने के लिए readme सामग्री के आसपास HTML संरचना का पर्याप्त पुनरुत्पादन किया; उदाहरण के लिए, विवश चौड़ाई।
GitHub CSS, ऑक्टिकन्स फॉन्ट और HTML "कंटेनर" के लिए रेडीम कंटेंट बढ़ते लक्ष्य हैं: मुझे समय-समय पर नए संस्करण डाउनलोड करने होंगे।
मैं विभिन्न GitHub परियोजनाओं से सीएसएस का उपयोग करने के साथ खेला गया। उदाहरण के लिए:
<link rel="stylesheet" type="text/css"
href="http://rawgit.com/sindresorhus/github-markdown-css/gh-pages/github-markdown.css">
लेकिन अंततः GitHub से CSS का उपयोग करने का निर्णय लिया।
स्रोत
यहां 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>
