.NET belgeleri için meta veriler ve Markdown şablonu

Makale
08/10/2023

Bu dotnet/belgeler şablonu, hem Markdown söz dizimi örneklerini hem de meta verileri ayarlama rehberini içerir.

Bir Markdown dosyası oluştururken, eklenen şablonu yeni bir dosyaya kopyalayın, meta verileri aşağıda belirtildiği gibi doldurun ve H1 bölüm başlığını makalenin başlığı olarak yukarıda ayarlayın.

Meta veriler

Gereken meta veri bloğu, aşağıdaki örnek meta veri bloğundadır:

---
title: [ARTICLE TITLE]
description: [usually a summary of your first paragraph. It gets displayed in search results, and can help drive the correct traffic if well written.]
author: [GITHUB USERNAME]
ms.date: [CREATION/UPDATE DATE - mm/dd/yyyy]
---
# The H1 should not be the same as the title, but should describe the article contents

İki nokta (:) ile meta veri öğesi arasına bir boşluk koymanız zorunludur.
Bir değerdeki (örneğin başlıktaki) iki nokta işareti, meta veri ayrıştırıcısını keser. Bu durumda başlığın başına ve sonuna tırnak işareti koyun (örneğin title: "Writing .NET Core console apps: An advanced step-by-step guide").
title (başlık) : Arama altyapısı sonuçlarında görünür. Başlık, H1 başlığınızla aynı olmamalı ve en fazla 60 karakterden oluşmalıdır.
description (açıklama) : Makalenin içeriğini özetler. Genellikle arama sonuçları sayfasında görüntülenir ancak arama sıralaması için kullanılmaz. Açıklama uzunluğu, boşluklu 115-145 karakter olmalıdır.
author (yazar) : Yazar alanı, yazarın GitHub kullanıcı adını içermelidir.
ms.date: En son yapılan önemli güncelleştirmenin tarihi. Tüm makaleyi gözden geçirip güncelleştirdiyseniz mevcut makalelerde bunu da güncelleştirin. Yazım hataları gibi küçük düzeltmeler güncelleştirme gerektirmez.

Diğer meta veriler makalelere eklenir, ancak çoğu meta veri değeri, docfx.json klasöründe belirtilen klasör düzeyinde uygulanır.

Temel Markdown, GFM ve özel karakterler

Markdown, GitHub Flavored Markdown (GFM) ve OPS’ye özgü uzantılar hakkında temel bilgileri Markdown başvurusu makalesinden edinebilirsiniz.

Markdown biçimlendirme için *, ' ve # gibi özel karakterler kullanır. İçeriğinizde bu karakterlerden birine yer vermek isterseniz şu ikisinden birini yapmalısınız:

"Kaçış" için özel karakterin önüne bir ters eğik çizgi koyun (örneğin, \* *).
Karakter için HTML varlık kodunu kullanın (örneğin, * *).

Dosya adları

Dosya adlarında şu kuralları takip edin:

Ad içerisinde yalnızca küçük harf, sayı ve kısa çizgi kullanın.
Boşluk veya noktalama işareti kullanmayın. Dosya adındaki sözcük ve sayıları birbirinden ayırmak için kısa çizgi kullanın.
Geliştir, satın al, oluştur, sorun gider gibi belirgin eylem fiillerini kullanın. -ing (İngilizcede) ile biten sözcük kullanmayın.
Kısa kelimeler kullanmayın; bir, ve, veya gibi sözcükler eklemeyin.
Ad, Markdown biçiminde olmalı ve .md dosya uzantısını kullanmalıdır.
Dosya adlarını olabildiğince kısa tutun. Adlar, makale URL’lerinin bir parçasıdır.

Bölüm başlıkları

Cümle stili büyük harf kullanımını uygulayın. Başlığın ilk harfini her zaman büyük yazın.

Metin stili

İtalik
Dosyalar, klasörler, yollar (uzun öğeleri kendi satırlarına göre ayırın) ve yeni terimler için kullanın.

Kalın
Kullanıcı arabirimi öğeleri için kullanın.

Code
Satır içi kod, bilgisayar dili anahtar sözcükleri, NuGet paket adları, komut satırı komutları, veritabanı tablosu ve sütun adları ile tıklanabilir olmasını istemediğiniz URL’ler için kullanın.

Bağlantılar

Yer işaretleri, dahili bağlantılar, diğer belgelere giden bağlantılar, kod eklemeleri ve harici bağlantılar için Bağlantılar genel makalesine bakın.

.NET belgeleri ekibi, şu kuralları kullanır:

Çoğu durumda göreli bağlantılar kullanırız ve göreli bağlantılar GitHub’daki kaynakta çözümlendiğinden, bağlantılarda ~/ kullanımını önermeyiz. Ancak bağımlı bir depodaki dosyalara bağlantı verdiğimizde, yolu sağlamak için ~/ karakterini kullanırız. Bağımlı depolardaki dosyalar GitHub’da farklı bir konumda olduğundan, nasıl yazıldıkları fark etmeksizin bağlantılar göreli bağlantılarla doğru çözümlenmez.
C# bilgisayar dili belirtimi ve Visual Basic bilgisayar dili belirtimi, bilgisayar dili depolarından kaynak eklenerek .NET dosyalarına eklenir. Markdown kaynakları, csharplang ve vblang depolarında yönetilir.

Belirtimlere yönlendiren bağlantılar, belirtimlerin bulunduğu kaynak dizinlere işaret etmelidir. Bunlar, C# için ~/_csharplang/spec ve VB için ~/_vblang/spec dizinleridir. Şu örnekte görebilirsiniz:

[C# Query Expressions](~/_csharplang/spec/expressions.md#query-expressions)

API’lere giden bağlantılar

Derleme sistemi, dahili bağlantılar kullanmaya gerek kalmadan .NET API’lerine bağlantı vermemizi sağlayan bazı uzantılara sahiptir. Şu söz dizimlerinden birini kullanın:

Otomatik bağlantı: <xref:UID> veya <xref:UID?displayProperty=nameWithType>

displayProperty sorgu parametresi, tam nitelikli bir bağlantı metni üretir. Varsayılan olarak, bağlantı metni yalnızca üyenin veya türün adını gösterir.
Markdown bağlantısı: [link text](xref:UID)

Görüntülenen bağlantı metnini özelleştirmek istediğinizde kullanın.

Örnekler:

<xref:System.String>, String olarak işlenir
<xref:System.String?displayProperty=nameWithType>, System.String olarak işlenir
[String class](xref:System.String), String sınıfı olarak işlenir

Bu gösterimi kullanma hakkında daha fazla bilgi için bkz. Çapraz başvuruyu kullanma.

Bazı UID'ler ', # veya * özel karakterlerini içerir; UID değerinin sırasıyla , %23 ve %2A olarak %60kodlanmış HTML olması gerekir. Bazen parantezlerin kodlandığını görürsünüz ancak bu, zorunlu değildir.

Örnekler:

System.Threading.Tasks.Task'1 olur System.Threading.Tasks.Task%601
System.Exception.#ctor olur System.Exception.%23ctor
System.Lazy'1.#ctor(System.Threading.LazyThreadSafetyMode) olur System.Lazy%601.%23ctor%28System.Threading.LazyThreadSafetyMode%29

Türlerin, üye aşırı yükleme listesinin veya belirli bir aşırı yüklenmiş üyenin UID’sini https://xref.learn.microsoft.com/autocomplete adresinden bulabilirsiniz. ?text=*\<type-member-name>* sorgu satırı, UID’sini görmek istediğiniz türü veya üyeyi belirler. Örneğin https://xref.learn.microsoft.com/autocomplete?text=string.format, String.Format aşırı yüklemelerini alır. Araç, sağlanan text sorgu parametresini UID’nin herhangi bir bölümünde arar. Örneğin üye adı (ToString), kısmi üye adı (ToStri), tür ve üye adı (Double.ToString) gibi bilgileri arayabilirsiniz.

UID'nin arkasına * (veya %2A) eklerseniz, bağlantı belirli bir API'yi değil aşırı yükleme sayfasını temsil eder. Örneğin, Liste<T'ye> bağlanmak istediğinizde bunu kullanabilirsiniz. List T gibi belirli bir aşırı yükleme yerine genel bir şekilde BinarySearch Yöntemi sayfası.>< BinarySearch(T, IComparer<T>). Üye aşırı yüklenmediğinde üye sayfasına bağlanmak için * de kullanabilirsiniz; bu, parametre listesini UID'ye eklemek zorunda olmamanızı sağlar.

Belirli bir metot aşırı yüklemesine bağlantı vermek için her bir metot parametresinin tam tür adını eklemeniz gerekir. Örneğin, <xref:System.DateTime.ToString> parametresiz DateTime.ToString yöntemine bağlanırken <, xref:System.DateTime.ToString(System.String,System.IFormatProvider)>DateTime.ToString(String,IFormatProvider) yöntemine bağlanır.

System.Collections.Generic.List<T> gibi genel bir türe bağlanmak için ' (%60) karakterini ve ardından genel tür parametrelerinin sayısını kullanırsınız. Örneğin, <xref:System.Nullable%601>System.Nullable<T> türüne <xref:System.Func%602> ve System.Func<T,TResult> temsilcisine bağlantılar.

Kod

Kod eklemenin en iyi yolu, çalışan bir örnekten kod parçacığı eklemektir. .NET’e katkıda bulunma makalesindeki yönergeleri izleyerek örneğinizi oluşturun. Tam programlardan kod parçacığı eklendiğinde, tüm kodların Sürekli Tümleştirme (CI) sistemimizde çalışması sağlanır. Ancak derleme zamanı veya çalışma zamanı hatalarına sebep olan bir durum göstermek istiyorsanız satır içi kod bloklarını kullanabilirsiniz.

Belgelerde kod göstermeyi sağlayan Markdown söz dizimi hakkında daha fazla bilgi için bkz. Belgelere kod nasıl eklenir.

Görüntüler

Statik görüntü veya animasyonlu GIF

![this is the alt text](../images/Logo_DotNet.png)

Bağlantı verilen görüntü

[![alt text for linked image](../images/Logo_DotNet.png)](https://dot.net)

Videolar

YouTube videolarını bir Markdown dosyasına ekleyebilirsiniz. Videoya ait doğru URL’yi almak için videoya sağ tıklayın, Ekleme Kodunu Kopyala’ya tıklayın ve <iframe> öğesinden URL’yi kopyalayın.

> [!VIDEO <youtube_video_link>]

Örneğin:

> [!VIDEO https://www.youtube.com/embed/Q2mMbjw6cLA]

learn.microsoft uzantıları

learn.microsoft, GitHub Flavored Markdown için birkaç ek uzantı sağlar.

İşaretli listeler

Listeler için özel bir stil kullanılabilir. Listeleri yeşil onay işaretleriyle işleyebilirsiniz.

> [!div class="checklist"]
> * How to create a .NET Core app
> * How to add a reference to the Microsoft.XmlSerializer.Generator package
> * How to edit your MyApp.csproj to add dependencies
> * How to add a class and an XmlSerializer
> * How to build and run the application

Bu, şu şekilde işlenir:

.NET Core uygulaması oluşturma
Microsoft.XmlSerializer.Generator paketine başvuru ekleme
Bağımlılık eklemek için MyApp.csproj dosyanızı düzenleme
Sınıf ve XmlSerializer ekleme
Uygulamayı derleme ve çalıştırma

.NET Core belgelerinde, işaretli maddelerin nasıl kullanıldığının örneklerini bulabilirsiniz.

Düğmeler

Düğme bağlantıları:

> [!div class="button"]
> [button links](dotnet-contribute.md)