Tôi sử dụng tệp HTML được lưu trữ cục bộ để xem trước GmesHub readmes.
Tôi đã xem xét một số tùy chọn hiện có, nhưng quyết định tự lăn để đáp ứng các yêu cầu sau:
- Tập tin duy nhất
- URL được lưu trữ cục bộ (mạng nội bộ)
- Không cần mở rộng trình duyệt
- Không xử lý phía máy chủ được lưu trữ cục bộ (ví dụ: không có PHP)
- Nhẹ (ví dụ: không có jQuery)
- Độ trung thực cao: sử dụng GitHub để hiển thị Markdown và cùng CSS
Tôi giữ các bản sao cục bộ của kho GitHub của mình trong các thư mục anh chị em trong thư mục "github".
Mỗi thư mục repo chứa một tệp README.md:
.../github/
repo-a/
README.md
repo-b/
README.md
etc.
Thư mục github chứa tệp HTML "xem trước":
.../github/
readme.html
Để xem trước một readme, tôi duyệt github / readme.html, chỉ định repo trong chuỗi truy vấn:
http://localhost/github/readme.html?repo-a
Ngoài ra, bạn có thể sao chép readme.html vào cùng thư mục với README.md và bỏ qua chuỗi truy vấn:
http://localhost/github/repo-a/readme.html
Nếu readme.html nằm trong cùng thư mục với README.md, bạn thậm chí không cần cung cấp readme.html qua HTTP: bạn chỉ có thể mở nó trực tiếp từ hệ thống tệp của mình.
Tệp HTML sử dụng API GitHub để hiển thị Markdown trong tệp README.md. Có giới hạn tỷ lệ : tại thời điểm viết, 60 yêu cầu mỗi giờ .
Hoạt động với tôi trong các phiên bản sản xuất hiện tại của Chrome, IE và Firefox trên Windows 7.
Nguồn
Đây là tệp 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>
Ghi chú của nhà phát triển
- Thông thường, tôi bọc mã của mình trong IIFE, nhưng trong trường hợp này, tôi đã không thấy sự cần thiết và nghĩ rằng tôi sẽ giữ nó ngắn gọn
- Tôi không bận tâm đến việc hỗ trợ backlevel IE
- Để đơn giản, tôi đã bỏ qua mã xử lý lỗi (bạn có tin tôi không?!)
- Tôi hoan nghênh các mẹo lập trình JavaScript
Ý tưởng
- Tôi đang xem xét việc tạo kho lưu trữ GitHub cho tệp HTML này và đặt tệp vào nhánh gh-page để GitHub phục vụ nó như một trang web "bình thường". Tôi muốn điều chỉnh tệp để chấp nhận một URL hoàn chỉnh - của README (hoặc bất kỳ tệp Markdown nào khác) - làm chuỗi truy vấn. Tôi tò mò muốn xem liệu được lưu trữ bởi GitHub có vượt qua giới hạn yêu cầu API GitHub hay không và liệu tôi có chạy các vấn đề liên tên miền hay không (sử dụng yêu cầu Ajax để lấy Markdown từ một tên miền khác với tên miền phục vụ trang HTML) .
Phiên bản gốc (không dùng nữa)
Tôi đã lưu giữ hồ sơ này của phiên bản gốc cho giá trị tò mò. Phiên bản này có các vấn đề sau được giải quyết trong phiên bản hiện tại:
- Nó đòi hỏi một số tập tin liên quan để được tải xuống
- Nó không hỗ trợ bị rơi vào cùng thư mục với README.md
- HTML của nó dễ vỡ hơn; dễ bị thay đổi hơn trong GitHub
Thư mục github chứa tệp HTML "xem trước" và các tệp liên quan:
.../github/
readme-preview.html
github.css
github2.css
octicons.eot
octicons.svg
octicons.woff
Tôi đã tải xuống các tệp phông chữ CSS và octicons từ 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)
Tôi đã đổi tên các tệp CSS để bỏ qua chuỗi dài các chữ số hex trong tên gốc.
Tôi đã chỉnh sửa github.css để tham khảo các bản sao cục bộ của tệp phông chữ octicons.
Tôi đã kiểm tra HTML của trang GitHub và sao chép đủ cấu trúc HTML xung quanh nội dung readme để cung cấp độ trung thực hợp lý; ví dụ: chiều rộng bị ràng buộc.
GitHub CSS, phông chữ octicons và "thùng chứa" HTML cho nội dung readme đang di chuyển mục tiêu: Tôi sẽ cần định kỳ tải xuống các phiên bản mới.
Tôi đã sử dụng CSS từ các dự án GitHub khác nhau. Ví dụ:
<link rel="stylesheet" type="text/css"
href="http://rawgit.com/sindresorhus/github-markdown-css/gh-pages/github-markdown.css">
nhưng cuối cùng đã quyết định sử dụng CSS từ chính GitHub.
Nguồn
Đây là tệp 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>
