Python ile Markdown içerik kontrolü: başlık, kod bloğu ve görsel metni taraması

Uzun bir teknik yazıda tek bir kapanmamış kod bloğu, sayfanın geri kalanını kod gibi gösterebilir. Boş görsel açıklaması veya unutulan ana başlık da yayın kalitesini düşürebilir. Bu rehberde Markdown metninin bazı mekanik özelliklerini kontrol eden küçük bir Python aracı hazırlıyoruz. Araç yazının doğru, özgün veya iyi anlatılmış olduğuna karar vermez. Editöre tekrar bakılacak noktalar verir; içerik değerlendirmesi insanın sorumluluğunda kalır.

1. Kontrol ile puanlamayı ayırın

Örneğimiz tek bir H1 başlığı, yeterli bölümleme, kapanmış kod çitleri ve boş olmayan görsel alternatif metni arar. “En az dört H2” gibi sınırlar bu çalışma için seçilmiş editoryal kurallardır; Google’ın zorunlu talebi değildir. Kısa bir haberin dört H2’ye ihtiyacı olmayabilir. Betiği yayın türüne göre uyarlayın. Bir sayı yüzünden gereksiz paragraflar eklemek yerine yazının okuyucuya hangi işi yaptırdığını değerlendirin.

2. Deneme dosyasını hazırlayın

Boş bir klasörde rehber.md dosyası oluşturun. İçine başlık, iki paragraf, bir bağlantı ve kısa bir kod bloğu yazın. Betiğin yalnızca bu dosyayı okuduğundan emin olun. İsterseniz kontrolün nasıl çalıştığını görmek için bir kopyada son üç ters tırnağı kaldırın. Orijinal metni bozmadan hata örneği üretmek, kontrol aracını anlamanın pratik yoludur.

3. Basit kalite kontrol kodu

Aşağıdaki kodu md_kontrol.py adıyla kaydedin ve python md_kontrol.py rehber.md komutuyla çalıştırın. Markdown’un bütün dil özelliklerini çözümleyen tam bir ayrıştırıcı değildir. Özellikle tırnak içindeki örnekler, HTML görselleri veya girintili kod blokları için daha gelişmiş araç gerekebilir.

from pathlib import Path
import re
import sys

path = Path(sys.argv[1] if len(sys.argv) > 1 else 'rehber.md')
text = path.read_text(encoding='utf-8-sig')
lines = text.splitlines()
inside = False
prose = []
for line in lines:
    if line.lstrip().startswith('```'):
        inside = not inside
        continue
    if not inside:
        prose.append(line)
plain = '\n'.join(prose)
h1 = re.findall(r'^#\s+.+$', plain, flags=re.M)
h2 = re.findall(r'^##\s+.+$', plain, flags=re.M)
words = re.findall(r'\b[\wÇĞİÖŞÜçğıöşü]+\b', plain)
images = re.findall(r'!\[([^\]]*)\]\(([^)]+)\)', plain)
issues = []
if len(h1) != 1:
    issues.append(f'H1 sayısı {len(h1)}; editör kontrol etsin.')
if len(h2) < 4:
    issues.append('Bölümleme az; bu yayın türü için yeterli mi?')
if inside:
    issues.append('Kapanmamış üç ters tırnaklı kod bloğu var.')
for alt, url in images:
    if not alt.strip():
        issues.append('Boş görsel açıklaması: '+url)
print('Sözcük:', len(words), '| H2:', len(h2), '| Görsel:', len(images))
print('\n'.join(issues) if issues else 'Bu basit kontrollerde uyarı yok.')

4. Sözcük sayısını doğru okuyun

Kod bloklarının uzunluğu yazıyı yapay biçimde uzun göstermesin diye bu örnek, çit içindeki satırları sözcük hesabından çıkarır. Yine de bağlantı URL’leri veya bazı işaretler sonucu etkileyebilir. Sayıyı yaklaşık bir gösterge olarak kullanın. Bir rehberin altı yüz kelime olması her adımının anlaşılır olduğunu kanıtlamaz. Kullanılan dosya adları, gereken kurulum ve beklenen çıktı gibi bilgiler eksikse uzun metin de uygulamayı zorlaştırabilir.

5. Görsel açıklamasını içerikle eşleştirin

Boş olmayan her alternatif metin iyi değildir. “Görsel 1” yerine “Üç sahnenin sırasını gösteren video üretim akışı” gibi açıklayıcı bir metin daha yararlıdır. Dekoratif görsellerin erişilebilirlikte farklı ele alınabileceğini de unutmayın; betik bu ayrımı yapamaz. Eğitim görselindeki kritik bilgi yalnızca resmin içinde kalmasın. Adımları metinde de anlatın. Görsel gerçek uygulama ekranı değilse bunu açıklamada belirtin.

6. Kod örneğinin kontrolü ayrı yapılır

Betiğin kapanmış bir kod bloğu bulması kodun çalıştığı anlamına gelmez. Python örneğini ayrı bir geçici klasörde deneyin; girdi dosyasını oluşturun ve beklenen çıktıyla karşılaştırın. Komut dosya siliyor veya üzerine yazıyorsa bu davranışı metinde açıkça anlatın. API anahtarlarını örnek kodda sabit yazmayın. Kullanıcıdan gereken değerleri, gerçek bir sır içermeyen açıklayıcı değişkenlerle gösterin. Teknik yazının güvenilirliği yalnızca biçim kontrolünden gelmez.

7. Editör kararını kaydedin

Uyarıları düzeltirken hangi kuralın gerçekten geçerli olduğunu düşünün. Kısa bir duyuruda bölüm sayısı uyarısını kabul edilebilir bulabilirsiniz; kapanmamış kod bloğunu ise yayın öncesi düzeltmelisiniz. Son dosyayı tekrar kontrol edip sayfanın tarayıcıdaki görünümüne bakın. Özellikle mobilde uzun kod satırlarının sayfayı yatay taşırmaması gerekir. Bu küçük araç, kontrol listesinin düzenli uygulanmasını sağlar; yazının doğruluğunu kaynakları okuyarak ve örnekleri deneyerek tamamlayın.

İlgili okumalar

• Python ile dosya SHA-256 özeti: video tesliminde bütünlük kontrolü
• Python ile görselleri topluca WebP’ye dönüştürme: boyut, kalite ve yön kontrolü

Bu uygulamayı forumda tartışın.