Orbit'te Proje README'nizi Görüntüleme

The Docs tab renders your repository's README inside KPanel, so the project's own documentation is one click from its deployments instead of in a browser tab someone has to go and find.

Docs sekmesi deponuzun README dosyasını KPanel içinde gösterir, böylece projenin kendi belgeleri dağıtımlarından bir tık uzakta olur, birinin gidip bulması gereken bir tarayıcı sekmesinde değil.

Docs Sekmesi Nerede Bulunur

Orbit'i açın, projeyi tıklayın ve proje sekme şeridindeki Overview grubu altında Docs'u seçin.

Yapılandırılması gereken bir şey yoktur. Projenin kökünde bağlı bir deposu ve README dosyası varsa, sekme onu gösterir.

Hangi Dosya Gösterilir

Orbit, README dosyasını bağlı deponun varsayılan dalından alır.

GitHub'da sırasıyla birkaç geleneksel adı dener: README.md, readme.md, README.MD, README ve readme.txt, var olanlardan ilkini alır. GitLab ve Bitbucket'ta README.md arar.

Yalnızca deponun kökü kontrol edilir. Monorepo uygulamasının kök dizini de dahil olmak üzere bir alt dizin içindeki README alınmaz.

İçerik yaklaşık beş dakika boyunca önbelleğe alınır. README dosyanızda bir değişiklik gönderin ve sekme kısa bir süre eski metni hala gösterecektir. Bu beklenen bir durumdur; değişikliğin yapılmadığını varsayarak bekleyin ve sayfayı yeniden yükleyin.

Ne Gösterilir

README markdown olarak gösterilir: başlıklar, listeler, tablolar, bağlantılar, satır içi kod ve sarılmış kod blokları hepsi beklediğiniz gibi görüntülenir.

README dosyası içindeki göreli görüntü yolları KPanel'e değil depoya işaret eder, bu nedenle sağlayıcınızın kendi sitesinde çalışan görüntüler burada çözümlenmeyebilir. Bir görüntü önemliyse mutlak bir URL kullanın.

Boş Durumlar

Gösterecek bir şey olmadığında iki durum içeriğin yerini alır:

Depo bağlı değil, Depo bağla düğmesi ile. Önce bir tane bağlayın: GitHub Deposunu Bağlama, GitLab Deposunu Bağlama veya Bitbucket Deposunu Bağlama sayfalarına bakın.
README bulunamadı, deponuzun köküne README.md eklemenizi isteyen ve sağlayıcınızda bir tane oluşturmak için bir bağlantı içeren.

Her ikisi de sağlayıcıya bağlantı verilerek hemen işlem yapabilmenizi sağlar ve doldurulmuş görünüm, düzenlemek istediğinizde dosyanın kendisine gitmek için Şurada görüntüle bağlantısı içerir.

Gösterilmeye Değer Bir README Yazma

Bu sekme dağıtım geçmişinin yanında yer aldığından, Orbit projesi için en yararlı README operasyonel olandır. Birisi onu açar çünkü projeyi az önce almıştır ve bir şeyi güvenle değiştirmesi gerekir.

İşe yarayan bir yapı:

Bu nedir. Bir paragraf. Projenin ne yaptığı ve kimi hizmet ettiği.

Yerel olarak çalıştırma. Paket yöneticisi dahil olmak üzere tam komutlar. pnpm install && pnpm dev aynı şeyi açıklayan bir paragraftan iyidir.

Ortam değişkenleri. Hangilerinin var olduğu ve her birinin ne için olduğu. Asla değerler: bunlar projenin ortam değişkenlerinde bulunmalı, depodaki bir dosyada değil. Orbit'te Ortam Değişkenleri bölümüne bakın.

Nasıl dağıtılır. Hangi dal üretimde, etiketlerin dağıtıp dağıtmadığı ve hangi kapıların yürürlükte olduğu. Orbit Dağıtım Boru Hattı sekmesine işaret edin, çoğaltmayın, çünkü sekme eski olamaz ama README'niz olabilir.

Nasıl geri alınır. İki cümle ve Dağıtımı Geri Alma bağlantısı. Bu, insanların en kötü anında ihtiyaç duyduğu şeydir ve bakacakları yerde olmalıdır.

Sahibi kim. Bir takım veya bir kişi. Projeler onları kuran insanlardan daha uzun yaşar.

Bir README dosyasına kimlik bilgileri koymayın. Bir bağlantı dizesi, API anahtarı veya parolası depoya kaydedilirse kalıcı olarak geçmişte bulunur ve sonraki bir commit'te silinmesi onu kaldırmaz. Bu olmuşsa, geçmişi temizlemeye çalışmak yerine kimlik bilgisini döndürün.

Canlı Durum Rozetini Ekleme

README buraya ve sağlayıcınıza gösterildiğinden, dağıtım durum rozeti eklemeye değer. Orbit her proje için bir tane yayımlar.

Ayarlar'ı açın ve Durum rozeti kartını bulun. Canlı bir önizleme ve üç kopyalama düğmesi gösterir: rozet URL'si, markdown kod parçası ve HTML kod parçası. Markdown'u README'nizin başına yapıştırın.

Rozet, projenin üretim ortamının mevcut durumunu bildiren küçük bir SVG'dir: deployed, building, failed, queued veya no deployments. Kimlik doğrulaması gerektirmez, bu nedenle depoyu okuyan herkes tarafından gösterilir ve KPanel'deki projeye geri bağlantı verir.

Bu, üretimin şu anda sağlıklı olup olmadığını bir bakışta gösteren bir README sağlar. Buna ekleyebileceğiniz en yüksek değerli satırdır.

Dürüst Kalma

Projenin artık sahip olmadığı bir kurulumu açıklayan README, hiç README olmaktan daha kötüdür, çünkü insanlar buna güvenirler. İki alışkanlık onu doğru tutar:

Çoğalt yerine bağlantı verin. KPanel'de görünen her şey, derleme ayarları, kapılar ve ortam yapılandırması gibi, yeniden belirtilmemeli, bağlantı verilmelidir.
Aynı pull request'te güncelleyin. Bir değişiklik projenin nasıl çalıştığını değiştirirse, README değişikliği o pull request'te bulunmalı, sonraki bir temizlik'te değil.

Sorun Giderme

Sekme eski bir sürümü gösteriyor. Beş dakikalık önbellek. Bekleyin ve sayfayı yeniden yükleyin.

README bulunamadı ama var. Depo kökünde ve README.md adında olduğunu kontrol edin. GitLab ve Bitbucket'ta ad tam olarak eşleşmelidir.

Depo bağlı ama sekme bağlı olmadığını söylüyor. Bağlantı erişimi kaybetmiş olabilir, örneğin entegrasyon sağlayıcı tarafında kaldırıldıysa. Proje ayarlarından yeniden bağlayın.

Görüntüler yüklenmez. Göreli yollar burada çözümlenmez. Mutlak URL'ler kullanın.

Rozet dağıtım yok gösteriyor. Üretim ortamında hiç başarılı bir dağıtım olmamıştır. Bir kez dağıtın ve güncellenir.

Sonraki Adımlar

Orbit Dağıtım Boru Hattı, bir README'nin genellikle açıklamaya çalıştığı şeyin canlı sürümü.
Orbit Proje Ayarları, durum rozeti ve geri kalan yapılandırma için.
Orbit'te Ortam Değişkenleri, bir README'nin asla içermemesi gereken değerler için.