Bu kılavuz docs/wiki/ içindeki wiki'ye, dokümantasyon standardını (docs/wiki/_standard/DOC_STANDARD.tr.md) karşılayacak ve durağan HTML sitesine derlenecek biçimde yeni bir sayfa ekler veya var olanı günceller. Yerleşimi, ön bilgiyi, atıfları, uyarı kutularını, şemaları, Türkçe ikizi ve derleme betiği docs/wiki/_build/build.py dosyasını kapsar. Kuralların tamamı standartta ve stil denetim listesinde (docs/wiki/_standard/STYLE_CHECKLIST.md) yer alır; bu sayfa çalışma sırasıdır.
Ön koşullar¶
- Dokümantasyon standardını (
docs/wiki/_standard/DOC_STANDARD.tr.md) ve bilgi mimarisini (docs/wiki/_standard/INFORMATION_ARCHITECTURE.tr.md) okuyun. - Derleme için:
markdown,pygmentsveyamlpaketleriyle Python (docs/wiki/_build/build.py:22-23,docs/wiki/_build/build.py:37-41). Şemalar için:docs/wiki/_build/içindenpm installile kurulan Mermaid paketi (docs/wiki/_build/package.json,docs/wiki/_build/build.py:524-528).
Adımlar¶
- Bilgi mimarisinde sayfanın satırını bulun. Satır klasörü, dosya adını ve sayfa türünü verir. Uygun satır yoksa bir satır ekleyin ve değişikliğinizde belirtin.
- Sayfa türünün şablonunu ve
.tr.mdikizinidocs/wiki/_standard/templates/klasöründen kopyalayın. Bir karar kaydı, "Bağlam", "Karar", "Sonuçlar", "Kodun uyguladığı yerler" ve "İlgili sayfalar" başlıklarıyla açıklama şablonunu kullanır. - Ön bilgiyi doldurun.
title,description,lang,type,section,stage,verified_commitveverified_datezorunludur;audienceisteğe bağlıdır. Derleme bloğu YAML olarak ayrıştırır ve ayrışmazsa bir hatayla durur (docs/wiki/_build/build.py:181-194).
```yaml
title: Event bus description: How modules exchange events and queries through the EventBus without importing each other. lang: en type: explanation section: platform stage: 2 audience: developer verified_commit: 92f8051 verified_date: 2026-11-09
```
- Başlığa eşit tek bir H1, ardından iki ila dört cümlelik bir özet yazın. Derleme ilk H1'i gövdeden çıkarır ve başlığı sayfa üst bilgisinde çizer (
docs/wiki/_build/build.py:337-338). - Anlattığınız her dosyayı açın ve varsa sembol adıyla birlikte satır içinde
path:lineveyapath:start-endolarak atıf yapın. Kodun yanıt vermediği yerde "Koddan belirlenemedi." yazın ve neyi aradığınızı söyleyin. Kod ile projenin yazılı mühendislik kuralları çeliştiğinde bir tutarsızlık uyarısı yazın. - Yalnız üç uyarı kutusunu kullanın:
> **Note:**,> **Warning:**ve> **Tip:**. Derleme bunları ve Türkçe biçimleriNot,Uyarıveİpucuetiketlerini biçimli kutulara çevirir (docs/wiki/_build/build.py:121-125,docs/wiki/_build/build.py:278-299). - Şemaları
mermaidçitli blokları olarak çizin ve içeriklerini düzyazıyla yineleyin. Derleme bu blokları Markdown çiziciden uzak tutar ve tarayıcıda Mermaid'e verir (docs/wiki/_build/build.py:225-246). - Diğer sayfalara
.mddosyalarına giden göreli yollarla bağlantı verin. Derleme bunları.htmlolarak yeniden yazar ve hedef sayfası olmayan her bağlantıyı bildirir (docs/wiki/_build/build.py:249-275). Türkçe sayfalar.tr.mddosyalarına bağlanır. - Yeni terimleri "Tanıtılan terimler" tablosuna, ardından "İlgili sayfalar" listesini, ardından ön bilgiyle aynı commit ve tarihi taşıyan alt bilgi satırını ekleyin.
- Türkçe ikiz
name.tr.mddosyasını aynı klasörde aynı yapıyla yazın: aynı başlıklar, tablolar, satırlar, uyarı kutuları, kod blokları ve atıflar. Derleme dosyaları gövde adına göre eşler ve bir dil geçişi sunar (docs/wiki/_build/build.py:197-200,docs/wiki/_build/build.py:555-556). -
Siteyi depo kökünden derleyin:
bash python docs/wiki/_build/build.pyÇıktı
docs/wiki/_siteklasörüne gider;--outbaşka bir klasör seçer ve--site-rootbir ürün sayfasına geri bağlantılar ekler (docs/wiki/_build/build.py:613-617).
Sonucu doğrulayın¶
Derleme dil başına sayfa sayısını, ardından eksik bir sayfayı gösteren her bağlantıyı yazar (docs/wiki/_build/build.py:603-609). Ayrıca her sayfanın başlığını, bölümünü, alt başlıklarını, açıklamasını ve ilk 4.000 karakterini içeren istemci tarafı bir arama dizini yazar (docs/wiki/_build/build.py:583-590, docs/wiki/_build/build.py:602). Sayfa ana hattı H2 ve H3 başlıklarını kapsar (docs/wiki/_build/build.py:329). Yeni sayfayı docs/wiki/_site içinde açın ve dil geçişini, ana hattı ve şemaları denetleyin. Ardından stil denetim listesini (docs/wiki/_standard/STYLE_CHECKLIST.md) uygulayın.
Sorun giderme¶
| Belirti | Koddaki neden | Çözüm |
|---|---|---|
| Derleme "front matter does not parse" ile durur | yaml.safe_load bir hata fırlattı (docs/wiki/_build/build.py:188-191) |
YAML'ı düzeltin, örneğin iki nokta içeren bir değeri tırnağa alın |
| "mermaid.min.js not found" uyarısı; şemalar metin olarak görünür | Mermaid paketi _build/node_modules içinde yok (docs/wiki/_build/build.py:524-528) |
docs/wiki/_build/ içinde npm install çalıştırın |
| Bir bağlantı "links point at pages that do not exist yet" altında listelenir | Göreli hedef bilinen bir sayfa değil (docs/wiki/_build/build.py:267-268) |
Yolu düzeltin; derleme yine de 0 koduyla çıkar (docs/wiki/_build/build.py:610) |
| Bir bölüm gezinmenin sonunda görünür | Kısa adı SECTIONS içinde yok (docs/wiki/_build/build.py:56-69) |
Var olan bir bölüm kısa adı kullanın |
Tanıtılan terimler¶
| Terim | Kod tanımlayıcısı | Tanım | Türkçe terim | Kaynak |
|---|---|---|---|---|
| Turkish twin | name.tr.md |
Bir İngilizce sayfayla aynı gövde adını ve aynı yapıyı taşıyan Türkçe sayfa. | Türkçe ikiz | docs/wiki/_build/build.py:197-200 |
| admonition | ADMONITION_WORDS |
Kalın bir Note, Warning veya Tip etiketiyle başlayan ve kutu olarak gösterilen alıntı bloğu. | Uyarı kutusu | docs/wiki/_build/build.py:121-125 |
İlgili sayfalar¶
- Katkı
- Dokümantasyon standardı (
docs/wiki/_standard/DOC_STANDARD.tr.md) - Stil denetim listesi (
docs/wiki/_standard/STYLE_CHECKLIST.md) - Sözlük
- Karar kayıtları
92f8051 numaralı commit ile 2026-11-13 tarihinde doğrulandı.