Notion — Contextator

Bir Notion çalışma alanını doğrudan API üzerinden indeksleyin: dahili bir integration ile paylaşılan her sayfa Markdown’a dönüştürülür ve senkronize tutulur. Değişen sayfalar yeniden render edilir; paylaşımı durdurulan sayfalar kaldırılır.

Bir integration oluşturmak istemiyorsanız, bir Notion Export → Markdown & CSV zip’ini de yükleyebilirsiniz — aşağıda dışa aktarım yolune bakın.

1. Bir integration oluşturun

notion.so/profile/integrations’a gidin ve dahili bir integration oluşturun.
Token’ını kopyalayın (ntn_ ya da secret_ ile başlar).

2. Sayfaları onunla paylaşın

Notion’da, indekslenmesini istediğiniz her sayfayı ya da veritabanını açın ve onu integration ile paylaşın (… → Connections → integration’ınız). Bir üst sayfayı paylaşmak, çocuklarını da paylaşır.

Bunu yapana kadar Contextator’a hiçbir şey görünmez — yepyeni bir integration hiçbir şey görmez.

3. Kaynağı ekleyin

Add source → Notion

Alan	Notlar
Name	Bağlama öneki. Değiştirilemez
Integration token	`SECRET_KEY` ile şifrelenmiş saklanır, bir daha gösterilmez
Root pages or databases	Opsiyonel. Sayfa ya da veritabanı id’leri — ya da yalnızca URL’leri, id ayıklanır. Satır başına bir tane. İntegration ile paylaşılan her şeyi almak için boş bırakın

Test connection’a basın: integration’ın kendi kullanıcısını okur ve adıyla yanıt verir (Connected as Docs Importer), böylece herhangi bir indeksleme başlamadan önce yanlış bir token belli olur.

Bir kaynak bir token saklayabilmeden önce SECRET_KEY ayarlanmış olmalıdır (32+ karakter). Bkz. Yapılandırma.

Neyin içeri alındığı

Her sayfa, üst sayfasının adını taşıyan bir klasöre yerleştirilmiş, başlığı, Notion id’si, URL’si ve last_edited_time’ı frontmatter’da olan tek bir Markdown dosyası olur:

notion/Engineering/Runbooks/Rotating the signing key.md

Render edilen blok türleri: paragraflar, üç başlık seviyesinin tümü (katlanabilir bir başlığın altına katlanmış bloklar dahil), iç içe geçmeleriyle madde işaretli, numaralı ve yapılacaklar listeleri, alıntılar, callout’lar, kod blokları, tablolar, ayraçlar, denklemler, yer imleri, görseller ve dosya bağlantıları. Bilinmeyen blok türleri, sayfayı başarısız kılmak yerine atlanır, böylece yeni bir Notion özelliği bir içe aktarımı asla bozmaz.

Kaynak başına sınırlar: 5000 sayfa ve 25 seviye iç içe geçme. İstekler saniyede yaklaşık üçe kısıtlanır, ki bu Notion’ın belgelenmiş hız sınırıdır — büyük bir çalışma alanı ilk senkronizasyonda biraz zaman alır ve sonrasında hızlıdır.

Senkronize tutmak

Her indeksleme çalışmasının başında, Contextator çalışma alanını yeniden çeker ve yalnızca last_edited_time’ı değişen sayfaları yeniden render eder. Artık paylaşılmayan ya da silinmiş bir sayfanın dosyası kaldırılır.

Notion’ın kendi push webhook’u bir git sağlayıcısının tersi yönde çalışır: URL yine de bir Notion subscription’ına yapıştırılır, başka yerdeki Push Webhook’ları ile aynı örüntü, ama sır ters yönde akar. Önce kaynağın satırından 15 dakikalık bir doğrulama penceresi açın; Notion’ın o URL’e ilk gönderimi token’ı taşır, o da doğrulamayı bitirmek için Notion’ın Webhooks sekmesine geri yapıştırılır (ADR-0049). Doğrulandıktan sonra kendi push webhook’unu sunar — ama her boşluğu kapatmaz: paylaşımı kaldırılan bir sayfa yalnızca tam bir çalışmada fark edilir. Doğrulanana kadar, ya da o boşluk için, senkronizasyon bir çalışma gerçekleştiğinde olur: kaynakta Sync’e basın, projede Re-index’e basın, ya da bir zamanlamayla POST /api/projects/:id/reindex’i çağırın — bkz. Admin API.

Bir şeyler yanlış olduğunda

Token reddedilirse, ya da yapılandırılan root sayfalarının hiçbiri okunamıyorsa, senkronizasyon başarısız olur ve bunu bildirir. Boş bir çalışma alanı bildirmez — ki bu aksi halde daha önce içeri alınan her sayfayı silerdi. Projenin diğer kaynakları yine de indekslenir, ve proje şunu bildirir:

2/3 sources synced; notion: No configured Notion root could be read — 1a2b3c4d… (object_not_found)

Bazı root’lar okunabiliyor ve diğerleri okunamıyorsa, okunabilenler içeri alınır ve başarısızlıklar bildirilir.

Belirti	Neden ve çözüm
Test connection, `unauthorized` ile başarısız olur	Yanlış ya da iptal edilmiş token. Yeni bir tane oluşturun ve yapıştırın
Kaynak hiçbir şey içeri almaz	Henüz integration ile hiçbir şey paylaşılmamış. Sayfaları paylaşın (… → Connections)
Belirli bir sayfa eksik	O — ya da üst sayfası — integration ile paylaşılmamış, ya da 25 seviyeden daha derinde
Bir root id için `object_not_found`	Id yanlış, ya da o sayfa integration ile paylaşılmamış
Bir veritabanının satırları eksik	Yalnızca içindeki sayfaları değil, veritabanının kendisini paylaşın

Dışa aktarım zip’i alternatifi

Bir integration oluşturamıyorsanız, Notion’dan dışa aktarın (… → Export → Markdown & CSV) ve zip’i içerik türü Notion export olan bir Upload files kaynağı olarak yükleyin. Notion’ın her dosya ve klasör adına eklediği 32 karakterlik sayfa id’si, yollardan ve onlara işaret eden bağlantılardan ayıklanır, ve dışa aktarımın içindeki iç içe geçmiş Part-1.zip otomatik olarak açılır.

Ödünleşim: hiçbir şey kendiliğinden senkronize olmaz — içerik değiştiğinde yeniden dışa aktarır ve yeniden yüklersiniz.