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

  • Makale
  • Okumak için 6 dakika

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.

Markaşağı, 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:

  • Özel karakteri "Escape" (örneğin, * için) önüne bir ters eğik çizgi koyun \* .
  • Karakter için HTML varlık kodunu kullanın (örneğin, bir * iç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.

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)

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:

  1. 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.

  2. 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><xref:System.String> olarak işler
  • <xref:System.String?displayProperty=nameWithType><xref:System.String?displayProperty=nameWithType> olarak işler
  • [String class](xref:System.String)[String class](xref:System.String) olarak işler

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ğeri %60 , ve SıRASıYLA HTML kodlamalı olmalıdır %23%2A . 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) şu şekilde 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.docs.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.docs.microsoft.com/autocomplete?text=string.formathttps://xref.docs.microsoft.com/autocomplete?text=string.format aşırı yüklerini 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 öğesinden sonra bir * (veya %2A ) eklerseniz, bağlantı daha sonra belirli BIR API değil aşırı yükleme sayfasını temsil eder. Örneğin, bunu, T listesini bağlamak istediğinizde kullanabilirsiniz > . BinarySearch yöntemi sayfası, liste T gibi belirli bir aşırı yükleme yerine genel bir >. Üye aşırı yüklü olmadığında üye sayfasına bağlamak için * öğesini de kullanabilirsiniz; Bu, sizi UID 'e parametre listesini eklemek zorunda kalmanı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 < yöntemine bağlanır, ancak < XREF: System. DateTime. ToString (System. String, System. IFormatProvider) > , > yöntemine bağlanır.

System. Collections. Generic. List > Tgibi genel bir türe bağlantı sağlamak için, ' ( %60 ) karakterini ve ardından genel tür parametrelerinin sayısını kullanın. Örneğin, System. <xref:System.Nullable%601><xref:System.Nullable%601> türüne bağlantılar sırasında <xref:System.Func%602>< temsilcisinin 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

Şu anda hem Channel 9 hem de YouTube videolarını şu söz dizimi ile ekleyebilirsiniz:

Channel 9

> [!VIDEO <channel9_video_link>]

Videonun doğru URL 'sini almak için video çerçevesinin altındaki Ekle sekmesini seçin ve öğesinden URL 'yi kopyalayın . Örneğin:

> [!VIDEO https://channel9.msdn.com/Blogs/dotnet/NET-Core-20-Released/player]

YouTube

Videonun doğru URL 'sini almak için videoya sağ tıklayın, ekleme kodunu kopyala' yı seçin ve URL 'yi öğeden kopyalayın.

> [!VIDEO <youtube_video_link>]

Örneğin:

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

docs.microsoft uzantıları

docs.microsoft, GitHub Flavored Markdown’a 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)

Bu, şu şekilde işlenir:

düğme bağlantıları

Visual Studio belgelerinde, düğmelerin nasıl kullanıldığının örneklerini bulabilirsiniz.

Adım adım açıklamalar

>[!div class="step-by-step"]
> [Pre](../docs/csharp/expression-trees-interpreting.md)
> [Next](../docs/csharp/expression-trees-translating.md)

C# Kılavuzunda, adım adım açıklamaların nasıl kullanıldığının örneklerini bulabilirsiniz.