Yerel Klasör Kaynağı

Sunucuda zaten var olan — konteynere bağlanmış — bir klasör, olduğu yerde taranır. Hiçbir şey kopyalanmaz, hiçbir şey değiştirilmez, ve düzenlemeler bir sonraki indeksleme çalıştırmasında ortaya çıkar.

Bu en basit kaynaktır ve dokümantasyon zaten makinedeyse doğru olanıdır: bir repository checkout’u, senkronize bir klasör, bir ağ paylaşımı, aynı sunucudaki bir Obsidian vault’u.

Klasörü konteynere görünür yapmak

Konteyner yalnızca bağladığınızı görebilir. Compose ile, DOCS_HOST_PATH salt okunur olarak /docs’a bağlanır:

# .env
DOCS_HOST_PATH=/srv/documentation

Birden fazla klasör bağlamak için, bunları docker-compose.yml’e ekleyin ve ALLOWED_DOC_ROOTS’ta listeleyin:

volumes:
  - /srv/documentation:/docs:ro
  - /srv/handbook:/handbook:ro

ALLOWED_DOC_ROOTS=/docs,/handbook

Kaynağı eklemek

Add source → Local directory

Alan	Örnek	Notlar
Name	`handbook`	Bu klasörden gelen her yolun mount öneki. Değiştirilemez
Directory	`/docs/` + `handbook`	Pano, izin verilen kökü bir önek olarak gösterir; gerisini siz yazarsınız
Content type	`Plain Markdown / text`	Bir vault için `Obsidian vault` — bkz. Obsidian Vaults — bir spesifikasyon klasörü için `OpenAPI / Swagger` seçin
File types	`.md`, `.mdx`	İsterseniz `.txt`, `.html`/`.htm`, `.csv`, `.docx` ya da `.pdf` ekleyin — ilk üçü dışındaki her şey indekslenirken Markdown’a çevrilir

Birden fazla izin verilen kök yapılandırıldığında, önek bir dropdown’a döner.

Allowed-roots kuralı

Bir local kaynağın klasörü mutlaka ALLOWED_DOC_ROOTS’tan birinin içinde çözümlenmelidir. Yol önce symlink’ler üzerinden çözülür, bu yüzden:

.. ile kaçışlar reddedilir;
izin verilen bir kökün dışına işaret eden bir symlink reddedilir;
bir klasör olmayan bir yol reddedilir.

“Directory is outside the allowed document roots” görürseniz, ya izin verilen bir kök altında bir yol kullanın (Docker içinde bu /docs/... demektir), ya da kökü ALLOWED_DOC_ROOTS’a ekleyip yeniden başlatın.

Bu bir kolaylık kontrolü değil, gerçek bir güvenlik sınırıdır — bkz. Güvenlik.

Ne taranır

Klasörden başlayarak, özyinelemeli olarak:

yalnızca kaynağın seçtiği dosya türleri;
gizli dosyalar, gizli klasörler, node_modules, dist, build, vendor, __pycache__ atlanır;
klasörün dışına kaçan symlink’ler atlanır;
IGNORE_GLOBS desenleri atlanır.

Yollar yapılarını korur ve kaynak adını kazanır: handbook adlı bir kaynağın içindeki guides/install.md, handbook/guides/install.md olarak indekslenir, aranır ve okunur.

Güncel tutmak

Çekilecek bir şey yoktur — klasör indeksleme anında okunur. Dosyalar değiştiğinde bir çalıştırmayı tetikleyin:

kaynak satırında Sync, ya da proje başlığında Re-index;
ya da bir cron job’dan veya CI adımından POST /api/projects/:id/reindex — bkz. Admin API.

İndeksleme artımlı olduğu için, sık çalıştırmak ucuzdur: değişmeyen dosyalar hash ile atlanır.

Salt okunur mount’lar

Dokümantasyonunuzu, gönderilen compose dosyasının yaptığı gibi salt okunur (:ro) bağlayın. Contextator hiçbir zaman bir local kaynağa yazmaz, ve mount bu garantiyi yapısal hâle getirir.