Szablon metadanych i szablon języka Markdown dla dokumentów platformy .NET

Artykuł
08/10/2023

Ten szablon z repozytorium dotnet/docs zawiera przykładową składnię języka Markdown oraz wskazówki dotyczące ustawiania metadanych.

Tworząc plik Markdown, skopiuj załączony szablon do nowego pliku, wypełnij metadane zgodnie z poniższym opisem i ustaw nagłówek H1 na tytuł artykułu.

Metadane

Poniższy przykład zawiera wymagany blok 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

Miedzy dwukropkiem (:) a wartością elementu metadanych musi znajdować się spacja.
Obecność dwukropków w wartości (na przykład w tytule) zakłóca działanie analizatora metadanych. W takim przypadku należy ująć tytuł w podwójny cudzysłów (na przykład title: "Writing .NET Core console apps: An advanced step-by-step guide").
title: ta wartość pojawia się w wynikach wyszukiwania. Tytuł nie powinien być taki sam jak tytuł w nagłówku H1. Ponadto może on zawierać maksymalnie 60 znaków.
description: podsumowanie zawartości artykułu. Ta wartość zwykle pojawia się na stronie z wynikami wyszukiwania, ale nie jest używana do klasyfikacji wyszukiwania. Liczba znaków (łącznie ze spacjami) powinna mieścić się w przedziale od 115 do 145.
author: pole autora powinno zawierać nazwę użytkownika w usłudze GitHub.
ms.date: data ostatniej ważnej aktualizacji. Tę wartość należy aktualizować w przypadku artykułów, które zostały zmodyfikowane podczas przeglądania. Drobniejsze poprawki, na przykład literówki, nie wymagają aktualizacji.

Do poszczególnych artykułów są dołączone inne metadane, ale większość wartości metadanych zwykle stosuje się na poziomie folderu za pośrednictwem pliku docfx.json.

Podstawowa składnia Markdown, elementy GFM i znaki specjalne

Podstawowe informacje o językach Markdown i GitHub Flavored Markdown (GFM) oraz rozszerzeniach specyficznych dla platformy OPS można znaleźć w artykule Dokumentacja języka Markdown.

Język Markdown używa znaków specjalnych, takich jak *, ', i # do formatowania. Jeśli chcesz dodać do zawartości jeden z tych znaków, musisz wykonać jedną z tych 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 *).

Nazwy plików

W przypadku nazw plików obowiązują następujące reguły:

Można używać tylko małych liter, cyfr i łączników.
Bez spacji i znaków interpunkcyjnych. Wyrazy i liczby w nazwie pliku powinny być oddzielane łącznikami.
Należy używać czasowników oznaczających określoną akcję, np. „develop”, „buy”, „build”, „troubleshoot”. Bez wyrazów zakończonych na „-ing”.
Bez krótkich wyrazów, takich jak „a”, „and”, „the”, „in”, „or” itp.
Nazwa musi być podana w języku znaczników Markdown i mieć rozszerzenie pliku MD.
Nazwy plików powinny być względnie krótkie. Stanowią one część adresów URL artykułów.

Nagłówki

Wielkość liter powinna być taka jak w zdaniu. Pierwszy wyraz nagłówka musi w każdym przypadku zaczynać się od wielkiej litery.

Styl tekstu

Kursywa
Należy ją stosować w przypadku plików, folderów, ścieżek (długie ciągi należy rozdzielić na dodatkowe wiersze) i nowych terminów.

Pogrubienie
Należy je stosować w przypadku elementów interfejsu użytkownika.

Code
Ten element należy stosować w przypadku kodu wbudowanego, słów kluczowych języka, nazw pakietów NuGet, poleceń używanych w wierszu polecenia, nazw tabeli i kolumn w bazie danych oraz adresów URL, które nie są przeznaczone do klikania.

Linki

Informacje dotyczące kotwic, linków wewnętrznych, linków prowadzących do innych dokumentów, klauzuli dołączeń w kodzie oraz linków zewnętrznych można znaleźć w ogólnym artykule Links (Linki).

Zespół, który zajmuje się dokumentacją platformy .NET stosuje następujące konwencje:

W większości przypadków używamy linków względnych. Unikamy używania elementu ~/, ponieważ linki względne są rozpoznawane w źródle w usłudze GitHub. Jednak w przypadku linków do plików znajdujących się w repozytorium zależnym ścieżka jest podawana za pomocą znaku ~/. Pliki z repozytorium zależnego znajdują się w innej lokalizacji w usłudze GitHub, dlatego linki względne nie zostaną poprawnie rozpoznane, niezależnie od tego, jak zostały napisane.
Dodanie specyfikacji języków C# i Visual Basic do dokumentacji platformy .NET odbywa się przez dołączenie źródła z repozytoriów języka. Źródła elementów markdown są zarządzane w repozytoriach csharplang i vblang.

Linki do specyfikacji muszą prowadzić do katalogów źródłowych, które zawierają 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 jest wyposażony w rozszerzenia, które umożliwiają tworzenie połączeń z interfejsami API platformy .NET bez używania linków zewnętrznych. Można użyć jednej z następujących składni:

Link automatyczny: <xref:UID> lub <xref:UID?displayProperty=nameWithType>

Parametr zapytania displayProperty prowadzi do utworzenia tekstu z w pełni kwalifikowanym linkiem. Domyślnie tekst linku zawiera tylko nazwę elementu członkowskiego lub typu.
Link języka Markdown: [link text](xref:UID)

Jest używany, aby można było dostosować wyświetlany tekst linku.

Przykłady:

<xref:System.String> jest renderowany jako String
<xref:System.String?displayProperty=nameWithType> jest renderowany jako System.String
[String class](xref:System.String) jest renderowany jako klasa String

Aby uzyskać więcej informacji na temat używania tej notacji, zobacz artykuł Using cross reference (Używanie odsyłacza).

Niektóre identyfikatory UID zawierają znaki specjalne ", # lub *, wartość UID musi być zakodowana odpowiednio jako %60, %23 i %2A . Czasami można zobaczyć zakodowane nawiasy, ale nie są one wymagane.

Przykłady:

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

Na stronie https://xref.learn.microsoft.com/autocomplete można znaleźć identyfikatory UID typów, listę przeciążeń składowych lub konkretną przeciążoną składową. Ciąg zapytania ?text=*\<type-member-name>* identyfikuje typ lub składową, której identyfikatory UID chcesz wyświetlić. Na przykład element https://xref.learn.microsoft.com/autocomplete?text=string.format pobiera przeciążenia metody String.Format. Narzędzie szuka udostępnionego parametru zapytania text w każdej części identyfikatora UID. Na przykład można wyszukiwać nazwę składowej (ToString), część nazwy składowej (ToStri), typ i nazwę składowej (Double.ToString) itp.

Jeśli dodasz * (lub %2A) po identyfikatorze UID, link reprezentuje stronę przeciążenia, a nie określony interfejs API. Możesz na przykład użyć tej funkcji, jeśli chcesz połączyć się z listą<T>. Strona metody BinarySearch w ogólny sposób zamiast określonego przeciążenia, takiego jak Lista<T>. BinarySearch(T, IComparer<T>). Można również użyć *, aby połączyć się ze stroną składową, gdy element członkowski nie jest przeciążony; Spowoduje to zapisanie konieczności uwzględnienia listy parametrów w identyfikatorze UID.

Aby utworzyć link do określonego przeciążenia metody, musisz dołączyć w pełni kwalifikowane nazwy typów wszystkich parametrów metody. Na przykład <element xref:System.DateTime.ToString> łączy się z bez parametrów metodą DateTime.ToString, a <element 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> łączy się z typem T> System.Nullable<, a linki <xref:System.Func%602> do delegata System.Func<T,TResult>.

Kod

Najlepsza metoda dodania kodu polega na dodaniu fragmentów z działającego przykładu. Utwórz własny przykład, wykonując instrukcje podane w artykule dotyczącym współtworzenia platformy .NET. Dołączenie fragmentów kodu z pełnych programów gwarantuje, że cały kod jest przetwarzany w systemie ciągłej integracji (CI). Jeśli jednak chcesz zademonstrować błędy kompilacji lub błędy w czasie wykonywania, możesz użyć bloków kodu wbudowanego.

Aby uzyskać informacje o składni Markdown na potrzeby pokazywania kodu w dokumentach, zobacz Jak dołączać kod do dokumentów.

Grafika

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)

Filmy wideo

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

> [!VIDEO <youtube_video_link>]

Na przykład:

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

rozszerzenia learn.microsoft

learn.microsoft udostępnia kilka dodatkowych rozszerzeń do języka Markdown w usłudze GitHub Flavored.

Listy ze znacznikami wyboru

W przypadku list dostępny jest styl niestandardowy. Można 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

Renderowanie zostanie przeprowadzone w następujący sposób:

Jak utworzyć aplikację .NET Core
Jak dodać odwołanie do pakietu Microsoft.XmlSerializer.Generator
Jak edytować plik MyApp.csproj, aby dodać zależności
Jak dodać klasę i obiekt XmlSerializer
Jak skompilować i uruchomić aplikację

Przykładowe listy ze znacznikami wyboru można znaleźć w dokumentacji platformy .NET Core.

Przyciski

Linki do przycisków:

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