Szablon metadanych i języka Markdown dla dokumentacji platformy .NET

Ten szablon dotnet/docs zawiera przykłady składni języka Markdown i wskazówki dotyczące ustawiania metadanych.

Podczas tworzenia pliku markdown skopiuj dołączony szablon do nowego pliku, wypełnij metadane zgodnie z poniższym opisem i ustaw nagłówek H1 powyżej na tytuł artykułu.

Metadane

Wymagany blok metadanych znajduje się w następującym przykładowym bloku metadanych:

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

• Musisz mieć odstęp między dwukropkiem (:) a wartością elementu metadanych.
• Dwukropki w wartości (na przykład tytuł) zakłócają działanie analizatora metadanych. W tym przypadku umieść tytuł podwójnym cudzysłowem (na przykład title: "Writing .NET Core console apps: An advanced step-by-step guide").
• title: pojawia się w wynikach wyszukiwarki. Tytuł nie powinien być identyczny z tytułem w nagłówku H1 i powinien zawierać 60 znaków lub mniej.
• description: podsumowuje zawartość artykułu. Zazwyczaj jest ona wyświetlana na stronie wyników wyszukiwania, ale nie jest używana do klasyfikowania wyszukiwania. Jego długość powinna zawierać od 115 do 145 znaków, w tym spacje.
• author: pole autora powinno zawierać nazwę użytkownika usługi GitHub autora.
• ms.date: data ostatniej istotnej aktualizacji. Zaktualizuj je w istniejących artykułach, jeśli przejrzeno i zaktualizowano cały artykuł. Małe poprawki, takie jak literówki lub podobne, nie uzasadniają aktualizacji.

Inne metadane są dołączane do każdego artykułu, ale zazwyczaj stosujemy większość wartości metadanych na poziomie folderu określonym w docfx.json.

Podstawowe Markdown, GFM i znaki specjalne

Podstawowe informacje na temat języka Markdown, GitHub Flavored Markdown (GFM) i rozszerzeń specyficznych dla platformy OPS można poznać w artykule referencyjnym języka Markdown .

Język Markdown używa znaków specjalnych, takich jak *, ', i # do formatowania. Jeśli chcesz dołączyć jeden z tych znaków do zawartości, musisz wykonać jedną z dwóch czynności:

• Umieść ukośnik odwrotny przed znakiem specjalnym w celu "ucieczki" (na przykład \* dla znaku *).
• Użyj kodu jednostki HTML dla znaku (na przykład * dla znaku *).

Nazwy plików

Nazwy plików używają następujących reguł:

• Zawierają tylko małe litery, cyfry i łączniki.
• Brak spacji ani znaków interpunkcyjnych. Użyj łączników, aby oddzielić wyrazy i liczby w nazwie pliku.
• Używaj konkretnych czasowników akcji, takich jak programowanie, kupowanie, kompilowanie, rozwiązywanie problemów. Brak słów zakończonych na "-ing".
• Nie ma małych słów — nie dołączaj elementu i, w, lub itp.
• Plik musi być zapisany w formacie Markdown i używać rozszerzenia .md.
• Zachowaj nazwy plików rozsądnie krótkie. Są one częścią adresu URL artykułów.

Headings

Użyj wielkich liter w stylu zdania. Zawsze pisz pierwsze słowo nagłówka wielką literą.

Styl tekstu

Italics
Służy do obsługi plików, folderów, ścieżek (w przypadku długich elementów podzielonych na własny wiersz), nowych terminów.

Pogrubiony
Służy do elementów interfejsu użytkownika.

Code
Służy do śródwierszowego kodu, słów kluczowych języka, nazw pakietów NuGet, poleceń wiersza polecenia, nazw tabel bazy danych i kolumn oraz adresów URL, których nie chcesz klikać.

Links

Zapoznaj się z ogólnym artykułem na temat linków, aby uzyskać informacje na temat kotwic, linków wewnętrznych, linków do innych dokumentów, wstawiania kodu i linków zewnętrznych.

Zespół dokumentacji platformy .NET używa następujących konwencji:

• W większości przypadków używamy linków względnych i odradzamy korzystanie z ~/ w linkach, ponieważ linki względne rozwiązują się w źródle na GitHubie. Jednak za każdym razem, gdy łączymy się z plikiem w repozytorium zależnym, użyjemy ~/ znaku , aby podać ścieżkę. Ponieważ pliki w repozytorium zależnym znajdują się w innej lokalizacji w usłudze GitHub, linki nie będą poprawnie rozpoznawane przy użyciu linków względnych niezależnie od sposobu ich zapisu.
• Specyfikacja języka C# i specyfikacja języka Visual Basic są zawarte w dokumentacji platformy .NET przez dołączenie źródła z repozytoriów językowych. Źródła języka Markdown są zarządzane w repozytoriach csharplang i vblang .

Linki do specyfikacji muszą wskazywać katalogi źródłowe, w których są zawarte te specyfikacje. W przypadku języka C#jest to ~/_csharplang/spec , a w przypadku języka VB jest to ~/_vblang/spec, jak w poniższym przykładzie:

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

Linki do interfejsów API

System kompilacji ma pewne rozszerzenia, które umożliwiają nam łączenie się z interfejsami API platformy .NET bez konieczności używania linków zewnętrznych. Należy użyć jednej z następujących składni:

1. Automatyczne linkowanie: <xref:UID> lub <xref:UID?displayProperty=nameWithType>

   Parametr displayProperty zapytania tworzy w pełni kwalifikowany tekst linku. Domyślnie tekst linku zawiera tylko nazwę członka lub typu.

2. Łącze Markdown: [link text](xref:UID)

   Użyj tej funkcji, gdy chcesz dostosować wyświetlany tekst linku.

Examples:

• <xref:System.String> wyświetla się jako ciąg
• <xref:System.String?displayProperty=nameWithType> renderuje jako System.String
• [String class](xref:System.String) przedstawia jako klasę String

Aby uzyskać więcej informacji na temat korzystania z tej notacji, zobacz Używanie odwołania krzyżowego.

Niektóre identyfikatory UID zawierają znaki specjalne ", # lub *, wartość UID musi być zakodowana odpowiednio jako %60, %23 i %2A . Czasami zobaczysz nawiasy zakodowane, ale nie jest to wymagane.

Examples:

• System.Threading.Tasks.Task'1 staje się System.Threading.Tasks.Task%601
• System.Exception.#ctor przekształca się w System.Exception.%23ctor
• System.Lazy'1.#ctor(System.Threading.LazyThreadSafetyMode) staje się System.Lazy%601.%23ctor%28System.Threading.LazyThreadSafetyMode%29

Jeśli dodasz * (lub %2A) po identyfikatorze UID, link będzie odnosił się do strony przeładowania, a nie do konkretnego API. Możesz na przykład użyć tego, gdy chcesz połączyć się z List<T>.BinarySearch Method w sposób ogólny zamiast określonego przeciążenia, takiego jak List<T>.BinarySearch(T, IComparer<T>). Można również użyć *, aby połączyć się ze stroną członka, gdy członek nie jest przeciążony; dzięki temu nie musisz uwzględniać listy parametrów w identyfikatorze UID.

Aby połączyć się ze specyficznym przeciążeniem metody, należy podać w pełni kwalifikowaną nazwę typu każdego parametru tej metody. Na przykład <xref:System.DateTime.ToString> łączy się z bezparametrową metodą DateTime.ToString, podczas gdy <xref:System.DateTime.ToString(System.String,System.IFormatProvider)> łączy się z metodą DateTime.ToString(String,IFormatProvider).

Aby połączyć się z typem ogólnym, takim jak System.Collections.Generic.List<T>, należy użyć znaku " (%60), po którym następuje liczba parametrów typu ogólnego. Na przykład <xref:System.Nullable%601> linkuje do typu System.Nullable<T>, a <xref:System.Func%602> linkuje do delegata System.Func<T,TResult>.

Code

Najlepszym sposobem dołączenia kodu jest uwzględnienie fragmentów kodu z działającego przykładu. Utwórz przykład, postępując zgodnie z instrukcjami w artykule przyczyniania się do .NET. Dołączenie fragmentów kodu z pełnych programów gwarantuje, że cały kod jest uruchamiany za pośrednictwem naszego systemu ciągłej integracji (CI). Jeśli jednak musisz pokazać coś, co powoduje błędy czasu kompilacji lub środowiska uruchomieniowego, możesz użyć wbudowanych bloków kodu.

Aby uzyskać informacje na temat składni języka Markdown służącej do wyświetlania kodu w dokumentacji, zobacz How to include code in docs (Jak dołączać kod w dokumentacji).

Obrazy

Obraz statyczny lub animowany obraz GIF

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

Połączony obraz

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

Videos

Klipy wideo z serwisu YouTube można osadzić w pliku Markdown. Aby uzyskać poprawny adres URL filmu wideo, kliknij go prawym przyciskiem myszy, wybierz polecenie Kopiuj kod osadzania i skopiuj adres URL z <iframe> elementu .

> [!VIDEO <youtube_video_link>]

Przykład:

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

rozszerzenia platformy Learn Microsoft

learn.microsoft oferuje kilka dodatkowych rozszerzeń do GitHub Flavored Markdown.

Listy zaznaczone

Dostępny jest niestandardowy styl dla listy. Możesz renderować listy z zielonymi znacznikami wyboru.

> [!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

Zostanie wyrenderowane jako:

W dokumentacji platformy .NET Core możesz zobaczyć przykład list kontrolnych.

Buttons

Linki przycisków:

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

Zostanie wyrenderowane jako:

Przykład przycisków można zobaczyć w dokumentacji programu Visual Studio.

Kroki krok po kroku

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

Przykład akcji krok po kroku można zobaczyć w przewodniku języka C#.