İçeriğe geç
Starlight

Kenar Çubuğu Gezintileri

İyi düzenlenmiş bir kenar çubuğu, kullanıcılarınızın sitenizde gezinti yapabileceği iyi bir dokümantasyonun anahtarıdır. Starlight kenar çubuğunuzun taslağı ve içeriğini özelleştirebileceğiniz ayarlar sunar.

Varsayılan Kenar Çubuğu

Starlight, varsayılan olarak dokümantasyonunuzda yer alan her dosyanın title değerini kenar çubuğu girdisi olacak şekilde kullanan ve dosya hiyerarşisini baz alan bir kenar çubuğunu otomatik olarak oluşturur.

Örneğin, aşağıdaki gibi dosya yapısı:

  • Directorysrc/
    • Directorycontent/
      • Directorydocs/
        • Directoryguides/
          • components.md
          • i18n.md
        • Directoryreference/
          • configuration.md

Aşdağıdaki gibi kenar çubuğu otomatik olarak oluşturulacaktır:

Otomatik oluşturulan kenar çubukları ile ilgili daha fazla bilgiye otomatik oluşturulan gruplar bölümünden ulaşabilirsiniz.

Bağlantı ve Bağlantı Grupları Ekleme

Kenar çubuğu bağlantıları ve link grupları (toplanabilen başlıkla birlikle) yapılandırmak için astro.config.mjs içindeki starlight.sidebar değerini kullanın.

Bağlantıları ve grupları birleştirereki çok çeşitli kenar çubuğu taslakları oluşturabilirsiniz.

Bağlantılar

Dahili ya da harici sayfaya label ve link değerlerine sahip bir nesneyi kullanarak bağlantı ekleyin.

starlight({
	sidebar: [
		// CSS ve Stillendirme rehberine bağlantı.
		{ label: 'CSS ve Stillendirme', link: 'tr/guides/css-and-tailwind/' },
		// Astro sitesine harici bir bağlantı.
		{ label: 'Astro', link: 'https://astro.build/' },
	],
});

Yukarıdaki yapılandırma aşağıdaki gibi kenar çubuğu oluşturur:

Gruplar

Kenar çubuğunuza ilişkili bağlantıları toplanabilen başlık altında gruplayarak yapı ekleyebilirsiniz. Gruplar bağlantı ve diğer alt grupları barındırabilir.

label ve items değerlerine sahip bir nesneyi kullanarak grup ekleyin. label grup için başlık olarak kullanılacaktır. items dizisine bağlantı ya da alt gruplar ekleyin.

starlight({
	sidebar: [
		// "Guides" etiketli bağlantı grupları.
		{
			label: 'Rehber',
			items: [
				{ label: 'Bileşenler', link: 'tr/guides/components/' },
				{ label: 'Uluslararasılaştırma (i18n)', link: 'tr/guides/i18n/' },
				// Yerleşik bir bağlantı grubu.
				{
					label: 'Stillendirme',
					items: [
						{ label: 'CSS', link: '/guides/css-and-tailwind/' },
						{ label: 'Tailwind', link: '/guides/css-and-tailwind/' },
						{ label: 'Shiki', link: '/guides/css-and-tailwind/' },
					],
				},
			],
		},
	],
});

Yukarıdaki yapılandırma aşağıdaki gibi kenar çubuğu oluşturur:

Otomatik Oluşturulmuş Gruplar

Starlight dokümantasyonunuzun dizinini baz alarak kenar çubuğunuzda otomatik olarak grup oluşturabilir. Elle her kenar çubuğu elemanını bir grup içerisine eklemek istemediğinizde yardımcı olur. Varsayılan olarak dosyalar, dosya isimlerinin alfabetik sıralamasına göre sıralanmış olacaktır.

label ve autogenerate değerlerini kullanarak otomatik oluşturulmuş bir grup ekleyin. autogenerate yapılandırmanız directory değerini, kenar çubuğu girdilerini kullanmak için belirtmelidir. Örneğin, aşağıdaki yapılandırmayla:

starlight({
	sidebar: [
		{
			label: 'Rehber',
			// 'guides' dizini için bağlantı gruplarını otomatik oluşturur.
			autogenerate: { directory: 'guides' },
		},
	],
});

Ve aşağıdaki dosya yapısıyla:

  • Directorysrc/
    • Directorycontent/
      • Directorydocs/
        • Directoryguides/
          • components.md
          • i18n.md
          • Directoryadvanced/
            • project-structure.md

Aşağıdaki gibi kenar çubuğu oluşturulacaktır:

Önbölümde otomatik oluşturulmuş bağlantıları özelleştirmek

Özel sayfalarınızda kenar çubuğu önbölüm alanı‘nı otomatik oluşturulan bağlantılarınızı özelleştirmek için kullanın.

Kenar çubuğu önbölüm ayarları bir bağlantıya özel isim ya da etiket eklemenize, kenar çubuğundan bir bağlantı gizlemenize ya da özel sıralama tanımlamanıza olanak sağlar.

---
title: Sayfam
sidebar:
  # Bağlantı için özel isim ayarlar
  label: Özel Kenar Çubuğu İsmi
  # Bağlantı için özel sıralama ayarlar (küçük sayılar üst sıralarda görünür)
  order: 2
  # Bağlantıya etiket ekler
  badge:
    text: Yeni
    variant: tip
---

Yukarıdaki gibi önbölümlü sayfa içeren otomatik oluşturulan grup, aşağıdaki gibi kenar çubuğu oluşturacaktır:

Etiketler

Bağlantılar ayrıca badge değerini bağlantı isminin yanında etiket göstermek için alabilir.

starlight({
	sidebar: [
		{
			label: 'Rehber',
			items: [
				// "Yeni" etiketli bağlantı.
				{
					label: 'Bileşenler',
					link: '/tr/guides/components',
					badge: 'Yeni',
				},
			],
		},
	],
});

Yukarıdaki yapılandırma aşağıdaki gibi kenar çubuğu oluşturur:

Etiket değişkenleri

text ve variant değerlerine sahip bir nesne kullanarak etiket özelleştirin.

text görüntülenecek içeriği temsil eder (örneğin “Yeni”).

variant özelliğini bu değerlerden (note, tip, danger, caution ya da success) biri ile değiştirdiğinizde, sitenizin ara rengini kullanan default stillendirmenizin üzerine yazar.

starlight({
	sidebar: [
		{
			label: 'Rehber',
			items: [
				// Sarı "Deneysel" etiketli bir bağlantı.
				{
					label: 'Bileşenler',
					link: 'components/',
					badge: { text: 'Experimental', variant: 'caution' },
				},
			],
		},
	],
});

The configuration above generates the following sidebar:

Özel HTML nitelikleri

Bağlantılar ayrıca, özel HTML niteliklerini bağlantı elemanına eklemek için attrs değerini içerir. Aşağıdaki örnekte attrs, target="_blank" niteliğini eklemek için kullanılmıştır. Böylecek bağlantı yeni bir sekmede açılır. Özel style niteliği bağlantı ismini italikleştirir:

starlight({
	sidebar: [
		{
			label: 'Rehber',
			items: [
				//Yeni sekmede açılan Astro Dokümantasyonuna harici bağlantı.
				{
					label: 'Astro Docs',
					link: 'https://docs.astro.build/',
					attrs: { target: '_blank', style: 'font-style: italic' },
				},
			],
		},
	],
});

Yukarıdaki yapılandırma aşağıdaki gibi kenar çubuğu oluşturur:

Uluslararasılaştırma

translations değerini bağlantının dilini ya da grup etiketini; BCP-47 dil etiketini (örneğin "en","ar ya da "zh-CN") anahtar ve çevirilmiş ismi değer olarak tanımlayarak her bir desteklenen dil için değiştirmekte kullanın. label değeri varsayılan yer ve çevirisi olmayan diller için kullanılır.

starlight({
	sidebar: [
		{
			label: 'Rehber',
			translations: {
				'pt-BR': 'Guias',
			},
			items: [
				{
					label: 'Bileşenler',
					translations: {
						'pt-BR': 'Componentes',
					},
					link: '/guides/components/',
				},
				{
					label: 'Uluslararasılaştırma (i18n)',
					translations: {
						'pt-BR': 'Internacionalização (i18n)',
					},
					link: '/guides/i18n/',
				},
			],
		},
	],
});

Dokümantasyonu Brezilya Portekizcesinde gezinmek aşağıdaki kenar çubuğunu oluşturacaktır:

Toplanabilen Gruplar

Bağlantı grupları varsayılan olarak collapsed değerinin true olarak ayarlanmasıyla toplanabilir olur.

starlight({
	sidebar: [
		{
			label: 'Rehber',
			// Collapse the group by default.
			collapsed: true,
			items: [
				{ label: 'Bileşenler', link: '/tr/guides/components/' },
				{ label: 'Uluslararasılaştırma (i18n)', link: '/tr/guides/i18n/' },
			],
		},
	],
});

Yukarıdaki yapılandırma aşağıdaki gibi kenar çubuğu oluşturur:

Otomatik oluşturulmuş gruplar collapsed değerinin üst grubuna dikkat eder:

starlight({
	sidebar: [
		{
			label: 'Rehber',
			// Varsayılan olarak grubu ve otomatik oluşturulmuş alt grupları toplar.
			collapsed: true,
			autogenerate: { directory: 'guides' },
		},
	],
});

Yukarıdaki yapılandırma aşağıdaki gibi kenar çubuğu oluşturur:

autogenerate.collapsed değerinin tanımlanmasıyla bu davranışın üzerine yazılabilir.

starlight({
	sidebar: [
		{
			label: 'Rehber',
			// "Guides" toplanmaz ama
			//otomatik oluşturulmuş alt grupları toplar.
			collapsed: false,
			autogenerate: { directory: 'guides', collapsed: true },
		},
	],
});

Yukarıdaki yapılandırma aşağıdaki gibi kenar çubuğu oluşturur: