Metaadatok és Markdown-sablon .NET-dokumentumokhoz

Cikk
08/10/2023

Ez a dotnet/docs sablon példákat tartalmaz a Markdown szintaxisára, valamint útmutatást a metaadatok beállításához.

Markdown-fájl létrehozásakor át kell másolnia a megadott sablont az új fájlba, ki kell töltenie a metaadatokat az alább megadott módon, a fenti H1 címsorban pedig a cikk címét kell megadnia.

Metaadatok

A szükséges metaadatblokk a következő mintául megadott metaadatblokkban található:

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

A kettőspont (:) és a metaadatelem értéke között lennie kell szóköznek.
Az értékben (például a címben) megadott kettőspontok a metaadat-elemző hibás működését eredményezik. Ebben az esetben foglalja a címet kettős idézőjelek közé (például: title: "Writing .NET Core console apps: An advanced step-by-step guide").
title: Megjelenik a keresőmotorok keresési eredményeiben. A cím ne legyen azonos a H1 címsorban megadott címmel, és legfeljebb 60 karaktert tartalmazhat.
description: Összefoglalja a cikk tartalmát. Általában megjelenik a keresési eredmények oldalán, de nem használatos a keresési eredmények rangsorolásához. A hossza 115–145 karakter legyen szóközökkel együtt.
author: Az author (szerző) mezőnek tartalmaznia kell a szerző GitHub-felhasználónevét.
ms.date: A legutóbbi jelentős frissítés dátuma. Frissítse ezt az értéket a meglévő cikkekben, ha áttekintette és átdolgozta a teljes cikket. A kisebb javítások, például az elírások és hasonlók miatt nem szükséges frissíteni az értékét.

Más metaadatok is kapcsolódnak minden cikkhez, de általában a legtöbb metaadatértéket a mappa szintjén alkalmazzuk docfx.json fájlként megadva.

Alapszintű Markdown, GFM és különleges karakterek

A Markdown, a GitHub Flavored Markdown (GFM) és az OPS-specifikus bővítmények alapjait a Markdown-referencia cikkeiből sajátíthatja el.

A Markdown speciális karaktereket használ, például *, ', és # formázást. Ha ezek közül a karakterek közül valamelyiket szeretné belefoglalni a dokumentumba, tegye az alábbi két dolog közül valamelyiket:

Helyezzen egy fordított perjelet a speciális karakter elé, hogy "elkerülje" azt (például \* egy *).
Használja a karakter HTML-entitáskódját (például * a *-hoz).

Fájlnevek

A fájlnevek a következő szabályokat használják:

Csak kisbetűk, számok és kötőjelek használhatók.
Szóköz és írásjelkarakter nem használható. A kötőjel a szavak és számok elválasztására használható.
Konkrét műveleteket használjon, például develop (fejlesztés), buy (vásárlás), build (fordítás), troubleshoot (hibakeresés). Ne használja az angol igék -ing végződésű alakját.
Ne használjon nem önálló szavakat (a, and, the, in, or, etc).
Markdown-formátumot kell használni, .md kiterjesztéssel.
Ésszerűen rövid fájlneveket használjon. Ezek a cikkek URL-címének részei.

Fejlécek

Csak a mondat első betűje legyen nagybetű. A cím első betűje mindig nagybetű legyen.

Szövegstílus

Dőlt
Használja fájlokhoz, mappákhoz, elérési utakhoz (hosszú elemek esetén törje ezeket a saját külön sorukba) és új kifejezésekhez.

Félkövér
Használja a felhasználói felület elemeihez.

Code
Használja beágyazott kódokhoz, programnyelvi kulcsszavakhoz, NuGet-csomagok nevéhez, parancssori parancsokhoz, adatbázistábla és oszlopnevekhez, valamint olyan URL-címekhez, amelyekre nem lehet rákattintani.

Hivatkozások

A horgonyokra, belső hivatkozásokra, más dokumentumokra mutató hivatkozásokra, belefoglalt kódokra és külső hivatkozásokra vonatkozóan olvassa el a Hivatkozások általános cikket.

A .NET-dokumentumok csapata a következő konvenciókat használja:

A legtöbbször relatív hivatkozásokat használunk, és nem javasoljuk ~/ használatát a hivatkozásokban, mert a relatív hivatkozások a forrásban lesznek feloldva a GitHubon. Ha azonban egy függő tárban lévő fájlra hivatkozunk, akkor a ~/ karaktert használjuk az elérési út megadásához. Mivel a függő tárban lévő fájlok más helyen vannak a GitHubon, a hivatkozások feloldása nem lesz megfelelő relatív hivatkozásokkal, függetlenül attól, hogyan írták őket.
A C# nyelvi specifikációk és a Visual Basic nyelvi specifikációk .NET-dokumentumokba való belefoglalása a programnyelvi kódtárakból a forrás belefoglalásával történik. A Markdown-források kezelése a csharplang és a vblang kódtárakban történik.

A specifikációkra mutató hivatkozásoknak azokra a forráskönyvtárakra kell mutatniuk, amelyekben ezek a specifikációk találhatók. C# esetén ez a ~/_csharplang/spec, VB esetén pedig a ~/_vblang/spec, a következő példához hasonlóan:

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

API-kra mutató hivatkozások

A build rendszer rendelkezik néhány bővítménnyel, amelyek lehetővé teszik a .NET API-kra való hivatkozást, anélkül, hogy külső hivatkozásokat kellene használni. Az alábbi szintaxisok egyikét használhatja:

Automatikus hivatkozás: <xref:UID> vagy <xref:UID?displayProperty=nameWithType>

A displayProperty lekérdezési paraméter teljesen minősített hivatkozási szöveget eredményez. Alapértelmezés szerint a hivatkozás szövegében csak a tag vagy a típus neve jelenik meg.
Markdown-hivatkozás: [link text](xref:UID)

Akkor használja, ha testre szeretné szabni a megjelenített hivatkozási szöveget.

Példák:

<xref:System.String>, megjelenítve String
<xref:System.String?displayProperty=nameWithType>, megjelenítve System.String
[String class](xref:System.String), megjelenítve String class

Ezen jelölés használatával kapcsolatban a Kereszthivatkozások használata című témakörben találhat további információt.

Egyes felhasználói felületek a speciális karaktereket (# vagy *) tartalmazzák, az UID-értéknek html kódolásúnak kell lennie, %23 és %2A a karakternek %60kell lennie. Időnként előfordul a zárójelek kódolása, de ez nem kötelező.

Példák:

System.Threading.Tasks.Task'1 lesz System.Threading.Tasks.Task%601
A System.Exception.#ctor System.Exception.%23ctor
System.Lazy'1.#ctor(System.Threading.LazyThreadSafetyMode) System.Lazy%601.%23ctor%28System.Threading.LazyThreadSafetyMode%29

Az UID-típusokat, a tag túlterhelési listáját vagy az adott túlterhelt tagot a https://xref.learn.microsoft.com/autocomplete weblapon találja. A(z) ?text=*\<type-member-name>* lekérdezési sztring azonosítja azt a tagtípust, amelyiknek az UID-jét látni szeretné. A https://xref.learn.microsoft.com/autocomplete?text=string.format például a String.Format túlterheléseket kéri le. Az eszköz a megadott text lekérdezési paramétert az UID bármely részében keresi. Kereshet például a tagnévre (ToString), a tagnév egy részére (ToStri), a típusra és a tagnévre (Double.ToString) stb.

Ha a UID után * (vagy %2A) értéket ad hozzá, akkor a hivatkozás a túlterhelési oldalt jelöli, nem pedig egy adott API-t. Ezt például akkor használhatja, ha a T> listára<szeretne hivatkozni. BinarySearch Metódus lapja általános módon, nem pedig egy adott túlterhelés, például a T> lista<. BinarySearch(T, IComparer<T>). Ha a tag nincs túlterhelve, a * használatával is hivatkozhat taglapra; Ezzel nem kell belefoglalnia a paraméterlistát a UID-be.

Meghatározott metódus-túlterhelésre való hivatkozáshoz meg kell adnia a metódus összes paraméterének teljes típusnevét. Az xref:System.DateTime.ToString például <a paraméter nélküli DateTime.ToString> metódusra mutat, míg <az xref:System.DateTime.ToString(System.String,System.IFormatProvider) a DateTime.ToString(String,IFormatProvider)> metódusra mutat.

Általános típusra( például System.Collections.Generic.List<T>) való hivatkozáshoz használja a " (%60) karaktert, majd az általános típusparaméterek számát. Például <xref:System.Nullable%601> a System.Nullable<T> típusra mutató hivatkozások, míg <xref:System.Func%602> a System.Func<T,TResult> delegáltra mutató hivatkozások.

Code

A kód belefoglalásának legjobb módja kódrészletek belefoglalása egy működő példányból. Hozza létre a mintát a hozzájárulás a .NET-hez cikk útmutatását követve. A teljes programok kódrészleteinek belefoglalása biztosítja, hogy minden kód futtatva legyen a Continuous Integration (CI) rendszerünkben. Ha azonban valami olyasmit kell bemutatnia, ami fordításkori vagy futásidejű hibákat okoz, akkor használhat beágyazott kódblokkokat.

A Kód belefoglalása a dokumentumokba című cikkben további információt talál arról, milyen Markdown-szintaxissal lehet kódot belefoglalni a dokumentumba.

Képek

Statikus képek vagy animált GIF-ek

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

Hivatkozott kép

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

Videók

YouTube-videókat egy Markdown-fájlba ágyazhat be. A videó megfelelő URL-címének beszerzéséhez kattintson a jobb gombbal a videóra, válassza a Beágyazási kód másolása lehetőséget, és másolja ki az URL-címet az <iframe> elemből.

> [!VIDEO <youtube_video_link>]

Példa:

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

learn.microsoft-bővítmények

A learn.microsoft további bővítményeket biztosít a GitHub Flavored Markdownhoz.

Listajeles listák

A listák készítéséhez egyéni stílus használható. A listák zöld pipákkal is megjeleníthetők.

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

Ez így jelenik meg:

.NET Core-alkalmazások létrehozásának módja
Hivatkozás hozzáadása a Microsoft.XmlSerializer.Generator csomaghoz
A MyApp.csproj szerkesztése függőségek hozzáadásához
Osztály és XmlSerializer hozzáadása
Alkalmazás fordítása és futtatása

A listajeles listákra gyakorlati példát a .NET Core-dokumentációban talál.

Gombok

Gombhivatkozások:

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