Bagaimana saya bisa menguji seperti apa file readme.md saya sebelum berkomitmen ke github?

235

Saya menulis readme untuk proyek github saya dalam format .md. Apakah ada cara saya bisa menguji seperti apa file readme.md saya sebelum berkomitmen ke github?

github markdown github-flavored-markdown Usman Ismail
sumber
4
Saya menjawab ini sebagai komentar karena utas ditutup dan tidak ada solusi yang menyajikan tabel pipa dengan cara yang sama seperti github. Solusi web yang tampaknya paling dekat ada di sini: pandao.github.io/editor.md/en.html
Donnie D'Amato
Dengan GitLab 13.0 (Mei 2020), editor situs statis untuk GitLab memiliki editor WYSIWYG. Lihat jawaban saya di bawah ini .
VonC

Jawaban:

150

Banyak cara: Jika Anda menggunakan Mac, gunakan Mou .

Jika Anda ingin menguji di browser, Anda dapat mencoba StackEdit , seperti yang ditunjukkan oleh @ Harun atau Dillinger karena Notepag tampaknya turun sekarang. Secara pribadi saya menggunakan Dillinger karena hanya berfungsi dan menyimpan semua dokumen saya di basis data lokal browser saya.

tiga
sumber
5
dillinger.io juga tampaknya turun sekarang, meskipun masih yang pertama kali terdaftar saat Anda google "markdown online viewer", jadi mungkin hanya saya. Saya berhasil menggunakan stackedit.io untuk mempratinjau dan mengedit readme.md saya.
Aaron
Dillinger dan ok. Sudah ok sebagian besar waktu.
tiga
1
StackEdit adalah alat yang hebat. Terima kasih!
Olkunmustafa
StackEdit memformat "daftar definisi", sedangkan github tidak. StackEdit menempatkan tiga blok kode backtick pada barisnya sendiri (berguna untuk digunakan dalam daftar bernomor), github tidak. Ada perbedaan lain. Satu-satunya taruhan yang aman adalah mencoba-coba dengan intisari dan menghapusnya setelah Anda selesai.
Bruno Bronosky
1
Sayangnya itu tidak terlihat seperti Mou mendukung MacOS Mojave (10.14)
Chris Priest
79

Atom berfungsi dengan baik di luar kotak - cukup buka file Markdown dan tekan Ctrl + Shift + M untuk mengaktifkan panel pratinjau Markdown di sebelahnya. Ini menangani HTML dan gambar juga.

Tangkapan layar atom

Brian Burns
sumber
2
Karena saya memiliki sumber daya lokal, seperti tangkapan layar aplikasi, solusi ini berfungsi paling baik. Terima kasih!
Emadpres
6
Saya telah menggunakan atom selama satu tahun sekarang dan tidak tahu itu bisa melakukan itu! Bawakan biarawati yang malu ...
PaulB
brew cask install atom
jmgarnier
perfs sudah menginstal Atom hanya mengetik atom .dan mengklik kanan readme>Markdown Preview
austin
Atom mengatur tempat bertenggernya. Tidak ada bagian stackedit, Dillinger, atau typora yang didukung yang dapat dilipat melalui <details>tag HTML . Atom melakukan dan terlihat lebih baik daripada yang lain untuk boot.
David Parks
35

Yang ini telah terbukti andal untuk beberapa waktu: http://tmpvar.com/markdown.html

Motin
sumber
Itu adalah awal yang baik tetapi kemudian ini tidak menunjukkan aturan horizontal ... ditinggalkan sebelum tes lebih lanjut.
Ben
Bagus untuk pemeriksaan cepat.
Nikos Alexandris
35

Ini adalah pertanyaan yang cukup lama, namun karena saya menemukan itu saat mencari di internet mungkin jawaban saya bermanfaat bagi orang lain. Saya baru saja menemukan alat CLI yang sangat berguna untuk rendering penurunan rasa GitHub: grip . Ia menggunakan API GitHub, sehingga menghasilkan cukup baik.

Frankly, pengembang cengkeraman , memiliki jawaban yang lebih rumit tentang pertanyaan-pertanyaan yang sangat mirip ini:

aleimba
sumber
2
Terima kasih! Sangat menyenangkan tidak harus merusak alur kerja saya dan membuka editor yang berbeda atau pergi ke situs web yang berbeda
oneWorkingHeadphone
1
Ini harus menjadi jawaban yang diterima - sempurna! Cukup alt-tab antara editor dan browser Anda, dan itu akan secara otomatis merender ulang penurunan harga, dan itu terlihat persis seperti di GitHub. Akhirnya solusi yang bisa diterima.
Upio
30

Saya biasanya mengeditnya langsung di situs web GitHub dan klik "Pratinjau" tepat di atas jendela pengeditan.

Mungkin itu fitur baru yang telah ditambahkan sejak posting ini dibuat.

Justin Harris
sumber
8
Masalah dengan solusi ini adalah bahwa GitHub (sejauh ini) menunjukkan perbedaan sebaris dari perubahan yang membuat pratinjau sangat tidak dapat digunakan jika Anda ingin mendapatkan kesan bagaimana perubahan itu terlihat dan bukan apa yang sebenarnya berubah.
B12Toaster
2
@ B12Toaster Anda dapat membuat file baru di repositori menggunakan situs web GitHub (tanpa menyimpannya) dan beri nama xxx.mddan rekatkan kode Anda di sana. Ekstensi file adalah .mdagar Anda dapat melihat pratinjau perubahan Anda. Anda akan memperbarui jika Anda selesai, lalu menyalin konten file dan menempelkannya di readme.mdfile asli .
Mahmoud
Masalah tambahan adalah bahwa ia tidak menampilkan semuanya dengan akurat. Salah satu contoh konkret: jika Anda memusatkan gambar di bagian atas menggunakan <div align='center'><img ...></div>itu tidak akan menunjukkan itu berpusat di pratinjau, itu akan menjadi rata kiri. Anda harus menyimpannya untuk melihatnya secara akurat, yang membuat pratinjau tidak dapat dipercaya menurut saya.
AFOC
28

Visual Studio Code memiliki opsi untuk mengedit dan melihat perubahan file md. Karena VS Code adalah platform independen, ini akan bekerja untuk Windows, Mac dan Linux.

Untuk beralih di antara tampilan, tekan Ctrl + Shift + V di editor. Anda dapat melihat pratinjau berdampingan (Ctrl + KV) dengan file yang sedang Anda edit dan melihat perubahan yang tercermin secara real-time saat Anda mengedit.

Juga...

T: Apakah VS Code mendukung GitHub Flavoured Markdown?

A: Tidak, VS Code menargetkan spesifikasi CommonMark Markdown menggunakan perpustakaan markdown-it. GitHub bergerak menuju spesifikasi CommonMark.

Lebih detail di sini

Nikhil Agrawal
sumber
3
Bagus!! Saya tidak perlu menginstal atom !!
Aerin
1
Omong-omong, saya ingin menguji tautan ke judul yang digunakan oleh GitHub ( stackoverflow.com/a/45860695/5362795 ) dan ternyata juga didukung oleh VS Code!
Nagev
5

Saya menggunakan file HTML yang di-host secara lokal untuk melihat pratinjau readit GitHub.

Saya melihat beberapa opsi yang ada, tetapi memutuskan untuk roll sendiri untuk memenuhi persyaratan berikut:

  • File tunggal
  • URL yang diinangi secara lokal (intranet)
  • Tidak diperlukan ekstensi browser
  • Tidak ada pemrosesan sisi server yang di-host secara lokal (misalnya, tidak ada PHP)
  • Ringan (misalnya, tanpa jQuery)
  • Kesetiaan tinggi: gunakan GitHub untuk membuat penurunan harga, dan CSS yang sama

Saya menyimpan salinan lokal dari repositori GitHub saya di direktori saudara di bawah direktori "github".

Setiap direktori repo berisi file README.md:

.../github/
           repo-a/
                  README.md
           repo-b/
                  README.md
           etc.

Direktori github berisi file HTML "pratinjau":

.../github/
           readme.html

Untuk mempratinjau readme, saya menjelajahi github / readme.html, menentukan repo dalam string kueri:

http://localhost/github/readme.html?repo-a

Atau, Anda dapat menyalin readme.html ke direktori yang sama dengan README.md, dan menghilangkan string kueri:

http://localhost/github/repo-a/readme.html

Jika readme.html berada di direktori yang sama dengan README.md, Anda bahkan tidak perlu menayangkan readme.html melalui HTTP: Anda bisa membukanya langsung dari sistem file Anda.

File HTML menggunakan API GitHub untuk merender Markdown dalam file README.md. Ada batasan kurs : pada saat penulisan, 60 permintaan per jam .

Bekerja untuk saya dalam versi produksi Chrome, IE, dan Firefox saat ini pada Windows 7.

Sumber

Ini file 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>

Catatan pengembang

  • Biasanya, saya membungkus kode saya dalam IIFE, tetapi dalam kasus ini, saya tidak melihat kebutuhan, dan berpikir saya akan menyimpannya secara ringkas
  • Saya belum peduli mendukung backlevel IE
  • Untuk keringkasan, saya telah menghilangkan kode penanganan kesalahan (apakah Anda percaya padaku ?!)
  • Saya akan menyambut tips pemrograman JavaScript

Ide ide

  • Saya sedang mempertimbangkan membuat repositori GitHub untuk file HTML ini, dan meletakkan file di cabang gh-pages, sehingga GitHub menyajikannya sebagai halaman web "normal". Saya akan mengubah file untuk menerima URL lengkap - dari README (atau file Penurunan harga lainnya) - sebagai string kueri. Saya ingin tahu apakah di-host oleh GitHub akan mengesampingkan batas permintaan API GitHub, dan apakah saya bertabrakan dengan masalah lintas-domain (menggunakan permintaan Ajax untuk mendapatkan Markdown dari domain yang berbeda dari domain yang melayani halaman HTML) .

Versi asli (usang)

Saya telah menyimpan catatan versi asli ini untuk nilai rasa ingin tahu. Versi ini memiliki masalah berikut yang diselesaikan di versi saat ini:

  • Untuk itu diperlukan beberapa file terkait untuk diunduh
  • Itu tidak mendukung dijatuhkan ke direktori yang sama dengan README.md
  • HTML-nya lebih rapuh; lebih rentan terhadap perubahan di GitHub

Direktori github berisi file HTML "pratinjau" dan file terkait:

.../github/
           readme-preview.html
           github.css
           github2.css
           octicons.eot
           octicons.svg
           octicons.woff

Saya mengunduh file font CSS dan octicons dari 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)

Saya mengganti nama file CSS untuk menghilangkan string panjang digit hex dalam nama aslinya.

Saya mengedit github.css untuk merujuk ke salinan lokal dari file font octicons.

Saya memeriksa HTML halaman GitHub, dan cukup mereproduksi struktur HTML yang mengelilingi konten readme untuk memberikan kesetiaan yang wajar; misalnya lebar dibatasi.

GitHub CSS, font octicons, dan "wadah" HTML untuk konten readme adalah target yang bergerak: Saya perlu mengunduh versi baru secara berkala.

Saya bermain-main dengan menggunakan CSS dari berbagai proyek GitHub. Sebagai contoh:

<link rel="stylesheet" type="text/css"
      href="http://rawgit.com/sindresorhus/github-markdown-css/gh-pages/github-markdown.css">

tetapi akhirnya memutuskan untuk menggunakan CSS dari GitHub itu sendiri.

Sumber

Ini file 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>
Graham Hannington
sumber
3

Untuk Githubatau Bitbuckettema, bisa menggunakan editor online mattstow , url: http://writeme.mattstow.com

Eric Wang
sumber
3

Untuk pengguna Visual Studio (bukan VS KODE).

Pasang ekstensi Editor Penurunan HargaTangkapan layar

Dengan cara ini, ketika Anda membuka README.md Anda akan memiliki pratinjau langsung di sisi kanan.

masukkan deskripsi gambar di sini

Guilherme de Jesus Santos
sumber
2

Hanya dengan mencari di web, berikan banyak yang ini: https://stackedit.io/

hasilnya
sumber
2

Preview Penurunan harga , plugin untuk Sublime Text yang disebutkan dalam komentar sebelumnya tidak kompatibel dengan ST2 lagi, tetapi hanya mendukung Sublime Text 3 (sejak musim semi 2018).

Apa yang rapi tentang hal itu: mendukung GFM, GitHub Flavoured Markdown , yang dapat melakukan sedikit lebih banyak daripada penurunan harga biasa. Ini relevan jika Anda ingin tahu seperti apa .mdpersisnya penampilan Anda di GH. (Termasuk sedikit info ini karena OP tidak menambahkan tag GFM sendiri, dan orang lain yang mencari solusi mungkin juga tidak menyadarinya.)

Anda dapat menggunakannya dengan API GitHub jika Anda online, meskipun Anda harus mendapatkan token akses pribadi untuk tujuan ini karena panggilan API tanpa otentikasi terbatas. Ada lebih banyak informasi tentang Parsing GFM di dokumen plugin.

Kay
sumber
1

Jika Anda menggunakan Pycharm (atau IDE Jetbrains lain seperti Intellij, RubyMine, PHPStorm, dll), ada beberapa plugin gratis untuk dukungan Markdown tepat di IDE Anda yang memungkinkan pratinjau waktu-nyata saat mengedit. Plugin Markdown Navigator cukup bagus. Jika Anda membuka file .md di IDE, versi terbaru akan menawarkan untuk menginstal plugin yang mendukung dan menampilkan daftar.

randalv
sumber
1

SublimeText 2/3

Instal paket: Markdown Preview

Pilihan:

  • Pratinjau di browser.
  • Ekspor ke html.
  • Menyalin ke clipboard.
alditis
sumber
Ini berfungsi dengan baik karena mendukung github, gitlab, dan penurunan harga umum. Meskipun sulit untuk menginstal.
Abel Callejo
0

Gunakan Lab Jupyter .

Untuk menginstal Jupyter Lab, ketikkan yang berikut di lingkungan Anda:

pip install jupyterlab

Setelah instalasi, browse ke lokasi file penurunan harga Anda, klik kanan file tersebut, pilih "Open With" lalu klik "Markdown Preview".

k0L1081
sumber
0

Untuk Visual Studio Code, saya menggunakan

Pratinjau Penurunan Harga. Ekstensi yang ditingkatkan.

Olusola Omosola
sumber
0

MarkdownViewerPlusPlus adalah "[...] Notepad ++ Plugin untuk melihat file penurunan harga yang diberikan Fitur-fitur on-the-fly

  • Panel dockable (beralih) dengan HTML yang diberikan dari file / tab yang dipilih saat ini
  • Sesuai dengan CommonMark (0.28)
  • Pengguliran yang disinkronkan
  • Integrasi CSS khusus
  • Ekspor HTML dan PDF
  • Notepad ++ Unicode Plugin [...] "
rob2universe
sumber
0

Anda dapat menggunakan editor situs statis : dengan GitLab 13.0 (Mei 2020) , ia dilengkapi dengan panel WYSIWYG.

WYSIWYG untuk Editor Situs Statis

Penurunan harga adalah sintaks yang kuat dan efisien untuk pembuatan konten web, tetapi bahkan penulis konten Markdown yang berpengalaman dapat berjuang untuk mengingat beberapa opsi pemformatan yang kurang sering digunakan atau menulis bahkan tabel yang cukup kompleks dari awal.
Ada beberapa pekerjaan yang lebih baik dilakukan dengan teks kaya, "Apa yang Anda Lihat Adalah Apa yang Anda Dapatkan" (WYSIWYG) editor.

GitLab 13.0 menghadirkan pengalaman penulisan WYSIWYG Markdown ke Static Site Editor dengan opsi pemformatan untuk opsi pemformatan umum seperti header, bold, miring, tautan, daftar, blockquotes, dan blok kode.

https://about.gitlab.com/images/13_0/wysiwyg-markdow-in-sse.png

Editor WYSIWYG juga menghapus tugas berat mengedit tabel dalam penurunan harga dengan membiarkan Anda secara visual mengedit baris tabel, kolom dan sel dengan cara yang sama Anda akan mengedit spreadsheet. Bagi mereka yang lebih nyaman menulis dalam Markdown mentah, bahkan ada tab untuk beralih antara WYSIWYG dan mode pengeditan teks biasa.

Lihat dokumentasi dan masalah .

Sekali lagi, Anda akan menggunakannya hanya untuk menulis README: setelah terlihat bagus, Anda dapat melaporkannya kembali ke proyek asli Anda.
Tapi intinya adalah: Anda tidak perlu lagi menggunakan plugin preview penurunan harga pihak ketiga.

VONC
sumber
-1

Bagi mereka yang ingin mengembangkan pada iPad mereka, saya suka Textastic. Anda dapat mengedit dan melihat pratinjau file README.md tanpa koneksi internet, setelah Anda mengunduh dokumen dari cloud.

ztalbot
sumber