Kimin için

API dokümanlarını kodu bozulmadan kaydedin

Clean Clipper kod bloğunun dilini sayfanın kendi işaretlemesinden okur ve etiketi bloğa yazar, böylece not yapıştırıldığı yerde renklenir. Dokuz sayfalık teknik bir korpusta etiket 156 bloğun 73’ünde korundu; karşılaştırılan iki motorda 20 ve 0. Parametre tabloları da tek satıra çökmeden geçer.

Dokümantasyonun asıl kısmı düşüyor

Bir API sayfasını kaydedersiniz, notu ertesi gün açarsınız ve kod tek renk bir metin yığınına dönmüştür. Dilin gittiğini fark etmek için genellikle geç olmuştur: kaynağı çoktan kapatmış, arkasından on sayfa daha kaydetmişsinizdir. Dokümantasyonun anlamı büyük ölçüde koddadır ve pek çok clipper tam o kısmı sıradan bir paragraf gibi taşır.

İkinci sorun tablolar. Parametre ve dönüş değeri tabloları hücrelerinde kod, liste ve bağlantı taşır; genel HTML’den Markdown’a dönüştürücüler tam o hücrelerde kırılır ve satır tek bir cümleye çöker. Sonuç, okumak için özgün sayfaya dönmeniz gereken bir nottur – yani kaydetmenin bütün anlamını yitiren bir dosya.

Üçüncüsü sürüm sorunu. Dokümantasyon sürümlenir, adres çoğu zaman sürümlenmez: v4 için okuduğunuz sayfa sessizce v6’ya döner, bir bayrağın adı değişir, bir seçenek kaldırılır – yer imi hâlâ açılır, ama artık başka bir metni açar. Notlarınızda hangi sürüme göre yazdığınızı kaydeden hiçbir şey yoktur. Başlığında kaynak adresi ve sayfanın kendi tarihi duran bir dosya bu soruyu bir yıl sonra da yanıtlar; yer imi hiçbir zaman yanıtlamaz.

Kaydettikten sonra ne değişir

• Blok ```js olarak çıkar, çıplak değil – Obsidian, VS Code ve GitHub’ta yapıştırdığınız anda renklendirme çalışır
• Dil koddan tahmin edilmez: sitenin renklendiricisinin bıraktığı sınıf okunur, etiket kaynak sayfa kadar doğrudur
• Hücresinde kod ya da liste olan parametre tabloları satırını yarmıyor – teknik korpusta on beş tablonun on ikisi korundu
• JavaScript ile çizilen dokümantasyon siteleri gördüğünüz gibi alınır; DOM çizim bittikten sonra okunur
• Ölçülen 512 sayfanın çıktısında tek bir artık HTML etiketi yok – notun ortasında div kalmıyor
• Kaynak adresi frontmatter’da durur, bir davranışın nereden geldiği her zaman izlenebilir
• Şartname sayfalarındaki referans bağlantıları [^1] dipnotuna dönüşür, tanımları dosyanın sonuna toplanır
• extraction alanı gövdenin hangi yoldan alındığını söyler: dom ya da sayfa metnini yalnızca yapılandırılmış veride yolladıysa jsonld-articlebody

JSON API şuna benzer bir veri döndürür:

```js
[
  { category: "Fruits", price: "$1", stocked: true, name: "Apple" },
  { category: "Vegetables", price: "$2", stocked: true, name: "Spinach" }
]
```

## Adım 1: Arayüzü bileşen hiyerarşisine bölün

Dokümantasyon için kurulum

Bir kez altı dakika, sonrasını kısayol halleder. Öntanımlı değerler makale okumak için ayarlıdır; dokümantasyon başka bir dosya adı, yazar alanı olmayan bir başlık ve görselsiz bir çıktı ister.

1. Eklentiyi kurun ve simgesini araç çubuğuna sabitleyin. Simgeye sağ tıklayıp Seçenekler’i açın; ayarlar ayrı bir sekmede açılır.
2. Simge tıklaması ayarını “klasöre kaydet” yapın. Kaydı tek tuşa indiren şey budur; önizleme penceresi aracı öğrenirken yararlı, sonrasında yoldadır.
3. Klasörü seçin. Sürüm denetiminde zaten tuttuğunuz bir dizini gösterin, örneğin çalıştığınız deponun içindeki docs/clips. Tarayıcı izni bir kez sorar ve o profil için hatırlar.
4. Dosya adı şablonunu {domain}-{title} yapın. Dört ayrı çatının dördünde de “Başlarken” adlı bir sayfa vardır; adında alan adı olmazsa dördüncüsü sessizce baslarken-4 olur.
5. Frontmatter bölümünde source ve extraction alanlarını açık bırakın, author alanını kapatın. Dokümantasyon sayfaları çoğu zaman imzasızdır; her dosyada boş duran bir alan sonunda elle temizleyeceğiniz gürültüdür.
6. Görselleri atla yapın. Başkasının editör ekran görüntüsü grep ile aranmaz, bağlantısı da taşınacak bir CDN’i gösterir.
7. chrome://extensions/shortcuts adresini açıp Alt+Shift+M kısayolunun bağlı olduğunu doğrulayın. Başka bir eklenti almışsa geri alacağınız yer burasıdır.

Geliştiriciye uygun ayarlar

Öntanımlıdan değiştirmeye değen değerler bunlar. Üçüncü sütun, her birinin genel olarak okumak için değil, özellikle dokümantasyon için neden böyle olduğunu söylüyor.

| Parametre | Tür | Açıklama |
| --- | --- | --- |
| `initialState` | herhangi | Başlangıç değeri. Bir işlev verirseniz `() => hesapla()` yalnızca ilk render’da çağrılır |
| `set` işlevi | `function` | Yeni değeri alır ya da `prev => prev + 1` biçiminde bir güncelleyici |

Sayfanın renklendiricisi aşağıdaki bloğa sınıf bırakmamış, bu yüzden blok
etiketsiz çıktı – yanlış bir dil yazmak yerine boş bırakılıyor:

```
npx create-react-app benim-uygulamam
```

Üç gerçek oturum

Hangi sürüme göre yazdığınızı sabitlemek

Bir çatının v4 dalındaki dokümanlarını okuyorsunuz; sayfa, v5’te adı değişen bir yapılandırma bayrağını anlatıyor. Alt+Shift+M’e basıyorsunuz. Dosya docs/clips içine alan adı ve başlıkla adlandırılmış hâlde düşüyor, source alanı /v4/ adresini, tarih alanı da sayfanın bildirdiği tarihi taşıyor.

Sekiz ay sonra bayrak üretimde başka türlü davranıyor ve neden öyle ayarlandığını kimse hatırlamıyor. Kayıt depoda, değişikliğin geçtiği commit aralığında duruyor ve kararın hangi dokümantasyon sürümüne göre alındığını söylüyor. Canlı adres artık v6 sunuyor ve o bayraktan hiç söz etmiyor.

İşi asıl çözen forum konusu

Resmî doküman mutlu yolu anlatıyor; sizin durumunuzun çözümü bir forum konusunda, dört yanıt aşağıda, 24 oylu kabul edilmiş yanıtın altında duruyor. Konuyu kaydediyorsunuz. Siteye özel kural dosyayı forum alt klasörüne yolluyor, yanıt yapısı iç içe alıntı bloklarıyla, oyuyla birlikte geliyor.

Geri okurken önemli olan tam da o oy. Aynı konunun düz kopyala-yapıştır hâli sıralama bilgisini büsbütün yitirir; elinizde hangisinin doğru olduğunu ayırt edemeyeceğiniz beş görüş kalır.

Ortam değişkenleri tablosu, doğrudan pull request’e

Dağıtım kılavuzunda on sekiz ortam değişkenlik bir tablo var; üçünün hücresinde kod örneği duruyor. Sayfada tabloyu seçip yalnızca seçimi kaydediyor, Markdown’ı pull request açıklamasına yapıştırıyorsunuz. GitHub bunu tablo olarak çiziyor, çünkü ekran görüntüsü değil GFM tablosu.

On beş tablolu teknik korpusta bu yazıcı on iki tabloyu korudu; karşılaştırılan iki motor yedişer tablo korudu. Genel dönüştürücüleri kıran hücreler zaten bunlar: içinde kod ya da liste olanlar.

Şimdiki yollarla karşılaştırma

Bunların hepsi işe yarar ve her biri şu anda ekipten birinin yaptığı şeydir. Üçüncü sütun dürüst bedeli söylüyor – bu eklenti de dahil.

Beklediğiniz gibi çıkmadıysa

Kod bloğum neden etiketsiz?

Çünkü sayfa dili söylememiş. Clean Clipper dili, sitenin kendi renklendiricisinin bıraktığı sınıftan okur; koda bakıp tahmin etmez. Elle biçimlendirilmiş, sınıfsız bir örnek etiketsiz blok üretir ve dürüst olan da budur – bir kabuk komutuna tahminle python yazmak, hiç yazmamaktan kötüdür, çünkü renklendirme o zaman yanlış şeyleri kendinden emin biçimde boyar.

Kılavuzun yarısı neden eksik?

Neredeyse her zaman sekmeler ya da akordeon yüzünden. Eklenti tarayıcının gerçekten çizdiği şeyi dönüştürür; içeriği ancak tıklayınca eklenen bir sekme, siz tıklamadan DOM’da yoktur. Sekmeyi açın, bölümü genişletin, sonra kaydedin – ya da her varyant için ayrı kaydedin. Bütün sekmeleri çizip CSS ile gizleyen sitelerde hepsi arka arkaya gelir.

Neden “makale yok” diyor?

Bir API oyun alanı, arama sonucu ya da paket dizini büyük ölçüde bağlantı etiketinden ibarettir ve eklenti bunları bilerek reddeder: çıkarılan karakterlerin kabaca dörtte birinden fazlası bağlantıların içindeyse üç yüz satırlık bir liste vermek yerine “makale yok” der. Bu reddediş, “yararlı metin” oranının her zaman bir şey döndüren motorlara göre neden düşük göründüğünü de açıklar.

Dosyamdaki extraction: "jsonld-articlebody" ne demek?

Sayfanın makale metnini yapılandırılmış verisinde yolladığı, ama DOM’a çizmeyi bitirmediği anlamına gelir; gövde bu yüzden yapılandırılmış veriden okunmuştur. Gizlenmeyip kaydedilmesinin nedeni iki kopyanın farklı olabilmesi: yapılandırılmış verideki metin kimi zaman daha erken bir taslak, kimi zaman da tek eksiksiz sürümdür. Bu değeri gördüğünüzde metne dayanmadan önce özgün sayfaya bir göz atmaya değer.

Yapmadıkları

Tarama yapmaz: bir dokümantasyon sitesinin tamamını tek komutla indiremezsiniz, açık olan sayfa kaydedilir. Görselleri ve diyagramları bağlantı olarak bırakır, dosyaları notun yanına indirmez. Kodu biçimlendirmez, çalıştırmaz ve dilini tahmin etmez – sayfa hiçbir sınıf bildirmiyorsa blok etiketsiz çıkar. chrome:// gibi tarayıcının koruduğu adreslerde de çalışmaz.

Sorular