Markdown Dokümanlarından CMS'e Senkronizasyon

Bu doküman, depodaki docs/ klasöründe değişen Markdown dokümantasyon dosyalarını kaynağa bağlı WebBlocks CMS dokümantasyon sayfalarına senkronize eden güvenilir AI/operatör iş akışları için bir operasyon el kitabıdır. Yalnızca dokümantasyon niteliğinde ürün rehberliğidir. Çalışma zamanında bir senkronizasyon motoru, uç nokta, migrasyon, Artisan komutu, betik, iş (job), kuyruk, veritabanı tablosu, sürüm yayınlama süreci veya herhangi bir canlı hedefe bağlantı eklemez.

Amaç

Teknik WebBlocks CMS dokümantasyonu için docs/ altındaki Markdown dosyaları doğruluk kaynağı olmaya devam eder. CMS dokümantasyon sayfaları, bu Markdown dosyalarından üretilmiş taslak veya yayında türevlerdir. İş akışı, normal ürün geliştirme sırasında yapılan dokümantasyon değişikliklerinin, CMS sayfası yetkili kopya sayılmadan bir CMS dokümantasyon sitesine yansıtılabilmesi için vardır.

Bu bir AI/operatör iş akışıdır, otomatik çalışma zamanı senkronizasyonu değildir. CMS depoyu izlememeli, Markdown dosyalarını çekmemeli veya içeriği kendi başına değiştirmemelidir. Güvenilir bir operatör ya da AI aracı, güvenli taslak güncellemelerini Internal Content API üzerinden planlar, doğrular ve isteğe bağlı olarak uygular.

Model, herhangi bir hedef CMS kurulumu veya dokümantasyon sitesi için çalışmalıdır. Dokümantasyon ve raporlar genel kalmalı; gerçek hedef site adı, gerçek alan adı, gerçek API token'ı, yerel mutlak yol, ham log veya ortam değeri içermemelidir.

Kısa Operatör Komutları

Gelecekteki operatörler şu gibi kısa istemleri kullanabilmelidir:

Update the CMS documentation site from changed Markdown files under docs/.
Plan Docs -> CMS updates for the changed docs/ Markdown files.
Validate and apply safe draft updates for changed docs/ Markdown files; do not publish.

AI/operatör bu kısa komutlardan standart iş akışını çıkarabilmelidir:

  • aday kaynak kümesi olarak docs/ altındaki Markdown dosyalarını kullanın
  • tam bir docs ağacı taraması yerine değişen dosyaları tercih edin
  • cms_sync front matter'ını ve kaynak meta verilerini okuyun
  • hedef CMS API'sini GET /webadmin/api üzerinden keşfedin
  • yalnızca keşfedilen içerik sözleşmelerini ve blok tanıtıcılarını (handle) kullanın
  • kaynağa bağlı CMS sayfalarını yoldan önce kaynak kimliğine göre eşleştirin
  • dosya başına bir plan ve doğrulama raporu üretin
  • yalnızca komut güvenli taslak uygulamayı açıkça yetkilendirdiğinde veya kullanıcı planı aynen onayladığında uygulayın
  • kullanıcı açıkça yayınlamayı istemedikçe ve token content.publish yetkisine sahip olmadıkça asla yayınlamayın

Update tek başına; planla, doğrula ve yalnızca kullanıcının talimatı uygulamayı açıkça yetkilendirdiğinde güvenli taslak değişiklikleri uygula anlamına gelir. Yayınlama, gezinme düzenlemeleri, canlı sayfanın üzerine yazma, medya içe aktarma veya tarayıcı otomasyonu anlamına gelmez.

Aday Dosya Tespiti

Hangi Markdown dosyalarının aday olduğuna karar vermek için şu sırayı kullanın:

  1. Kullanıcı açık bir dosya listesi verdiyse o listeyi kullanın.
  2. Aksi halde, depoda docs/ altındaki değişen Markdown dosyalarını kullanın.
  3. Yeni eklenen, değiştirilen ve yeniden adlandırılan .md dosyalarını dahil edin.
  4. Açıkça istenmedikçe docs/releases/ altındaki arşivlenmiş sürüm değişiklik günlüğü dosyalarını hariç tutun.
  5. Genel dokümantasyonun dışında kalan veya dahili olarak işaretlenmiş dahili AI, çalışma günlüğü, denetim veya özel planlama dokümanlarını hariç tutun.
  6. İş akışı açıkça planlama veya benimseme modunda değilse cms_sync meta verisi olmayan dosyaları hariç tutun.
  7. Tam bir docs/ yeniden taramasını yalnızca kullanıcı açıkça istediğinde çalıştırın.

Değişen dosya tespiti yalnızca bir kaynak seçim adımıdır. Git durumunu değiştirmemeli, dosyaları stage etmemeli, sürüm artefaktları oluşturmamalı veya depo remote'larından bir hedef CMS kurulumu çıkarmamalıdır.

Kaynak Meta Verileri

Markdown dosyaları front matter ile katılım sağlar:

cms_sync: true
cms_site: docs-site
cms_locale: en
cms_path: /docs/contact-forms-and-messages
cms_title: Contact Forms and Messages
cms_layout: docs
cms_source_id: webblocks-cms:docs/contact-forms-and-messages.md

Yukarıdaki cms_site örnek bir hedef site tanıtıcısıdır; gerçek bir alan adı veya kurulum adı değildir. cms_source_id kararlı kaynak kimliğidir. Bir dosya taşınırsa kaynak kimliği değişmeden kalabilir; böylece hedef sayfa yine güvenle eşleştirilebilir.

Meta veri kuralları:

  • cms_source_id kararlı kaynak kimliğidir.
  • cms_path, /docs/internal-content-api gibi kurallara uygun (canonical) Page Translation yoludur; yeni docs sayfalarının başına /p eklemeyin.
  • cms_layout yoksa varsayılan olarak docs kullanılır.
  • cms_locale yoksa varsayılan olarak en kullanılır.
  • cms_title yoksa varsayılan olarak ilk H1 veya dosya adından türetilen bir başlık kullanılır.
  • kaynak hash'i, değişiklikleri tespit etmek için kullanılan Markdown kaynak içeriğinin SHA-256 hash'idir.
  • cms_sync meta verisi yoksa dosya normal güncelleme modunda atlanır ve benimseme planlaması için raporlanabilir.

İlk benimseme, herhangi bir canlı CMS keşfi veya uygulama denemesinden önce yalnızca docs'a yönelik bir meta veri tohumlama adımı olarak yapılabilir. Bu adım, seçilen genel dokümantasyon Markdown dosyalarına güvenli ve genel front matter eklemelidir; böylece sonraki planlar kaynak kimliklerini, yolları, dilleri (locale), yerleşimleri ve başlıkları tahmin etmeden belirleyebilir. Tam bir docs/ benimseme geçişi, güvenilir bir operatör bu arşiv sayfalarını açıkça onaylamadıkça docs/releases/ altındaki arşivlenmiş sürüm değişiklik günlüklerini yine hariç tutmalıdır.

CMS Kaynak Meta Verileri

Kaynağa bağlı bir CMS sayfası, kaynak meta verilerini sayfa ayarlarında tutmalıdır. Belgelenen iş akışı için sayfa ayarları yeterlidir; ayrı bir kaynak eşleme tablosu ancak raporlama, diller arası eşleme, denetim veya büyük ölçekli operasyonlar gerektirirse daha sonra değerlendirilebilir.

Önerilen sayfa ayarları biçimi:

{
  "source_sync": {
    "type": "markdown_documentation",
    "source_id": "webblocks-cms:docs/contact-forms-and-messages.md",
    "source_path": "docs/contact-forms-and-messages.md",
    "source_sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "managed_slots": ["main"],
    "last_synced_at": "2026-06-24T00:00:00Z"
  }
}

Kaynak yolu tanımlayıcıdır. Kararlı kimlik source_id, değişiklik algılayıcısı ise source_sha256'dır. Internal Content API bu nesneyi yalnızca izin listesindeki source_sync sayfa ayarı üzerinden kabul eder, uygulamadan sonra kalıcı hale getirir ve eşleştirme için aynı güvenli alanları sayfa listesi/detay yanıtlarında döndürür. Token, ortam değeri, yerel mutlak yol, sunucu yolu veya başka gizli bilgiler saklamayın.

Sayfa Eşleştirme

Eşleştirme sırası deterministik olmalıdır:

  1. Eşleşen source_sync.source_id veya eşdeğer cms_source_id meta verisine sahip bir CMS sayfası arayın.
  2. Bulunursa source_sha256 değerini karşılaştırın.
  3. Kaynak kimliği eşleşmesi yoksa, kurallara uygun cms_path yolundaki bir sayfayı arayın.
  4. Yol, eşleşen kaynak meta verisi olmadan mevcutsa, bir benimseme veya çakışma inceleme durumu raporlayın.
  5. Yol başka bir source_id değerine aitse, çakışma raporlayın ve o dosya için durun.
  6. Yolda hiç sayfa yoksa, page.path değeri kurallara uygun cms_path olarak ayarlanmış bir create_draft_page planlayın.

İçerik karşılaştırmasını birincil eşleştirme mekanizması olarak kullanmayın. Önce kararlı kaynak kimliğine göre, ardından yalnızca benimseme veya çakışma incelemesi için yola göre eşleştirin.

Varsayılan Kararlar

Değişen Markdown dokümanları için şu varsayılanları kullanın:

  • Kaynak hash'i CMS meta verisinde değişmemişse dosyayı atlayın.
  • Eşleşen bir CMS sayfası yoksa create_draft_page planlayın.
  • Eşleşen bir taslak sayfa varsa, yönetilen sayfaya ait slotlar için replace_existing_draft_page planlayın.
  • Yalnızca eşleşen yayında bir sayfa varsa, iş akışının belgelenmiş güvenli bir taslak veya hazırlama (staging) yolu olmadıkça ve kullanıcı bu yolu açıkça onaylamadıkça doğrudan değiştirmeyin.
  • Varsayılan yönetilen slot main'dir.
  • Üstbilgi, altbilgi, devre dışı slotlar ve ortak slot atamalarını koruyun.
  • Ortak slot destekli bir slotu değiştirmeyin.
  • Gezinmeyi ayrı planlayın ve gezinme değişikliklerini varsayılan olarak uygulamayın.
  • Yayınlama, varsayılan olarak içerik uygulamanın hiçbir zaman parçası değildir.

İş akışı, yönetilen sayfaya ait slotları bu slotlar içindeki elle yapılmış CMS düzenlemelerini korumaya çalışmak yerine Markdown kaynağından yeniden üretmelidir. Kaynağa bağlı dokümantasyon sayfaları yeniden üretilebilir türevlerdir; Markdown yetkili kaynak olmaya devam eder.

Markdown'dan Bloklara Eşleme

Yapılandırılmış içeriği yalnızca hedef kurulumdan keşfedilen tanıtıcıları (handle) kullanarak oluşturun. Blok tanıtıcılarını veya benzer yazımları asla tahmin etmeyin.

Pratik eşleme kuralları:

  • H1, sayfa başlığına ve/veya bu tanıtıcı mevcut olduğunda bir content_header bloğuna eşlenir.
  • H2 ve H3, desteklenen yerlerde çapalarla (anchor) birlikte header bloklarına eşlenir.
  • Paragraflar rich-text bloğuna eşlenir.
  • Basit, biçimlendirilmemiş kısa metinler yalnızca zengin metinden daha uygun olduğunda plain_text kullanabilir.
  • Listeler, geçerli içerik sözleşmesi bir liste bloğunu destekliyorsa liste bloğuna eşlenir; aksi halde rich-text içinde kalır.
  • Tablolar mümkün olduğunda bir table bloğuna eşlenir.
  • Kod blokları (code fence) bir code bloğuna eşlenir.
  • Alıntılar, anlamlarına ve keşfedilen sözleşmelere bağlı olarak quote veya alert/callout tarzı bloklara eşlenir.
  • Normal Markdown bağlantıları zengin metin bağlantısı olarak kalır.
  • CTA benzeri bağlantılar, yalnızca bilinçli olarak eyleme yönelik olduklarında button_link olabilir.
  • Ham HTML'den kaçınılmalıdır; html yalnızca yapılandırılmış bloklar içeriği temsil edemediğinde incelemeye tabi bir yedek çözümdür.
  • Görseller ve medya indirilmemeli veya içe aktarılmamalıdır. Hedef iş akışı mevcut medya referanslarını açıkça desteklemedikçe uyarı verin.

Tek bir büyük rich-text bloğu yerine okunabilir bir dokümantasyon yapısını tercih edin. Normal bir dokümantasyon sayfası genellikle yönetilen main slotu içinde content_header veya H1'den türetilen başlık içeriği, ardından başlıklar, zengin metin, listeler, tablolar ve kod blokları kullanır.

API İş Akışı

İş akışı API öncelikli çalışır:

  1. GET /webadmin/api ile başlayın.
  2. Dönen bağlantıları OpenAPI, AI rehberi, içerik sözleşmesi, blok türleri, sayfalar, gezinme ve ortak slotlar için kullanın.
  3. Token'ın istenen mod için gereken yetkilere sahip olduğunu doğrulayın.
  4. Mevcut sayfaları ve kaynak meta verilerini API üzerinden okuyun.
  5. Sayfa planlarını yalnızca keşfedilen tanıtıcılarla oluşturun.
  6. Uygulamadan önce POST /webadmin/api/content/validate çalıştırın.
  7. Yalnızca açık onaydan sonra veya kullanıcının talimatı güvenli taslak uygulamayı açıkça yetkilendirdiğinde uygulayın.
  8. Kullanıcı açıkça yayınlamayı istemedikçe ve token content.publish yetkisine sahip olmadıkça asla yayınlamayın.
  9. API mevcutken asla tarayıcı otomasyonu kullanmayın.

API hataları iş akışı geri bildirimidir. 401, 403 ve 422 JSON yanıtlarını durma veya revize sinyali olarak ele alın, keşif/dokümantasyon bağlantılarını izleyin ve gizli bilgileri yazdırmadan güvenli, özetlenmiş durum raporlayın.

Toplu İşlem Davranışı

Birden fazla değişen doküman aday olduğunda:

  • her kaynak dokümanı bağımsız planlanmış bir sayfa güncellemesi olarak işleyin
  • operatör açıkça dosya bazlı uygulamayı seçmedikçe herhangi bir toplu işlemi uygulamadan önce tüm aday sayfa planlarını doğrulayın
  • bir dosyadaki çakışmanın diğer dosyaların başarılı planlarını gizlemeden yalnızca o dosyayı durdurmasına izin verin
  • atlanan, planlanan, doğrulanan, uygulanan, başarısız ve çakışan dosyaları ayrı ayrı raporlayın
  • yalnızca birden fazla doküman değişti diye gezinme değişikliği yapmayın
  • gezinme planlamasını ayrı ve açık bir plan olarak tutun

Toplu uygulama temkinli olmalıdır. Kullanıcı güvenli taslak uygulamayı istediyse, yalnızca doğrulanmış taslak açısından güvenli öğeleri uygulayın; çakışmaları veya inceleme durumlarını uygulamadan bırakın.

Durma Koşulları

Şu durumlarda uygulamadan önce durun:

  • API token'ı eksik, geçersiz veya iptal edilmişse
  • API keşfi başarısız olursa
  • OpenAPI, içerik sözleşmesi veya blok türleri okunamazsa
  • gerekli blok tanıtıcıları mevcut değilse
  • cms_path başka bir cms_source_id ile çakışıyorsa
  • hedef sayfa yayındaysa ve güvenli bir taslak değiştirme yolu yoksa
  • plan ortak slot destekli bir slotu değiştirecekse
  • doğrulama başarısız olursa
  • kullanıcı uygulamayı onaylamadıysa ve talimat dry-run veya yalnızca plan modundaysa

Ayrıca, kullanıcı açıkça yayınlamayı istemedikçe, plan zaten güvenle doğrulanmış/uygulanmış olmadıkça ve token content.publish yetkisine sahip olmadıkça yayınlamadan önce de durun.

Rapor Biçimleri

Dry-Run Raporu

Docs -> CMS dry-run

Source path: docs/example.md
Source id: webblocks-cms:docs/example.md
Source hash: sha256:...
Target path: /docs/example
Target locale: en
Target layout: docs
Decision: create draft | replace draft | skip | conflict | needs review
Planned managed slots: main
Warnings: none | ...
Validation result: not run
Apply result: not performed
Preview URL: not available
Publish status: not performed

Doğrulama Raporu

Docs -> CMS validation

Source path: docs/example.md
Source id: webblocks-cms:docs/example.md
Source hash: sha256:...
Target path: /docs/example
Target locale: en
Target layout: docs
Decision: replace draft
Planned managed slots: main
Warnings: ...
Validation result: passed | failed
Validation details: safe summary of API feedback
Apply result: not performed
Preview URL: not available
Publish status: not performed

Uygulama Raporu

Docs -> CMS apply

Source path: docs/example.md
Source id: webblocks-cms:docs/example.md
Source hash: sha256:...
Target path: /docs/example
Target locale: en
Target layout: docs
Decision: replace draft
Planned managed slots: main
Warnings: ...
Validation result: passed
Apply result: applied | skipped | failed
Preview URL: /webadmin/pages/{page}/preview
Publish status: not performed

Toplu işlemler için aynı alanları skipped, planned, validated, applied, failed, conflict ve needs review bölümleri altında gruplayın.

Minimal İstem Örnekleri

Yalnızca plan:

Plan Docs -> CMS updates for the changed docs/ Markdown files. Do not validate or apply.

Yalnızca doğrulama:

Validate Docs -> CMS content plans for the changed docs/ Markdown files. Do not apply.

Doğrula ve güvenli taslak güncellemelerini uygula:

Validate and apply safe draft updates for changed docs/ Markdown files; do not publish.

Tam yeniden tarama planlaması:

Plan Docs -> CMS updates for all cms_sync Markdown files under docs/. Full rescan only; do not apply.

Yalnızca gezinme planlaması:

Plan documentation navigation updates for changed docs/ Markdown files. Do not apply content or navigation.

Güvenlik ve Düzenleme Kuralları

Kaynağa bağlı dokümantasyon sayfaları CMS'te kaynak tarafından yönetilen olarak işaretlenmelidir. Gelecekteki bir düzenleme ekranı editörleri şöyle uyarabilir: "Bu sayfa Markdown kaynağından senkronize ediliyor. Bunun yerine kaynak dosyayı düzenleyin."

Kaynağa bağlı dokümantasyon sayfalarında elle yapılan CMS düzenlemeleri, yönetilen slotların bir sonraki kaynak temelli yeniden üretiminde korunmaz. Üstbilgi/altbilgi ve ortak slot atamaları, sayfaya ait yönetilen Markdown içeriği olmadıkları için korunur.

Dokümantasyon ve operatör raporları; token, gizli bilgi, yerel mutlak yol, ham log, ortam değeri, gerçek hedef site adı veya gerçek alan adı içermemelidir.