Markdown Diff: İki Markdown dosyasını çevrimiçi karşılaştırın
İki Markdown belgesini yapıştırın ve neyin değiştiğini satır satır görün. README dosyaları, sürüm notları, MDX ve frontmatter'lı belgelerde çalışır. Diff tarayıcınızda çalışır.
Markdown diff aracı nedir?
İki Markdown belgesini kaynak metin düzeyinde karşılaştırmak için tarayıcıda çalışan ücretsiz bir araç. Eskimiş bir README.md'yi sola, güncellenmiş halini sağa yapıştırın; değişmiş her başlık, liste ögesi, bağlantı, kod bloğu ve tablo hücresi yanar. Hiçbir şey makinenizden çıkmaz.
Diff karakter karakter çalışır. Markdown düz metindir, dolayısıyla doğru ilkel budur: belgenin kaynağındaki gerçek değişikliği görürsünüz, bir oluşturucunun nasıl yorumlayacağına dair tahmini değil.
Genel düzyazı için metin diff'imizi zaten kullanıyorsanız, Markdown sayfası aynı motoru, gerçekten dokümantasyon yazarken karşılaşılan durumlara odaklanan metinlerle sunar. Jekyll, Hugo veya MkDocs dosyalarının başındaki YAML frontmatter bloklarını karşılaştırmak için YAML sayfası girintiye duyarlı yapıyı daha iyi yönetir. Anahtar/değer sorguları olan katı yapılandırılmış veri ise JSON diff'e aittir.
Diff aslında nasıl çalışır
Diff karakter düzeyindedir. Ham diff'in ardından bir anlamsal temizleme adımı, vurguları kelimelerin tamamına, liste ögelerine ve bağlantı hedeflerine düşecek şekilde kaydırır; satır içi bir `code span`'i ortadan ikiye bölmez ya da bir başlığın başındaki ##'yi koparmaz. Eklemeler sağda yeşile, silmeler solda kırmızıya boyanır.
Bu, oluşturulmuş çıktının değil, kaynak metnin diff'idir. Markdown işi için doğru ilkel budur ve göründüğünden daha fazla önemlidir. Aynı HTML'e oluşturulan iki belgenin kaynağı çok farklı olabilir: **kalın** ile __kalın__, * madde imleri ile - madde imleri, iç içe listede dört boşluk girinti ile sekme. Bir oluşturucu bunların hepsini aynı çıktıya düzleştirir ve siz sinyali kaybedersiniz. Bir katkıcının gerçekten sadece bir yazım hatasını mı düzelttiğini bilmek istediğinizde cevabı kaynak diff verir.
Markdown ayrıca bir lehçe ailesidir. John Gruber'ın orijinal şartnamesi (bkz. daringfireball.net) bilinçli olarak gevşekti ve zaman içinde CommonMark, GitHub Flavored Markdown, Pandoc ve MultiMarkdown her biri farklı bir yöne çekti. Tablolar GFM ve Pandoc'ta var ama CommonMark'ta yok. ~~ ile üstü çizili ve - [ ] ile görev listeleri GFM uzantılarıdır. Diff aracı hangi lehçeyi kullandığınızla ilgilenmez; ham metni gösterir. Lehçe, bir paragrafın yeni dokümantasyon temasında hâlâ doğru oluşturulup oluşturulmadığını sorduğunuzda önemli olur ki bu, diff'in değil, oluşturucunuzun işidir.
Markdown'ı üç adımda karşılaştırın
İki metin paneli, bir diff. Kayıt yok, yükleme yok, sunucuya gidiş geliş yok.
- 1
Markdown'ınızı yapıştırın veya yükleyin
Eski sürümü sola, yenisini sağa yapıştırın. Veya bir .md, .markdown ya da .mdx dosyası yüklemek için herhangi bir panelde Yükle'ye tıklayın. Örnek düğmesi, kendi içeriğinizi yapıştırmadan önce diff'in çalıştığını görmeniz için her iki tarafa da küçük bir README örneği koyar.
- 2
Gerekirse satır sonlarını eşitleyin
Windows'ta düzenlenmiş bir dosyada genellikle CRLF satır sonu, Linux sunucusundan gelen bir dosyada ise LF bulunur. Karakter tabanlı bir diff bunları farklı sayar ve her satırı değişmiş gibi boyayabilir. Diff şüpheli derecede kırmızı ve yeşille doluysa, önce her iki dosyayı da editörünüzde aynı satır sonuna eşitleyin. VS Code, etkin satır sonunu altta durum çubuğunda gösterir.
- 3
Diff'i okuyun
Silmeler solda kırmızı, eklemeler sağda yeşil görünür. İki panel birlikte kayar. Frontmatter blokları, kod çitleri, tablo satırları ve liste ögelerinin hepsi diff motoru için sadece metindir; bu nedenle içlerindeki değişiklikler de gövde metnindeki değişiklikler gibi yüzeye çıkar. Her başlıktaki değişiklik sayıları, düzenlemenin ne kadar ağır olduğuna dair hızlı bir ölçüm verir.
Markdown diff'in doğru araç olduğu durumlar
PR dalları arasındaki README değişikliklerini incelemek
PR dalındaki README.md'nin main'e göre neyi değiştirdiğine hızlıca bakmak istiyorsunuz, ama GitHub'ı açıp oluşturulmuş önizlemenin yanından geçip üç menü derinliğindeki "Display the source diff"'e tıklamak istemiyorsunuz. Bunun yerine iki ham dosyayı bu araca yapıştırın. Başlıklar, kod çitleri ve bağlantı hedefleri net çıkar. PR aynı zamanda yüz kaynak dosyaya da dokunuyor ve dokümantasyon değişikliği gürültüde kayboluyorsa kullanışlıdır.
Yayından önce sürüm notları V1 ile V2'yi karşılaştırmak
Sürüm notları yayınlanmadan önce birkaç düzenlemeden geçer. Taslaklar yeniden sıralanır, maddeler birleşir, sürüm numaraları değişir. Daha önce yayımlanan RELEASE_NOTES.md ile yeni taslak arasında diff almak, oluşturulmuş önizlemenin yakalayamadığı düşmüş girdileri ve istenmeyen tekrarları yakalar; çünkü göz benzer görünen satırlar üzerinden kayar. Diff ayrıca ## Breaking changes bölümünün sürümler arasında gerçekten büyüyüp büyümediğini doğrulamayı kolaylaştırır.
CMS dışa aktarımını kaynak depo ile diff'lemek
Ekibiniz dokümantasyonu Git deposunda Markdown olarak yazıyor, ancak halka açık site MkDocs, Hugo veya Docusaurus gibi bir CMS ya da statik site oluşturucu tarafından üretiliyor. Bazen yayınlanan sayfa kaynaktan sapar: Birisi CMS arayüzünden canlı sayfayı düzenleyip geri push etmeyi unutmuştur veya bir CI adımı dosyayı yeniden yazmıştır. Yayınlanan sayfayı Markdown olarak dışa aktarın, bir panele bırakın, deponun .md'sini diğerine bırakın; sapma saniyeler içinde önünüzdedir.
Blog yazısı taslağı ile editör revizyonları
Bir editöre Markdown olarak blog yazısı gönderdiniz. Editör işaretlenmiş bir sürümü geri gönderdi. İki sürüm arasındaki diff, paragraf paragraf yeniden okumaktan çok daha hızlı geri bildirim almanızı sağlar; özellikle editör bölümleri yeniden sıraladığında veya girişinizi yeniden yazdığında. Yazarın hangi ses ayarlarının düzenleme aşamasından sağ çıktığını teyit etmesi gereken hayalet yazılı içerik için de aynı şekilde işe yarar.
Markdown'dan MDX'e geçişi denetlemek
Bir Docusaurus veya Astro sitesini .md'den .mdx'e taşımak zararsız bir işlem gibi görünür; ta ki bazı içe aktarımların yer değiştirdiğini, JSX bileşenlerinin eskiden düz Markdown olan tabloların yerini aldığını ve birkaç kod çitinin artık özel bileşenlerle sarıldığını görene kadar. Eski page.md'yi yeni page.mdx ile dosya bazında diff'leyin; göç kararları gözden geçirilebilir hale gelir. MDX'in hata olduğuna karar verip düz Markdown'a dönmek isterseniz aynı akış ters yönde de çalışır.
Markdown hızlı referansı
Bu aracın en sık gün yüzüne çıkardığı söz dizimi sınır durumları için kısa bir özet. Lehçe sütunu, özelliği gerçekten hangi türlerin desteklediğini söyler; çünkü oluşturucular arası sürprizlerin çoğu buradan çıkar.
| Topic | What this tool does |
|---|
| Türler arası sapma | Markdown bir ailedir. CommonMark fiili temeldir. GFM tablolar, görev listeleri, üstü çizili ve otomatik bağlantı ekler. Pandoc ve MultiMarkdown dipnotlar, tanım listeleri ve daha fazlasını ekler. Aynı kaynak bunlar arasında çok farklı oluşturulabilir. |
|---|
| Tablolar | Boru ile sınırlanmış tablolar GFM ve Pandoc'ta vardır. CommonMark'ın veya orijinal Markdown'ın parçası değildir. Bir oluşturucu hücreler yerine ham | karakterleri yazıyorsa, ayrıştırıcı CommonMark'a sıkı bağlıdır ve GFM uyumlu birine ihtiyacınız vardır. |
|---|
| Üstü çizili | ~~metin~~ bir GFM uzantısıdır. Orijinal Markdown ve CommonMark desteklemez. Pandoc, strikeout uzantısı etkinken destekler. Metniniz harfi harfine tilde'larla oluşuyorsa, oluşturucu GFM'i tanımıyor demektir. |
|---|
| Görev listeleri | - [ ] yapılacak ve - [x] tamam bir GFM uzantısıdır. CommonMark bunları parantezleri olduğu gibi bırakan basit madde imleri olarak oluşturur. GitHub, GitLab ve modern dokümantasyon sitelerinin çoğu destekler; standart Markdown işleyicileri genellikle desteklemez. |
|---|
| Kod blokları: çitli ve girintili | Çitli kod blokları (üçlü ters tırnak veya tilde, isteğe bağlı dil etiketiyle) CommonMark'tır ve evrensel olarak desteklenir. Orijinal Markdown şartnamesinde yalnızca dört boşluk girintili kod blokları vardı; bunlar hâlâ çalışır ama dil ipucu taşıyamaz. İkisini bir dosyada karıştırmak yasaldır ama dağınıktır. |
|---|
| Sert satır sonları | Üç seçenek: bir satırı sondaki iki boşluk ile bitirin, bir ters eğik çizgi \ ile bitirin (CommonMark ve GFM, orijinal değil) ya da paragraf molası için boş bir satır ekleyin. Sondaki boşluklar çoğu editörde görünmez; sert satır sonlarının kimsenin fark etmediği bir diff'ten sağ çıkmasının nedeni budur. |
|---|
| Frontmatter | Dosyanın en üstündeki --- çitleri arasında YAML, +++ arasında TOML veya { } arasında JSON. Markdown şartnamesinin hiçbir yerinde değildir, ama Jekyll, Hugo, MkDocs, Docusaurus ve Astro'da her yerdedir. Oluşturucular gövdeyi ayrıştırmadan önce çıkarır. |
|---|
| Satır içi HTML | CommonMark, Markdown içinde ham HTML etiketlerine izin verir. GFM de izin verir, ancak github.com'da oluştururken bir HTML temizleyici uygular. Bazı statik site oluşturucular temizler, bazıları HTML'i geçirir, birkaçı kaçırır. İçinde <div> veya <iframe> blokları olan sayfaların diff'leri göç denetimlerinde sıkça görülür. |
|---|
Markdown diff: sık sorulan sorular
Bu, oluşturulmuş çıktının önizlemesini gösterir mi?
Hayır. Araç, bir oluşturucunun üreteceği HTML'i değil, Markdown'ın kaynak metnini diff'ler. Bu kasıtlıdır. İki belge aynı HTML'e oluşturulurken anlamlı biçimde farklı kaynaklara sahip olabilir; örneğin * ile - arasında yazılan madde imleri ya da ** ile __ arasında yazılan kalın. Kaynak düzeyi diff bu sinyali korur. Belgenin nasıl oluştuğunu görmek istiyorsanız, her zamanki önizleyicinize yapıştırın: GitHub web arayüzü, VS Code veya statik site oluşturucunuz.
Bu, oluşturulmuş HTML'i karşılaştırmaktan nasıl farklıdır?
Oluşturulmuş HTML diff'i okuyucuların ne göreceğini söyler. Kaynak diff dosyada gerçekten neyin değiştiğini söyler. Farklı sorulara cevap verirler. Markdown için kaynak diff neredeyse her zaman daha yararlıdır çünkü yazarın düzenlemelerini sadakatle gösterir: bir başlık seviyesi ##'den ###'e değişti, çitli bir kod bloğu dil etiketini değiştirdi, göreli bir bağlantı mutlak hale geldi. HTML düzeyinde karşılaştırma istiyorsanız, iki dosyayı önce oluşturucunuzdan geçirin ve çıktıyı diff'leyin.
CommonMark ile GitHub Flavored Markdown belirsizliği ne olacak?
Diff'in kendisi Markdown'ı ayrıştırmaz, dolayısıyla hangi lehçeyi kullandığınızı umursamaz. Tablolar, görev listeleri, üstü çizili ve otomatik bağlantılar metin gibi görünür. Lehçe, belgenizin hâlâ doğru oluşturulup oluşturulmadığını sorduğunuzda önemli olur. CommonMark bir temel şartnameye en yakın olandır ve GitHub Flavored Markdown, CommonMark üzerine tablolar, görev listeleri, üstü çizili ve otomatik bağlantılar ekler. Hedef oluşturucunuz hangisini destekliyorsa onu seçin.
YAML veya TOML frontmatter'ı nasıl ele alır?
Frontmatter dosyanın en üstündeki, YAML için --- ve TOML için +++ ile çevrelenmiş bir metindir. Hugo, Jekyll ve MkDocs gibi statik site oluşturucular bunu sayfa meta verisi olarak kullanır. Diff bu bloğu sıradan metin gibi ele aldığı için title:, date: veya tags: üzerindeki değişiklikler de diğer satırlar gibi görünür. Frontmatter'ınız büyük ve girintiye duyarlıysa, o blok için tek başına YAML diff sayfası daha uygundur.
Markdown içindeki MDX veya JSX için çalışır mı?
Evet. MDX, içine JSX bileşenleri yerleştirilmiş Markdown'dır ve diff açısından JSX yalnızca biraz daha fazla metindir. Bir .mdx dosyasını herhangi bir panele yapıştırabilirsiniz; diff, içe aktarımlardaki, bileşen prop'larındaki ve çevredeki Markdown'daki değişiklikleri .md ile yaptığı gibi yüzeye çıkarır. Aracın yapmadığı tek şey JSX'inizin derlenip derlenmediğini doğrulamaktır; bu, MDX derleyicisinin işidir. JSX kısımlarının yalnızca kod incelemesi için onları metin diff'imize yapıştırın.
Satır sonları (CRLF ile LF) nasıl ele alınır?
Satır sonları karakterdir; bu nedenle Windows tarzı CRLF ile kaydedilmiş bir dosya ile Unix tarzı LF ile kaydedilmiş bir dosya her satırda farklı diff'lenir. Panelleriniz hayalet değişikliklerle dolu görünüyorsa nedeni neredeyse her zaman budur. Çözüm, yapıştırmadan önce her iki dosyayı da editörünüzde aynı satır sonuna eşitlemektir; VS Code'da etkin satır sonu altta durum çubuğunda gösterilir ve tek tıkla değiştirilir. Git'in core.autocrlf ayarı da makineler arasında sürpriz CRLF farklılıkları getirebilir.
Gizlilik ve nasıl çalıştığı
Markdown'ınız hiçbir zaman tarayıcınızdan ayrılmaz. Editör, diff ve biçimlendirici makinenizde çalışır. Girdinizde analitik yok, log yok, sunucuya gidiş geliş yok. Biçimin kendisi hakkında arka plan okuması Wikipedia'da, en güncel CommonMark şartnamesi spec.commonmark.org/0.31.2'de ve GitHub türü github.github.com/gfm'de bulunur.