Tôi không quá quen thuộc với ngôn ngữ đánh dấu nhẹ được github sử dụng khi cập nhật tệp README.
Đâu là tài nguyên mà tôi có thể đọc về cách viết cú pháp đánh dấu thích hợp cho các tệp README / wiki của thư viện nguồn mở của tôi?
Và có công cụ nào mà tôi có thể "xem lại tài liệu cục bộ trong trình duyệt của mình" trước khi đẩy README đã cập nhật vào kho lưu trữ github của tôi không?
Câu trả lời:
Đánh dấu được đề cập ngẫu nhiên được gọi là Markdown , được tạo ra bởi John Gruber, tác giả của blog Daring Fireball . Nguồn ban đầu của Markdown có thể được tìm thấy tại Daring Fireball - Markdown .
Có rất nhiều phương ngữ Markdown, bạn có thể tìm thấy tài liệu cho Github's trên trang Github Flavored Markdown .
mẹo hay từ trang đó:
nhấn M trên bất kỳ trang Github nào có trình chỉnh sửa Markdown để hiển thị bảng gian lận.
Bạn cũng có thể sử dụng trang Github Markdown Live Preview để kiểm tra tài liệu Markdown của mình.
Cập nhật 2012-11-08 : Các nỗ lực đang được tiến hành để chuẩn hóa cú pháp Markdown. Xem Tương lai của Markdown - Jeff Atwood, Coding Horror và Nhóm cộng đồng W3C Markdown .
Cập nhật 2014-09-09 : CommonMark một tiêu chuẩn đánh dấu và thông số kỹ thuật đã được phát hành.
( Đăng lại câu trả lời này với một số chỉnh sửa.)
Trò chơi hơi muộn, nhưng tôi đã viết một CLI nhỏ bằng Python. Nó được gọi là Grip (Github Readme Instant Preview) . Thêm vào câu trả lời của Patrick, điều này sẽ cho phép bạn "xem lại tài liệu của tôi cục bộ trong trình duyệt của tôi."
Cài đặt nó với:
$ pip install grip
Và để sử dụng nó, chỉ cần:
$ grip
Sau đó truy cập localhost:5000để xem readme.mdtệp tại vị trí đó.
Bạn cũng có thể chỉ định tệp của riêng mình:
$ grip CHANGES.md
Và thay đổi cổng:
$ grip 8080
Hoặc kết hợp hai phần trước:
$ grip CHANGES.md 8080
Bạn thậm chí có thể hiển thị GitHub-Flavored Markdown (tức là cách hiển thị nhận xét và vấn đề), tùy chọn với ngữ cảnh repo để tự động tham chiếu siêu liên kết đến các vấn đề khác:
$ grip --gfm --context=username/repo issue.md
Để ngắn gọn, hãy xem phần còn lại của các tùy chọn và chi tiết của chúng bằng cách sử dụng trợ giúp CLI:
$ grip -h
Các tính năng đáng chú ý:
Hi vọng điêu nay co ich. Kiểm tra nó ra .
Có một trình chỉnh sửa trực tuyến / trực tiếp rất hay ở đây:
http://jbt.github.io/markdown-editor/
Ngoài ra còn có một Previewnút trên GitHub.
Xem trong ảnh chụp màn hình sau rằng nút này xuất hiện khi tôi nhấp vào Chỉnh sửa README.md.
IMHO live biên tập là tốt hơn so với hiện tại một sẵn tại GitHub.
CẬP NHẬT
Vừa rồi tôi đã tìm thấy sau khi tìm kiếm Markdownvà Visual Studio rằng nếu bạn đang sử dụng VS, bạn có thể cài đặt Web Essentials và được Markdownhỗ trợ ngay từ bên trong Visual Studio. Thật tuyệt!
Nó có:
Thông tin chi tiết về nó tại đây .
Lưu ý rằng kể từ tháng 2 năm 2014, với "Độ lệch văn bản được hiển thị", bạn cũng có thể thấy phiên bản được hiển thị của một khác biệt trên tệp đánh dấu:
Các cam kết và yêu cầu kéo bao gồm các tệp văn xuôi hiện có nguồn và các chế độ xem được kết xuất .
Các thay đổi không phải văn bản xuất hiện với dấu gạch dưới có dấu chấm nhẹ. Di chuột qua văn bản để xem những gì đã thay đổi:
Một tùy chọn khác - trình soạn thảo văn bản mới của Github, Atom, sẽ hiển thị đánh dấu có hương vị github khi bạn chỉnh sửa nó. Xem https://atom.io/
Tôi không chắc liệu nó có được miễn phí (như bia) trong dài hạn hay không.
Tôi không thấy rằng các công cụ khác đủ tốt - tôi muốn:
Đây là điều cuối cùng tôi đã giải quyết: https://github.com/ypocat/gfms
> gfms
Github Flavored Markdown Server.
Run in your project's root directory.
Usage: gfms
Options:
-p, --port Port number to listen at. [required]
-h, --host Host address to bind to. [default: "localhost"]
--proxy if behind a proxy, proxy url.
-a, --api Render using Github API.
-n, --no-api-on-reload Disable usage of Github API when the doc is manually reloaded.
Vì vậy, tôi đã đặt bí danh:
alias gm='gfms -a -p 8070'
Sử dụng -ptùy chọn sẽ truy cập API Github và sử dụng CSS Github hiện tại, thực tế nên không có bất kỳ sự ngạc nhiên nào.