Aracılığıyla paylaş

Markdown uygulama önerileri

Bu makale, belgelerimizde Markdown'ın kullanımına yönelik özel yönergeler sağlar. Markdown için öğretici değildir. Markdown için bir öğreticiye ihtiyacınız varsa bu Markdown bilgi sayfasına bakın.

Belgelerimizi oluşturan derleme işlem hattı , Markdig kullanarak Markdown belgelerini işler. Markdig, belgeleri en son CommonMark belirtiminin kurallarına göre ayrıştırıyor. OPS, CommonMark belirtimini izler ve tablolar ve uyarılar gibi platforma özgü özellikler için bazı uzantılar ekler.

CommonMark belirtimi, bazı Markdown öğelerinin oluşturulması konusunda daha katıdır. Bu belgede sağlanan ayrıntılara çok dikkat edin.

Stil ve biçimlendirme kurallarımızı zorunlu kılmak için VS Code'da markdownlint uzantısını kullanırız. Bu uzantı Learn Yazma Paketi'nin bir parçası olarak yüklenir.

Boş satırlar, boşluklar ve sekmeler

Boş satırlar markdown'daki bir bloğun sonunu da gösterir.

  • Farklı türlerdeki Markdown bloklarının arasına tek bir boşluk koyun; örneğin, bir paragrafla liste veya üst bilgi arasında.
  • Birden fazla boş satır kullanmayın. Birden çok boş satır HTML'de tek bir boş satır olarak işlenir, bu nedenle fazladan boş satırlar gereksizdir.
  • Kod bloğuna ardışık birden çok boş satır koymayın, ardışık boş satırlar kod bloğunu kırar.

Markdown'da aralık önemlidir.

  • Satırların sonundaki fazladan boşlukları kaldırın. Sondaki boşluklar Markdown'ın görüntülenme biçimini değiştirebilir.
  • Her zaman sekmeler (sabit sekmeler) yerine boşluk kullanın.

Başlıklar ve alt başlıklar

Yalnızca ATX başlıklarını (#veya = stil üst bilgilerinin aksine - stil) kullanın.

  • Cümle başı harf kullanımı - yalnızca özel isimler ve başlığın veya başlık üzerindeki ilk harf büyük harfle yazılmalıdır
  • Başlığın # ve ilk harfi arasına tek bir boşluk ekleme
  • Başlıkları tek boş satırla çevreleme
  • Belge başına birden fazla H1 kullanmayın
    • İlk üst bilgi olmalıdır
    • Makalenin başlığıyla eşleşmelidir
  • Başlık düzeylerini bir seviye yükseltin - düzeyleri atlamayın
  • Derinliği H3 veya H4 ile sınırla
  • Başlıklar'da kalın veya diğer işaretlemeleri kullanmaktan kaçının

Satır uzunluğunu 100 karakterle sınırla

Kavramsal makaleler ve cmdlet başvurusu için satırları 100 karakterle sınırlayın. Makaleler için about_ satır uzunluğunu 79 karakterle sınırlayın. Farkların ve geçmişin git okunabilirliğini artırmak için çizgi uzunluğunu sınırlamak faydalıdır. Ayrıca diğer yazarların katkıda bulunmalarını kolaylaştırır.

Paragrafları belirtilen satır uzunluğuna uyacak şekilde yeniden akıtmak için VS Code'da Reflow Markdown uzantısını kullanın.

Bazı içerik türleri kolayca yeniden akıtılamaz. Örneğin, içeriğe ve kod diline bağlı olarak kod bloklarının içindeki kodun yeniden akıtılması da zor olabilir. Tabloyu yeniden düzenleyemezsiniz. Bu gibi durumlarda, içeriği mümkün olduğunca 100 karakterlik sınıra yakın tutmak için en iyi kararınızı kullanın.

Vurgu

Markdown, vurgu için kalın ve italik yazı biçimlerini destekler. Markdown, vurguyu işaretlemek için * veya _ kullanmanıza olanak tanır. Ancak tutarlı olmak ve amacı göstermek için:

  • ** kullanarak kalın yapın
  • Italik yazı için _ kullanın

Bu deseni uygulamak, belgede kalın ve italik bir karışım olduğunda başkalarının işaretlemenin amacını anlamasını kolaylaştırır.

Listeler

Listenizde birden çok cümle veya paragraf varsa, liste yerine alt düzey üst bilgisi kullanmayı göz önünde bulundurun.

Listeleri tek bir boş satırla çevreleyin.

Sırasız listeler

  • Birden çok cümle içermedikleri sürece liste öğelerini noktalı olarak sonlandırmayın.
  • Liste öğesi madde işaretleri için kısa çizgi karakterini (-) kullanın, yıldız işareti (*) kullanan vurgu işaretlemesi ile karışıklığı önlemek için.
  • Madde işareti öğesinin altına paragraf veya başka öğeler eklemek için, satır sonu ekleyin ve girintiyi madde işaretinden sonraki ilk karakterle hizalayın.

Örneğin:

This is a list that contains child elements under a bullet item.

- First bullet item

  Sentence explaining the first bullet.

  - Child bullet item

    Sentence explaining the child bullet.

- Second bullet item
- Third bullet item

Bu, madde işaretiyle gösterilen bir öğe altında bulunan alt öğeleri içeren bir listedir.

  • İlk madde işareti öğesi

    İlk maddeyi açıklayan cümle.

    • Alt madde işareti öğesi

      Çocuk mermisini açıklayan cümle.

  • İkinci nokta öğesi

  • Üçüncü madde işareti

Sıralı listeler

  • Numaralandırılmış listedeki tüm öğeler, her öğeyi artırmak yerine sayıyı 1. kullanmalıdır.
    • Markdown işlemesi değeri otomatik olarak artırır.
    • Bu, öğeleri yeniden sıralamayı kolaylaştırır ve alt içeriğin girintisini standartlaştırır.
  • Numaralandırılmış öğenin altına paragraf veya başka öğeler eklemek için, girintiyi öğe numarasından sonraki ilk karakterle hizalayın.

Örneğin:

1. For the first element, insert a single space after the `1`. Long sentences should be wrapped to
   the next line and must line up with the first character after the numbered list marker.

   To include a second element, insert a line break after the first and align indentations. The
   indentation of the second element must line up with the first character after the numbered list
   marker.

1. The next numbered item starts here.

Sonuçta elde edilen Markdown'ın görünümü aşağıdaki şu şekildedir.

  1. İlk öğe için, öğesinin 1arkasına tek bir boşluk ekleyin. Uzun cümleler bir sonraki satıra kaydırılmalıdır ve numaralandırılmış liste işaretçisinin sonraki ilk karakteriyle hizalanmalıdır.

    İkinci bir öğe eklemek için, ilk öğeden sonra bir satır sonu ekleyin ve girintileri hizalayın. İkinci öğenin girintisi, numaralandırılmış liste işaretçisinin sonraki ilk karakteriyle hizalanmalıdır.

  2. Sonraki numaralandırılmış öğe burada başlar.

Resimler

Resim eklemek için söz dizimi şöyledir:

![[alt text]](<folderPath>)

Example:
![Introduction](./media/overview/Introduction.png)

Burada alt text görüntünün kısa bir açıklamasıdır ve <folderPath> görüntünün göreli yoludur.

  • Görme engelliler için ekran okuyucuları desteklemek için alternatif metin gereklidir.
  • Görüntüler, makalenin bulunduğu klasörün içindeki bir media/<article-name> klasörde depolanmalıdır.
    • Klasörün altında media makalenizin dosya adıyla eşleşen bir klasör oluşturun. Bu makalenin görüntülerini bu yeni klasöre kopyalayın.
  • Makaleler arasında resim paylaşmayın.
    • Bir resim birden çok makale tarafından kullanılıyorsa, her klasörde bu görüntünün bir kopyası olmalıdır.
    • Bu, bir makaledeki görüntüde yapılan değişikliğin başka bir makaleyi etkilemesini önler.

Aşağıdaki görüntü dosyası türleri desteklenir: *.png, *.gif, *.jpeg, , *.jpg, *.svg

Markdown uzantısı - Uyarı kutuları

Learn Yazma Paketi, yayımlama sistemimize özgü özellikleri destekleyen araçlar içerir. Uyarılar, içeriğin önemini vurgulayan renkler ve simgelerle işlenen blok alıntıları oluşturmaya yönelik bir Markdown uzantısıdır. Aşağıdaki uyarı türleri desteklenir:

> [!NOTE]
> Information the user should notice even if skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Essential information required for user success.

> [!CAUTION]
> Negative potential consequences of an action.

> [!WARNING]
> Dangerous certain consequences of an action.

Bu uyarılar Microsoft Learn'de şöyle görünür:

Nota bloğu

Uyarı

Kullanıcının fark etmesi gereken bilgiler( skimming olsa bile).

İpucu bloğu

Tavsiye

Kullanıcının daha başarılı olmasına yardımcı olmak için isteğe bağlı bilgiler.

Önemli blok

Önemli

Kullanıcı başarısı için gerekli temel bilgiler.

Uyarı bloğu

Dikkat

Bir eylemin olumsuz olası sonuçları.

Uyarı bloğu

Uyarı

Bir eylemin bazı sonuçları tehlikeli.

Markdown uzantısı - Tablolar

Tablo, aşağıdakilerden oluşan satırlar ve sütunlar içeren bir veri düzenlemesidir:

  • Tek bir üst bilgi satırı
  • Üst bilgiyi verilerden ayıran ayırıcı satır
  • Sıfır veya daha fazla veri satırı

Her satır, kanallar (|) ile ayrılmış rastgele metin içeren hücrelerden oluşur. Netlik açısından ön ve arka ayırıcı borunun kullanımı da önerilir. Kanallar ve hücre içeriği arasındaki boşluklar kırpılır. Blok düzeyi öğeler tabloya eklenemez. Bir satırın tüm içeriği tek bir satırda olmalıdır.

Ayırıcı satır, içeriği yalnızca kısa çizgiler (-) olan hücrelerden oluşur ve isteğe bağlı olarak baştaki veya sondaki iki nokta üst üste (:), ya da her ikisi birden, sırasıyla sol, sağ veya orta hizalamayı belirtmek için kullanılabilir.

Küçük tablolar için bunun yerine bir liste kullanmayı göz önünde bulundurun. Listeler şunlardır:

  • Bakımı ve okuması daha kolay
  • 100 karakterlik çizgi sınırına sığacak şekilde yeniden akıtılabilir
  • Görsel yardım için ekran okuyucu kullanan kullanıcılar için daha erişilebilir

Daha fazla bilgi için, Microsoft Learn için Markdown başvuru kılavuzuTablolar bölümüne bakın.

  • Köprüler Markdown söz dizimlerini [friendlyname](url-or-path)kullanmalıdır.

  • Yayımlama sistemi üç tür bağlantıyı destekler:

    • URL bağlantıları
    • Dosya bağlantıları
    • Çapraz referans bağlantıları

  • Dış web sitelerine yönelik tüm URL'ler, hedef site için geçerli olmadığı sürece HTTPS kullanmalıdır.

  • Bağlantıların, genellikle bağlantılı makalenin başlığı olan anlamlı bir ada sahip olması gerekir

  • Köprü köşeli ayraçlarının içinde ters tırnak işareti, kalın veya diğer işaretleme kullanmaktan kaçının.

  • Belirli bir URI'yi belgelerken çıplak URL'ler kullanılabilir, ancak arka uçlar içine alınmalıdır. Örneğin:

    By default, if you don't specify this parameter, the DMTF standard resource URI
`http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/` is used and the class name is appended to it.

  • İzin verilen yerlerde bağlantı referanslarını kullanın. Paragrafların içindeki bağlantı başvuruları, paragrafları daha okunabilir hale getirir.

    Bağlantı referansları, Markdown bağlantılarını iki bölüme böler:

    • bağlantı referansı - [friendlyname][id]
    • bağlantı tanımı - [id]: url-or-path
  • üzerindeki learn.microsoft.com diğer makalelere yönelik URL bağlantıları, site göreli yollarını kullanmalıdır. Site 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 kaldırmaktır https://learn.microsoft.com/en-us .
  • Microsoft özelliklerindeki URL'lere veya Wikipedia bağlantılarına bölge veya dil ayarları eklemeyin ve URL'den /en-us etiketini kaldırın.
  • URL'den gereksiz sorgu parametrelerini kaldırın. Kaldırılması gereken örnekler:
    • ?view=powershell-5.1 - PowerShell'in belirli bir sürümüne bağlanmak için kullanılır
    • ?redirectedfrom=MSDN - Eski bir makaleden yeni konumuna yönlendirildiğinde URL'ye eklenir
  • Belgenin belirli bir sürümüne bağlanmanız gerekiyorsa, parametresini &preserve-view=true sorgu dizesine eklemeniz gerekir. Örneğin: ?view=powershell-5.1&preserve-view=true
  • Microsoft sitelerinde URL bağlantıları dosya uzantıları içermez (örneğin, hayır .md)
  • Dosya bağlantısı, bir başvuru makalesinden diğerine veya aynı docset'teki kavramsal bir makaleden diğerine bağlanmak için kullanılır.
    • Kavramsal bir makaleden başvuru makalesine bağlantı vermeniz gerekiyorsa URL bağlantısı kullanmanız gerekir.
    • Başka bir belge kümesindeki veya depolardaki bir makaleye bağlantı vermeniz gerekiyorsa URL bağlantısı kullanmanız gerekir.
  • Göreli dosya yolları kullanma (örneğin: ../folder/file.md)
  • Tüm dosya yolları eğik çizgi (/) karakterleri kullanır
  • Dosya uzantısını ekleyin (örneğin, .md)

Çapraz başvuru bağlantıları, yayımlama sistemi tarafından desteklenen özel bir özellik. .NET API'sine veya cmdlet başvurusuna bağlanmak için kavramsal makalelerde çapraz başvuru bağlantılarını kullanabilirsiniz.

  • .NET API referans bağlantıları için merkezi Katkıda Bulunan Kılavuzu'ndaki Belgelerdeki Bağlantıları Kullanma bölümüne bakın.

  • Cmdlet komut başvuru bağlantıları şu biçimdedir: xref:<module-name>.<cmdlet-name>. Örneğin, Get-Content modülündeki cmdlet'e bağlanmak için.

    [Get-Content](xref:Microsoft.PowerShell.Management.Get-Content)

Derin bağlantı

Hem URL hem de dosya bağlantılarında derin bağlamaya izin verilir.

  • Tutturucu metni küçük harf olmalıdır
  • Tutturucuyu hedef yolun sonuna ekleyin. Örneğin:
    • [about_Splatting](about_Splatting.md#splatting-with-arrays)
    • [custom key bindings](https://code.visualstudio.com/docs/getstarted/keybindings#_custom-keybindings-for-refactorings)

Daha fazla bilgi için bkz. Belgelerde bağlantıları kullanma.

Kod aralıkları

Kod yayılma alanları, paragraf içindeki satır içi kod parçacıkları için kullanılır. Bir kod parçasını belirtmek için tek ters tırnak işaretleri kullanın. Örneğin:

PowerShell cmdlet names use the `Verb-Noun` naming convention.

Bu örnek şu şekilde görüntülenir:

PowerShell cmdlet adları adlandırma kuralını kullanır Verb-Noun .

Kod blokları

Kod blokları komut örnekleri, çok satırlı kod örnekleri, sorgu dilleri ve çıkışlar için kullanılır. Makale dosyasında metnin bir bölümünün bir kod bloğu olduğunu belirtmenin iki yolu vardır: bunu üç tane ters tırnak işareti (```) ile çevreleyerek veya girintili olarak.

Yanlış anlamak çok kolay olduğundan ve başka bir yazarın makalenizi düzenlemesi gerektiğinde amacınızı anlaması zor olabileceği için hiçbir zaman girinti kullanmayın.

Çevrelenmiş kod blokları, blokta yer alan dil söz dizimini gösteren isteğe bağlı bir etiket içerebilir. Yayımlama platformu , dil etiketlerinin listesini destekler. Dil etiketi, makale web sayfasında işlendiğinde söz dizimi vurgulama sağlamak için kullanılır. Dil etiketi büyük/küçük harfe duyarlı değildir, ancak birkaç özel durum dışında küçük harf kullanmanız gerekir.

  • Söz dizimi blokları veya söz dizimi vurgulamanın gerekli olmadığı diğer içerik türleri için etiketleri olmayan kod çitleri kullanılabilir.
  • Bir komutun çıktısını gösterirken, dil etiketiyle Outputetiketli bir kod çiti kullanın. İşlenen kutu Çıkış olarak etiketlenmiştir ve söz dizimi vurgulama özelliğine sahip değildir.
  • Çıktı belirli bir desteklenen dildeyse uygun dil etiketini kullanın. Örneğin, birçok komut JSON çıkışı sağlar json , bu nedenle etiketini kullanın.
  • Desteklenmeyen bir dil etiketi kullanırsanız kod bloğu söz dizimi vurgulamadan işlenir. Dil etiketi, web sayfasındaki işlenmiş kod kutusunun etiketi olur. Etiketi büyük harfle yazın, böylece etiket web sayfasında büyük harfle görünür.

Sonraki Adımlar

PowerShell stil kılavuzu

  • Last updated on