Markdown, 2004 yılında John Gruber tarafından tek, zarif bir hedefle oluşturuldu: doğal okunan düz metin yazın, sonra onu temiz HTML'ye dönüştürün. İki on yıl sonra her yerde — GitHub README dosyaları, pull request açıklamaları, Slack mesajları, Notion belgeleri, blog yazıları, AI sohbet yanıtları. Bunu bilinçli düşünüp düşünmemenizden bağımsız olarak kariyerinizin geri kalanında her gün kullanacağınız araçlardan biridir.
Markdown Gerçekte Nedir
Markdown, üzerine hafif, okunabilir sözdizimi eklenmiş düz metindir. Bir satırın başındaki # bir <h1> olur. Bir kelimeyi **çift yıldız** içine almak onu kalın yapar. Backtick'ler satır içi kod üretir. Merkezi tasarım felsefesi, Markdown kaynağının render edilmeden önce olduğu gibi okunabilir olması gerektiğidir. Eğer bir e-postayı *vurgu için yıldız işaretleriyle* yazdıysanız ya da madde listesi için tire kullandıysanız, zaten Markdown'a çok yakın bir şey yazıyordunuz.
İşte hızlı bir önce-sonra. Soldaki Markdown sağdaki HTML'yi üretir:
## Getting Started
Install the package with **npm**:
`npm install my-library`
Then import it in your project — see the [docs](https://example.com) for details.<h2>Getting Started</h2>
<p>Install the package with <strong>npm</strong>:</p>
<p><code>npm install my-library</code></p>
<p>Then import it in your project — see the <a href="https://example.com">docs</a> for details.</p>Üst yarıyı siz yazarsınız; bir Markdown işlemcisi alt yarıyı üretir. Bu dönüştürme adımı, editörünüzde veya CI pipeline'ınızda bulunduğunda görünmezdir.
Temel Sözdizimi — Her Çeşidin Paylaştığı Kısım
Hangi Markdown varyantını kullanıyor olursanız olun, bu yapı taşları her yerde çalışır:
- Başlıklar —
# H1,## H2,### H3(altı seviyeye kadar) - Kalın ve italik —
**kalın**,*italik*,***ikisi birden*** - Bağlantılar —
[bağlantı metni](https://url.com) - Görüntüler —
 - Satır içi kod —
`backtick`bir snippet sarar; üç backtick çevrilmiş kod bloğu açar - Alıntılar —
>ile başlayan bir satır - Sırasız listeler —
-veya*ile başlayan satırlar - Sıralı listeler —
1.,2.vb. ile başlayan satırlar - Yatay çizgi — üç veya daha fazla tire:
---
İşte yukarıdakilerin hepsini birlikte kullanan gerçekçi bir README parçası:
# json-transform
> A zero-dependency library for transforming JSON structures.
## Installation
```bash
npm install json-transform
```
## Usage
```js
import { transform } from 'json-transform';
const result = transform(input, schema);
```
## Features
- **Fast** — processes 10k objects/sec on average hardware
- *Typed* — ships with full TypeScript definitions
- Zero runtime dependencies
See the [full documentation](https://json-transform.dev/docs) for advanced options.
---
MIT LicenseÇeşit Sorunu — CommonMark, GFM ve Diğerleri
İşte püf nokta: "Markdown" tek bir şey değildir. Gruber'ın 2004 orijinal spesifikasyonu kasıtlı olarak gevşekti; bu da yıllarca uyumsuz uygulamalara yol açtı. Farklı ayrıştırıcılar uç durumları — iç içe geçmiş listeler, alıntı bloklarının içindeki boş satırlar, vurgu ve bağlantılar arasındaki öncelik — farklı şekillerde yönetti. Aynı kaynak dosya, farklı araçlarda farklı şekilde render ediliyordu.
CommonMark (2014'te başlatıldı) bunu düzeltti. GitHub, Stack Overflow ve Reddit'ten kişiler dahil bir grup geliştirici, 652 örneğin test paketiyle her uç durumu kapsayan titiz, belirsizliğe yer bırakmayan bir spesifikasyon yazdı. Modern araçların çoğu artık CommonMark'ı temel olarak kullanıyor.
GitHub daha sonra CommonMark'ı kendi eklemeleriyle genişletti ve GitHub Flavored Markdown (GFM)'i yayınladı. GFM, GitHub README'lerinde, sorunlarda ve pull request'lerde yazdığınız şeydir. Diğer pek çok araç da GFM uzantılarını benimsedi, ancak hepsi değil — bu nedenle GitHub'da render edilen şey statik site oluşturucunuzda veya not alma uygulamanızda aynı şekilde render edilmeyebilir. Aracınızın hangi çeşidi desteklediğini bilmek çok fazla kafa karışıklığından kurtarır.
GitHub Flavored Markdown Uzantıları
GFM, CommonMark'ın üstüne GitHub'da ve GFM üst kümesini destekleyen herhangi bir araçta sürekli kullanacağınız beş özellik ekler:
Tablolar — tire satırı ayıracına sahip boru ile ayrılmış sütunlar:
| Method | Returns | Mutates? |
|---------|---------------|----------|
| map() | new array | No |
| filter()| new array | No |
| sort() | same array | Yes |Görev listeleri — sorunlarda ve pull request'lerde onay kutuları:
- [x] Write unit tests
- [x] Update CHANGELOG
- [ ] Add migration guide
- [ ] Tag releaseÜstü çizili metin — metni çift tilde ile sarın:
~~deprecated API~~ — use `newMethod()` insteadDil ipuçlarıyla çevrilmiş kod blokları — açılan backtick'lerin ardından gelen dil tanımlayıcısı sözdizimi vurgusunu tetikler:
```python
def parse_config(path: str) -> dict:
with open(path) as f:
return json.load(f)
```Otomatik bağlantılar — https://example.com gibi yalın URL'ler, [metin](url) sözdizimi gerekmeden otomatik olarak tıklanabilir yapılır. Bu sorun yorumlarında kullanışlıdır ancak bağlantı vermek istemediğiniz bir URL yapıştırırsanız sürpriz olabilir.
Markdown'ı Pratikte Nerede Kullanacaksınız
Markdown, çoğu geliştiricinin ilk karşılaştığında beklediğinden daha fazla yerde ortaya çıkar:
- GitHub ve GitLab — README dosyaları, sorunlar, pull request açıklamaları, wiki'ler ve hatta commit mesajı gövdeleri. Dokunduğunuz her depoda en azından bir README.md bulunur.
- Statik site oluşturucular — Jekyll, Hugo, Eleventy, Astro ve Next.js'nin hepsi Markdown içerik dosyalarını kabul eder. Yazıları
.mddosyalarına yazarsınız ve oluşturucu bunları derleme sırasında HTML sayfalarına dönüştürür. - Belgeleme araçları — MkDocs, Docusaurus ve GitBook tamamen Markdown kaynağı etrafında inşa edilmiştir. Açık kaynaklı kütüphaneler neredeyse evrensel olarak bunlardan birini kullanır.
- Not alma uygulamaları — Obsidian, Notion, Bear ve Typora'nın hepsi Markdown'ı yerel formatları olarak kullanır (değişen uzantılarla). Notlarınız taşınabilir düz metin dosyalarıdır, özel bir veritabanı değil.
- CMS platformları — Ghost Markdown'ı yerel olarak kullanır. Contentful ve Strapi'nin ikisi de Markdown alanlarını destekler. Headless CMS kurulumları uzun biçimli içeriği genellikle Markdown dizeleri olarak depolar.
- AI araçları — ChatGPT ve Claude'un ikisi de varsayılan olarak Markdown çıktısı üretir. AI yanıtlarındaki kod parçacıkları, kalın terimler ve madde listeleri Markdown'dır — sohbet arayüzü bunları render eder, ancak altta yatan metin
**kalın**ve```python'dur.
Markdown vs HTML — Ne Zaman Hangisini Kullanmalı
Markdown HTML'ye dönüşür, ancak HTML'nin ifade edebildiği her şeyi ifade edemez. <div class="card">, data-* nitelikleri veya aria-* nitelikleri için eşdeğeri yoktur. Basit nesir içeriği için — belgeler, README'ler, blog yazıları, changelog'lar — Markdown daha hızlı yazılır ve ham biçiminde çok daha okunabilirdir. Karmaşık UI bileşenleri, özel düzenler veya belirli nitelikler gerektiren erişilebilirlik ek açıklamaları için HTML gereklidir.
İyi haber: çoğu Markdown işlemcisi satır içi ham HTML'ye izin verir. İkisini karıştırabilirsiniz. Bir <figcaption> ile <figure> veya bir <details> açıklama widget'ı gerekiyorsa, HTML'yi doğrudan .md dosyanıza yazın. İşlemci dokunulmadan geçirir. Bu kaçış kapısını tutumlu kullanın — dosyanızın üçte birinden fazlası ham HTML ise, doğrudan HTML yazabilirsiniz ve temiz tutmak için HTML Biçimlendirici'mizi kullanabilirsiniz.
- Markdown için kullanın: belgeler, README'ler, changelog'lar, blog yazıları, bilgi bankası makaleleri, API açıklama alanları
- HTML için kullanın: hassas düzen, özel bileşenler, formlar, belirli nitelikler gerektiren öğeler
- İkisini karıştırın: az sayıda yapısal istisna içeren ağırlıklı olarak nesir içeriği (duyarlı tablo, video yerleştirme)
Sonuç
Markdown aldatıcı derecede basittir — sadece birkaç noktalama işareti kuralı gibi görünür, ancak neredeyse her büyük açık kaynaklı projenin belgelerini destekler. Temel sözdizimini anlamak yaklaşık on dakika sürer. Çeşit farklılıklarını anlamak (CommonMark vs GFM vs SSG'nizin kullandığı) ise belge araçlarıyla zaman zaman mücadele eden geliştiricileri etmeyenlerden ayıran şeydir.
Yetkili referanslar: standartlaştırılmış spesifikasyon için CommonMark, GitHub uzantıları için GitHub Flavored Markdown ve pratik bir kopya kağıdı referansı için Markdown Guide. Günlük yazı için Markdown Önizleme'miz anında render edilmiş çıktıyı görmenizi sağlar ve Markdown Biçimlendirici kaynak dosyalarınızı tutarlı tutar.