Dokümantasyon linkleri neden sessizce kırılır?
Bir mühendis `docs/setup.md` dosyasını yeniden adlandırdığında ya da bir başlığı `## Authentication` yerine `## Token Setup` yaptığında testler ve derleme hâlâ yeşil kalır. Kod tarafındaki tüm kontroller geçse bile README içindeki `#authentication` çapası artık hiçbir yere gitmez.
Klasik HTTP tabanlı link tarayıcılar ise pull request aşamasında iki açıdan yetersiz kalır: yerel göreli yolları ve GitHub Flavored Markdown (GFM) başlık çapalarını çoğu zaman atlarlar; ayrıca hız limitleri (429/403) yüzünden CI koşumlarını gereksiz yere kırarlar.
1. Adım: Yerel linkleri, görselleri ve #çapaları çevrimdışı doğrulayın
En sağlıklı CI kapısı; ağ isteği yapmadan çalışan, yalnızca repo içindeki Markdown dosyalarını, göreli görsel yollarını ve GFM başlık slug'larını (`emoji`, noktalama, Türkçe/Unicode ve yinelenen `-1`, `-2` başlık ekleri dahil) doğrulayan deterministik katmandır.
Sıfır bağımlılıklı Python CLI aracı `deadlinkfinder`, bozuk hedefi bulmakla kalmaz; `difflib` tabanlı yakın eşleşme ile büyük olasılıkla kastettiğiniz dosya veya `#anchor` adını da önerir.
pip install deadlinkfinder
# Repo genelindeki yerel Markdown linkleri, görselleri ve #başlık çapalarını tara
deadlinkfinder check .
# Yalnızca docs klasörünü JSON çıktısıyla ve isteğe bağlı dış URL kontrolüyle tara
deadlinkfinder check docs/ --format json --external2. Adım: GitHub Actions + SARIF ile PR satırında uyarı verin
Kontrolü `pull_request` iş akışına bağlayıp `--format sarif` çıktısını `github/codeql-action/upload-sarif` adımına verdiğinizde kırık linkler doğrudan PR diff'inde ilgili satır parmak iziyle görünür.
Günlük geliştirme akışında dış URL kontrolünü haftalık zamanlanmış bir job'a ayırıp her PR'da sadece çevrimdışı kontrol çalıştırmak, sıfır ağ kırılganlığıyla birkaç saniyede sonuç almanızı sağlar.
name: Markdown Link Check
on:
pull_request:
paths:
- "**/*.md"
- "docs/**"
jobs:
links:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- run: pip install deadlinkfinder && deadlinkfinder check .
- name: Generate SARIF report
if: always()
run: deadlinkfinder check . --format sarif > links.sarif
continue-on-error: trueKaynak: DeadLinkFinder proje sayfası ve mimari notları
Kaynak: PyPI: deadlinkfinder paketi
