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

Bu dotnet/docs şablonu, Markdown söz dizimi örneklerini ve meta verileri ayarlama yönergelerini içerir.

Markdown dosyası oluştururken, eklenen şablonu yeni bir dosyaya kopyalayın, aşağıda belirtilen meta verileri doldurun ve yukarıdaki H1 başlığını makalenin başlığına ayarlayın.

Meta veriler

Gerekli 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

Meta veri öğesinin değeriyle iki nokta üst üste (:) arasında bir boşluk zorunludur.
Bir değerdeki iki nokta (örneğin, başlık) meta veri ayrıştırıcısını bozar. Bu durumda başlığı çift tırnak içine alın (örneğin, title: "Writing .NET Core console apps: An advanced step-by-step guide").
title: Arama altyapısı sonuçlarında görünür. Başlık, H1 başlığınızdaki başlıkla aynı olmamalıdır ve 60 veya daha az karakter içermelidir.
description: Makalenin içeriğini özetler. Genellikle arama sonuçları sayfasında gösterilir, ancak arama derecelendirmesi için kullanılmaz. Uzunluğu boşluklar da dahil olmak üzere 115-145 karakter olmalıdır.
yazar: Yazar alanı, yazarın GitHub kullanıcı adını içermelidir.
ms.date: Son önemli güncelleştirmenin tarihi. Makalenin tamamını gözden geçirdiyseniz ve güncelleştirdiyseniz bunu mevcut makalelerde güncelleştirin. Yazım hataları veya benzerleri gibi küçük düzeltmeler güncelleştirmeyi garantilemez.

Diğer meta veriler her makaleye eklenir, ancak genellikle docfx.jsoniçinde belirtilen çoğu meta veri değerini klasör düzeyinde uygularız.

Temel Markdown, GFM ve özel karakterler

Markdown, GitHub Flavored Markdown (GFM) ve OPS'ye özgü uzantıların temellerini Markdown başvuru makalesinde öğrenebilirsiniz.

Markdown biçimlendirme için *, ' ve # gibi özel karakterler kullanır. İçeriğinize bu karakterlerden birini eklemek istiyorsanız iki işlemden birini yapmalısınız:

Özel karakteri "kaçıra"bilmek için önüne bir ters eğik çizgi koyun (örneğin, \* bir * için).
Karakter için HTML varlık kodunu kullanın (örneğin, * *).

Dosya adları

Dosya adları aşağıdaki kuralları kullanır:

Yalnızca küçük harf, sayı ve kısa çizgi içerir.
Boşluk veya noktalama karakteri yok. Dosya adındaki sözcükleri ve sayıları ayırmak için kısa çizgileri kullanın.
Geliştirme, satın alma, derleme, sorun giderme gibi belirli eylem fiillerini kullanın. -ing ile biten kelime yok.
Küçük kelimeler kullanmayın - 'a', 've', 'the', 'in', 'or' gibi.
Markdown'da olmalı ve .md dosya uzantısını kullanmalıdır.
Dosya adlarını oldukça kısa tutun. Bunlar makalelerinizin URL'sinin bir parçasıdır.

Headings

Cümle tarzı büyük harfle başlatmayı kullanın. Başlığın ilk sözcüğünü her zaman büyük harfle yazın.

Metin stili oluşturma

Italics
Dosyalar, klasörler, yollar (uzun öğeleri kendi satırlarına bölerek) ve yeni terimler için kullanılmalıdır.

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

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

Links

Yer işaretleri, iç bağlantılar, diğer belgelere bağlantılar, kod içerir ve dış bağlantılar hakkında bilgi için Bağlantılar'ın genel makalesine bakın.

.NET belgeleri ekibi aşağıdaki kuralları kullanır:

Çoğu durumda göreli bağlantıları kullanıyoruz ve GitHub'daki kaynakta göreli bağlantılar çözümlendiği için bağlantılar içinde ~/ kullanımını önermiyoruz. Ancak, bağımlı bir depodaki bir dosyaya her bağlanışımızda yolu sağlamak için ~/ karakterini kullanırız. Bağımlı depodaki dosyalar GitHub'da farklı bir konumda olduğundan, bağlantılar nasıl yazıldıklarından bağımsız olarak göreli bağlantılarla doğru çözümlenmez.
C# dil belirtimi ve Visual Basic dil belirtimi, dil depolarındaki kaynak eklenerek .NET belgelerine eklenir. Markdown kaynakları csharplang ve vblang depolarında yönetilir.

Belirtim bağlantıları, bu özelliklerin dahil edildiği kaynak dizinlere işaret etmelidir. C# için ~/_csharplang/spec ve VB için aşağıdaki örnekte olduğu gibi ~/_vblang/spec şeklindedir:

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

API'lere bağlantılar

Derleme sistemi, dış bağlantıları kullanmak zorunda kalmadan .NET API'lerine bağlanmamıza olanak sağlayan bazı uzantılara sahiptir. Aşağıdaki söz dizimlerinden birini kullanırsınız:

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

Sorgu displayProperty parametresi tam nitelikli bağlantı metni oluşturur. Varsayılan olarak, bağlantı metni yalnızca üye veya tür 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.

Examples:

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

Bu notasyonu kullanma hakkında daha fazla bilgi için bkz. Çapraz başvuru kullanma.

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

Examples:

System.Threading.Tasks.Task 1 System.Threading.Tasks.Task%601 olarak dönüşür
System.Exception.#ctor System.Exception.%23ctor olur
System.Lazy'1.#ctor(System.Threading.LazyThreadSafetyMode) olur System.Lazy%601.%23ctor%28System.Threading.LazyThreadSafetyMode%29

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, belirli bir aşırı yükleme yerine, List<T>.BinarySearch Yöntemi sayfasına genel bir şekilde bağlanmak istediğinizde bunu kullanabilirsiniz, örneğin List<T>.BinarySearch(T, IComparer<T>). Üye aşırı yüklenmediğinde üye sayfasına bağlanmak için * de kullanabilirsiniz; bu sizi UID'ye parametre listesini eklemek zorunda kalmadan kurtarır.

Belirli bir yöntem aşırı yüklemesine bağlanmak için, yöntemin parametrelerinin her birinin 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 bağlantı verirken, <xref:System.Func%602>System.Func<T,TResult> temsilcisine bağlantı verir.

Kod

Kod eklemenin en iyi yolu, çalışan bir örnekten kod parçacıkları eklemektir. .NET'e katkıda bulunma makalesindeki yönergeleri izleyerek örneğinizi oluşturun. Tam programlardan kod parçacıkları dahil olmak, tüm kodların Sürekli Tümleştirme (CI) sistemimiz aracılığıyla çalışmasını sağlar. Ancak, derleme zamanı veya çalışma zamanı hatalarına neden olan bir şey göstermeniz gerekiyorsa satır içi kod blokları kullanabilirsiniz.

Belgelerde kod göstermeye yönelik Markdown söz dizimi hakkında bilgi için bkz. Belgelere kod ekleme.

Resimler

Statik resim veya animasyonlu GIF

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

Bağlı resim

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

Videos

YouTube videolarını bir Markdown dosyasına ekleyebilirsiniz. Videonun doğru URL'sini almak için videoya sağ tıklayın, Ekleme Kodunu Kopyala'yı seçin ve öğesinden URL'yi <iframe> kopyalayın.

> [!VIDEO <youtube_video_link>]

Örneğin:

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

Learn.microsoft eklentileri

learn.microsoft, GitHub Flavored Markdown'a birkaç ek uzantı sağlar.

Kontrol edilmiş 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 şekilde görüntülenir:

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

.NET Core belgelerinde işaretli listelerin nasıl çalıştığını gösteren bir örnek görebilirsiniz.

Buttons

Düğme bağlantıları:

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