Belgelerde bağlantı kullanma

Bu makalede, Microsoft Learn'de barındırılan sayfalardan köprülerin nasıl kullanılacağı açıklanmaktadır. Bağlantılar, çeşitli birkaç kural ile birlikte Markdown’a eklemesi kolay öğelerdir. Bağlantılar, kullanıcıları aynı sayfadaki, komşu sayfalardaki veya harici site ve URL’lerdeki içeriklere götürür.

Microsoft Learn arka ucu, Markdig ayrıştırma altyapısı aracılığıyla ayrıştırılan CommonMark uyumlu Markdown'ı destekleyen Open Publishing Services 'ı (OPS) kullanır. Çoğu belge GitHub'da depolandığından ve orada düzenlenebildiği için bu Markdown çeşidi çoğunlukla GitHub Flavored Markdown (GFM) ile uyumludur. Markdown uzantıları ile ilave işlevler eklenir.

Bağlantı metni

Bağlantı metnine eklediğiniz kelimeler kolay olmalıdır. Diğer bir deyişle, bunlar normal Türkçe kelimeler veya bağlantı kurduğunuz sayfanın başlığı olmalıdır.

Doğru:

• For more information, see the [contributor guide index](https://github.com/Azure/azure-content/blob/master/contributor-guide/contributor-guide-index.md).

• For more details, see the [SET TRANSACTION ISOLATION LEVEL](/sql/t-sql/statements/set-transaction-isolation-level-transact-sql) reference.

Yanlış:

• For more details, see [https://msdn.microsoft.com/library/ms173763.aspx](https://msdn.microsoft.com/library/ms173763.aspx).

• For more information, click [here](https://github.com/Azure/azure-content/blob/master/contributor-guide/contributor-guide-index.md).

Bir makaleden diğerine bağlantı

Yayımlama sistemi tarafından desteklenen iki tür köprü vardır: URL'ler ve dosya bağlantıları.

URL bağlantısı, köküne https://learn.microsoft.comgöre bir URL yolu veya tam URL söz dizimini içeren mutlak bir URL olabilir (örneğin, https://github.com/MicrosoftDocs/PowerShell-Docs).

• Geçerli docset dışındaki bir içeriğe bağlantı verirken veya docset içindeki otomatik olarak oluşturulmuş başvuru makaleleri ve kavramsal makaleler arasında yönlendirme yaparken URL bağlantılarını kullanın.
• Göreli bağlantı oluşturmanın en basit yolu, tarayıcınızdan URL’yi kopyalayıp Markdown’a yapıştırdığınız değerden https://learn.microsoft.com/en-us kısmını kaldırmaktır.
• Microsoft özellikleri için URL'lere yerel ayarlar eklemeyin (örneğin, URL'den kaldırın /en-us ).

Dosya bağlantısı, docset’in içinde bulunan bir makaleyi farklı bir makaleye bağlamak için kullanılır.

• Tüm dosya yollarında, ters eğik çizgi karakterleri yerine eğik çizgileri karakterleri (/) kullanılır.

• Bir makaleden aynı dizindeki başka makaleye bağlantı oluşturma:

  [link text](article-name.md)

• Bir makaleden mevcut dizinin üst dizinindeki makaleye bağlantı oluşturma:

  [link text](../article-name.md)

• Bir makaleden mevcut dizinin alt dizinlerinden birindeki makaleye bağlantı oluşturma:

  [link text](directory/article-name.md)

• Bir makaleden mevcut dizinin üst dizininin alt dizinlerinden birindeki makaleye bağlantı oluşturma:

  [link text](../directory/article-name.md)

• Bazı makaleler hem bir .yml .md hem de dosyadan oluşur; burada .yml dosya meta verileri ve .md içeriği içerir. Bu durumda, dosyaya bağlanın .yml :

  [link text](../directory/article-name.yml) (değil [link text](../directory/article-name-content.md))

Microsoft Learn'de bağlantıların yapısı

Microsoft Learn'de yayımlanan içerik aşağıdaki URL yapısına sahiptir:

https://learn.microsoft.com/<locale>/<product-service>/[<feature-service>]/[<subfolder>]/<topic>[?view=<view-name>]

Örnekler:

https://learn.microsoft.com/azure/load-balancer/load-balancer-overview

https://learn.microsoft.com/powershell/azure/overview?view=azurermps-5.1.1

• <locale> - makalenin dilini tanımlar (örnek: en-us veya tr-tr)
• <product-service> - ürünün veya hizmetin adı (örnek: powershell, dotnet veya azure)
• [<feature-service>] - (isteğe bağlı) ürünün özelliğinin veya alt hizmetinin adı (örnek: csharp veya yük dengeleyici)
• [<subfolder>] - (isteğe bağlı) bir özellikte bulunan alt klasörün adı
• <topic> - konuya yönelik makale dosyasının adı (örnek: load-balancer-overview veya overview)
• [?view=\<view-name>] - (isteğe bağlı) birden fazla sürümü olan içeriğe yönelik sürüm seçicisi tarafından kullanılan görünüm adı (örnek: azps-3.5.0)

Yer işareti bağlantıları

Geçerli dosyadaki bir başlığa yönelik yer işareti bağlantısı oluşturmak için diyez simgesinden sonra küçük harflerle başlığı girin. Başlıktan noktalama işaretlerini kaldırın ve boşlukları çizgilerle değiştirin:

[Managed Disks](#managed-disks)

Başka bir makalenin yer işareti başlığına bağlantı vermek için, göreli dosya veya göreli site bağlantısını kullanıp yanına diyez işareti ile başlıktaki sözcükleri ekleyin. Başlıktan noktalama işaretlerini kaldırın ve boşlukları çizgilerle değiştirin:

[Managed Disks](../../linux/overview.md#managed-disks)

Yer işareti bağlantısını URL’den de kopyalayabilirsiniz. URL'yi bulmak için farenizi Microsoft Learn'de başlık satırının üzerine getirin. Bir bağlantı simgesinin görüntülendiğini görmeniz gerekir:

Bağlantı simgesine tıklayın ve URL’den yer işareti bağlama metnini (diyez etiketinden sonra gelen kısım) kopyalayın.

Açık yer işareti bağlantıları

<a> HTML etiketini kullanarak açık yer işareti bağlantılarının eklenmesi, hub ve giriş sayfaları haricinde önerilmez. Bunun yerine, yer işareti bağlantılarında açıklanan otomatik olarak oluşturulan yer işaretlerini kullanın. Merkez ve giriş sayfaları için yer işaretlerini aşağıdaki gibi bildirin:

## <a id="anchortext" />Header text

veya

## <a name="anchortext" />Header text

Ayrıca, yer işaretine açılan bağlantı oluşturmak için aşağıdaki gibi bildirin:

To go to a section on the same page:
[text](#anchortext)

To go to a section on another page.
[text](filename.md#anchortext)

XRef (çapraz başvuru) bağlantıları

Bağlantı metnini özelleştirmeyi kolaylaştırdığından, API'lere bağlanmanın önerilen yolu XRef bağlantılarıdır. Ayrıca, derleme zamanında doğrulanırlar ve API başvurusunun URL'si değişirse bağlantı çalışmaya devam eder. Geçerli docset’te veya farklı bir docset’te bulunan otomatik olarak oluşturulmuş API başvurularına yönlendiren bağlantılar oluşturmak için türe veya üyeye ilişkin benzersiz kimlik (UID) ile XREF bağlantılarını kullanın.

Bağlanmak istediğiniz API'nin Microsoft Learn'de yayımlandığını denetlemek için .NET API tarayıcısına veya Windows UWP arama kutusuna tam adının tamamını veya bir kısmını yazın. Görüntülenen hiçbir sonuç görmüyorsanız, bu tür henüz Microsoft Learn'de değildir.

Şu söz dizimlerinden birini kullanabilirsiniz:

• Otomatik bağlantılar:

  <xref:UID>
  <xref:UID?displayProperty=nameWithType>
  

  Varsayılan olarak, bağlantı metni yalnızca üyenin veya türün adını gösterir. İsteğe bağlı displayProperty=nameWithType sorgu parametresi, tam nitelikli bağlantı metni oluşturur. Bu, türler için namespace.type ve tür üyeleri için (numaralandırma tür üyeleri de dahil olmak üzere) type.member şeklindedir.

• Markdown stili bağlantıları:

  [link text](xref:UID)
  

  Görüntülenen bağlantıyı özelleştirmek istiyorsanız XRef için Markdown stili bağlantıları kullanın.

Örnekler:

• <xref:System.String> şu şekilde görüntülenir: String

• <xref:System.String?displayProperty=nameWithType> şu şekilde görüntülenir: System.String

• [Dize sınıfı] (xref:System.String) Dize sınıfı olarak görüntülenir.

displayProperty=fullName sorgu parametresi, sınıflara yönelik displayProperty=nameWithType ile aynı şekilde çalışır. Bağlantı metni namespace.classname olur. Ancak, üyeler için bağlantı metni namespace.classname.membername olarak görüntülenir ve bu istenmeyen bir durum olabilir.

UID’yi belirleme

UID genellikle tam sınıf veya üye adından oluşur. UID'yi belirlemek için, bir türün veya üyenin Microsoft Learn sayfasına sağ tıklayın, Kaynağı görüntüle'yi seçin ve ms.assetid için içerik değerini kopyalayın.

URL’lerin yüzde kodlaması

UID'deki özel karakterlerin aşağıdaki gibi yüzde kodlanmış olması gerekir:

Kodlama örneği:

• System.Exception.#ctor, System.Exception.%23ctor olarak kodlanır

Genel türler

Gelen türler System.Collections.Generic.List<T> gibi türlerdir. .NET API tarayıcısında bu türe gidip bunun URL’sine bakarsanız, <T> öğesinin URL’de -1 olarak yazıldığını ve bunun şu öğeyi temsil ettiğini görebilirsiniz: `1:

https://learn.microsoft.com/dotnet/api/system.collections.generic.list-1

Yöntemler

Bir yönteme yönlendiren bir bağlantı oluşturmak için yöntem adından sonra veya belirli bir aşırı yüklemeye yıldız işareti (*) ekleyebilirsiniz. Örneğin, <xref:System.Object.Equals*?displayProperty=nameWithType> yöntemine yönlendiren bağlantıyı belirli parametre türleri olmadan oluşturmak istiyorsanız genel sayfasını kullanın. Örneğin:

<xref:System.Object.Equals*?displayProperty=nameWithType>, Object.Equals öğesine bağlanır

Belirli bir aşırı yükleme yönlendiren bağlantıyı oluşturmak için yöntem adından sonra parantez ekleyin ve her parametrenin tam tür ismini ekleyin. Tür adları arasında boşluk bırakmayın. Boşluk bırakırsanız bağlantınız çalışmaz. Örneğin:

<xref:System.Object.Equals(System.Object,System.Object)?displayProperty=nameWithType>, Object.Equals(Object, Object) öğesine bağlanır

Eklemelerden bağlantılar

Ekleme dosyaları başka bir dizinde bulunduğu için daha uzun göreli yollar kullanmanız gerekir. Bir ekleme dosyasından bir makaleye bağlantı vermek için şu biçimi kullanın:

[link text](../articles/folder/article-name.md)

Seçicilerde bağlantılar

Seçici, bir belgeler makalesinde açılan liste olarak görüntülenen bir gezinti bileşenidir. Okuyucu, açılan listeden bir değer seçtiğinde tarayıcı, seçili makaleyi açar. Seçiciler genellikle bir makaleyle yakından ilgisi olan, aynı konunun birden fazla bilgisayar dilinde ele alındığı veya ilgili bir dizi başka makale gibi diğer makalelere yönlendiren bağlantıları içerir.

Bir ekleme işlemine eklenmiş seçicileriniz varsa aşağıdaki bağlantı yapısını kullanın:

> [AZURE.SELECTOR-LIST (Dropdown1 | Dropdown2 )]
- [(Text1 | Example1 )](../articles/folder/article-name1.md)
- [(Text1 | Example2 )](../articles/folder/article-name2.md)
- [(Text2 | Example3 )](../articles/folder/article-name3.md)
- [(Text2 | Example4 )](../articles/folder/article-name4.md)

Başvuru stili bağlantıları

İçeriğinizin daha kolay okunması için başvuru stili bağlantıları kullanabilirsiniz. Başvuru stili bağlantıları; satır içi bağlantı söz dizimini, uzun URL’leri makale sonuna taşımanıza izin veren basitleştirilmiş söz dizimi ile değiştirir. Aşağıda Daring Fireball örneği verilmiştir:

Satır içi metin:

I get 10 times more traffic from [Google][1] than from [Yahoo][2] or [MSN][3].

Makale sonunda başvuru bağlantıları:

<!--Reference links in article-->
[1]: http://google.com/
[2]: http://search.yahoo.com/
[3]: http://search.msn.com/

Bağlantıdan önce, iki nokta üst üste işaretinin sonuna boşluk koymayı unutmayın. Bu boşluğu unutursanız makale yayımlandığında diğer teknik makalelere verdiğiniz bağlantı bozuk olacaktır.

Teknik belgeler kümesine ait olmayan sayfaların bağlantıları

Başka bir tür Microsoft sayfasına (fiyatlandırma sayfası, SLA sayfası gibi belge makalesi olmayan herhangi bir şey) bağlantı vermek için bir mutlak URL kullanın, ancak yerel ayarı çıkarın. Burada amaç, bağlantıların GitHub’da ve işlenmiş sitede çalışmasını sağlamaktır:

[link text](https://azure.microsoft.com/pricing/details/virtual-machines/)

Üçüncü taraf sitelerine yönelik bağlantılar

En iyi kullanıcı deneyimi, kullanıcıları başka sitelere göndermekten olabildiğince uzak durarak sağlanır. Ancak bazen bunu yapmamız gerekir, bu durumda üçüncü taraf sitelere giden bağlantıları şu bilgiler temelinde oluşturun:

• Sorumluluk: Paylaşmak istediğiniz bilgi üçüncü tarafa aitse üçüncü taraf içeriğine bağlantı verin. Örneğin, Android geliştirici araçlarını kullanmayı anlatmak Microsoft’un işi değildir, bu görev Google’a düşer. Gerekirse Android geliştirici araçlarının Azure ile birlikte nasıl kullanılacağını anlatabiliriz ancak kendi araçlarının kullanımı açıklamak yine Google’ın işidir.
• PM oturum kapatma: Microsoft’un üçüncü taraf içerikte oturum kapatmasını isteyin. Bağlantı vererek, bağlantı verdiğimiz siteye güvendiğimizi ve insanlar bu yönergeleri izlediğinde üzerimize düşen yükümlülüğün farkında olduğumuzu belirtmiş oluruz.
• Yenilik gözden geçirmeleri: Üçüncü taraf bilgilerinin hala güncel, doğru ve ilgili olduğundan ve bağlantının değişmediğinden emin olun.
• Site dışı: Kullanıcıların başka bir siteye gittiklerini fark etmelerini sağlayın. Bağlam bunu açıklamıyorsa belirleyici bir ifade ekleyin. Örneğin: "Önkoşullar, Android Studio sitesine indirebileceğiniz Android Geliştirici Araçları'nı içerir."
• Sonraki adımlar: "Sonraki adımlar" bölümünde bir MVP blogu bağlantısı eklemek normaldir. Kullanıcıların siteden ayrıldıklarını fark etmelerini sağlayın.
• Yasal: Her microsoft.com sayfasındaki Kullanım Koşulları alt bilgisinde Üçüncü Taraf Sitelere Bağlantılar altında yasal olarak ele alınıyoruz.