İçerik Türleri

Başka bir araçtan dışa aktarılmış dokümantasyon Markdown’dır, ama o aracın kendi sözdizimini taşır. Bir kaynağın içerik türü — bazen kendi çeşidi (flavor) olarak da anılır — küçük bir dönüşüm uygular, böylece bir ajan, dosya nereden geldiğine bakmaksızın düz Markdown okur. Dosyalarınız asla değiştirilmez: ne bağlanan klasör, ne git checkout’u, ne de yüklenen ağaç.

Önce her dosya Markdown olur — bir istisna

Bir içerik türü hiç çalışmadan önce, bir kaynağın okuduğu her dosya kendi dosya türüne göre Markdown’a dönüştürülür: .html/.htm, .docx, .pdf ve .csv her biri dönüştürülür; .md, .mdx ve .txt zaten metin oldukları için değişmeden geçer. Bir Confluence sayfasının ya da crawl edilmiş bir dokümantasyon sitesi sayfasının da Markdown olarak gelmesini sağlayan budur — bkz. Confluence ve Dokümantasyon Sitesi Kaynağı. Aşağıdaki içerik türü, o Markdown’a uygulanan ikinci bir dönüşümdür ve dosyaların hangi formatta olduğundan çok nereden geldiğine bağlıdır.

Tek istisna OpenAPI / Swagger’dır: bu içerik türü altındaki bir .yaml, .yml ya da .json spesifikasyonu hiçbir zaman Markdown’a dönüştürülmez. Yapılandırılmış veri olarak okunur ve doğrudan operasyon başına bir belgeye render edilir — aşağıya bakın.

Dört içerik türü

Add source bunu kaynak başına seçer: panonun Obsidian vault sekmesi sizin için Obsidian içerik türünü seçer; bir Notion export zip’i, sekme bunu ima etmediği için Notion export’un açıkça seçildiği Upload files’a ihtiyaç duyar; OpenAPI / Swagger her zaman bilinçli olarak seçilmelidir. Bkz. Belge Kaynakları.

Obsidian vault

Her wikilink biçimi standart bir Markdown linkine dönüşür, > [!NOTE] > **Note:** olur, böylece callout türü düz metinde aranabilir kalır, ve %%comments%% kaldırılır. Yeniden yazımların tam tablosu Obsidian Vault’ları sayfasındadır.

Notion export

Bir Notion export zip’i, dosyaları ve klasörleri şöyle adlandırır:

Getting started 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d.md
Engineering 9f8e7d6c5b4a39281706f5e4d3c2b1a0/Runbook 0a1b2c3d….md

Notion export seçildiğinde, 32 karakterlik id her yol segmentinden ve bu dosyalara işaret eden linklerden kaldırılır, bu yüzden belgeler şöyle okunur:

Getting started.md
Engineering/Runbook.md

Bir export zip’i yerine canlı API için bunun yerine bir Notion kaynağı kullanın — bir API yanıtından kaldırılacak bir id olmadığı için hiçbir içerik türüne ihtiyaç duymaz.

OpenAPI / Swagger

Bu, tek başına bir dönüşümün yapamayacağı bir şeyi yapan tek içerik türüdür: bir dosyanın tek bir belge olmadığını söyler. Bir spesifikasyon, her (method, path) operasyonu için bir belge olarak indekslenir — yol, method, özet, parametreler, istek ve yanıt şemaları ve örnekler, her biri kendi başlığının altında — bu yüzden bir arama sonucu GET /pets/{petId} > Responses > 200 gibi bir kırıntı taşır ve search_docs, dosyayı değil, endpoint’i döndürür.

• .yaml, .yml ve .json yalnızca bu içerik türü altında seçilebilir. Hiçbir uzantı tek başına bir spesifikasyonu ima etmez — bir .yaml bir Helm values dosyası ya da bir CI yapılandırması da olabilir — bu yüzden bu içerik türünü seçmek, o uzantıları yalnızca o kaynakta okunabilir kılan şeydir.
• Her belge <file>/<method>-<path> adresinde saklanır, ör. api/petstore.yaml/get-pets-petId. Yol yalnızca method’dan ve URL yolundan gelir, bu yüzden aynı spesifikasyonu, yeniden biçimlendirilmiş olsa bile, yeniden indekslemek aynı belgelere iner.
• $ref dosya içinde çözümlenir. Özyinelemeli bir şema, kendine geri işaret ettiği yere kadar render edilir ve bunu söyler; sekiz seviyeden derini durduğu yeri söyler. Başka bir dosyaya bir referans, izlenmek yerine adlandırılır.
• Spesifikasyonların yanındaki Markdown, Markdown olarak kalır — aynı kaynaktaki bir README.md yine sıradan bir belgedir.
• Geçerli bir spesifikasyon olmayan bir dosya, adıyla reddedilir, dönüştürülemeyen bir PDF ile aynı şekilde — sebep kaynağın satırında gösterilir ve kaynağın geri kalanı normal şekilde indekslenir. Bir render edicinin başarısız olması için yazılmış bir dosya da öyledir, kendine referans veren bir örnek ya da çözülmeyecek bir $ref gibi: bir spesifikasyonun içerebileceği hiçbir şey çalıştırmanın tamamını başarısız kılmaz.
• OpenAPI 3’ün yanı sıra Swagger 2.0 da okunur, definitions, in: body parametreleri ve host/basePath dahil; kendisi bir $ref olan bir 3.1 path item’ı izlenir.
• Bir spesifikasyon, okunmadan önce MAX_SPEC_FILE_BYTES (8 MiB)’a karşı ölçülür — dönüştürülmüş dosyalar için olandan çok daha düşük kendi tavanı, çünkü birini ayrıştırmak, o dosya indekslenirken bellekte tutulan, dosyanın boyutunun yaklaşık elli beş katı büyüklüğünde bir nesne grafiği üretir. Varsayılan tavanda bu, bir spesifikasyon indekslenirken kabaca 400 MB heap demektir; bunu karşılayamayan bir konteynerde değişkeni düşürün. Bkz. Yapılandırma.
• Render edilen bir belge 2.000 satırla, bir spesifikasyon ise 5.000 operasyonla sınırlıdır. İkisi de gerçek bir API tarafından ulaşılabilir değildir — en büyük yayımlanmış spesifikasyonlar kabaca bin operasyona çıkar — ve ikisi de var olma nedenini, dosya boyutu tavanının ayrıştırmayı sınırlaması ama bir dosyanın neye render edilmek istediğini sınırlamamasından alır.
• Aynı API’nin bir projedeki iki sürümü çakışmaz: her spesifikasyonun kaynağına bir sürüm verin, ve v2/openapi.yaml/get-pets ile v3/openapi.yaml/get-pets, search_docs’un version filtresinin ayırt ettiği ayrı belgeler olur.

İçerik türünü sonradan değiştirmek

Bir kaynağı düzenleyip başka bir içerik türü seçmenin bilinmeye değer bir inceliği var: Contextator, her dosyanın ham byte’larını, iki dönüşüm de çalışmadan önce hash’leyerek neyin yeniden gömüleceğine karar verir. Yalnızca içerik türünü değiştirmek, byte’ları değişmemiş bir dosyaya asla dokunmazdı — bu yüzden bunun yerine, onu değiştirmek o kaynağın saklanan hash’lerini düşürür ve bir indeksleme çalıştırması kuyruğa alır, ve her dosya yeni dönüşümle yeniden işlenir. Bunun pratik sonucu, büyük bir kaynağın içerik türünü değiştirmenin onun tam bir yeniden gömülmesine mal olması, başka herhangi bir şeyi değiştirmenin ise olmamasıdır.

Doğrusunu seçmek

• Şüpheniz varsa, bir kaynağı Plain Markdown / text’te bırakın — diğer dönüşümler yalnızca kendi sözdizimleri gerçekten mevcut olduğunda yardımcı olur ve sıradan Markdown’ı asla iyileştirmez.
• Bir Notion export zip’i, bir Upload kaynağında açıkça seçilmiş Notion export’a ihtiyaç duyar; hiçbir şey bunu dosya adlarından çıkarmaz.
• OpenAPI / Swagger bilinçli olarak seçilmelidir, ve o kaynakta .yaml, .yml ve .json’ı File types’ta seçilebilir kılan şey budur.