Metadata a šablona v Markdownu pro dokumentaci k .NET

Článek
08/10/2023

Tato šablona pro dotnet/dokumentaci obsahuje příklady syntaxe jazyka Markdown a pokyny k nastavení metadat.

Při vytváření souboru Markdown zkopírujte přiloženou šablonu do nového souboru, vyplňte metadata podle návodu níže a nastavte nadpis H1 výše na název článku.

Metadata

Požadovaný blok metadat je v následujícím ukázkovém bloku metadat:

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

Mezi dvojtečkou (:) a hodnotou prvku metadat musí být mezera.
Dvojtečky v hodnotě (třeba v nadpisu) způsobí chybu analyzátoru metadat. V takovém případě dejte nadpis do dvojitých uvozovek (příklad: title: "Writing .NET Core console apps: An advanced step-by-step guide").
title (název): Zobrazí se ve výsledcích vyhledávačů. Nadpis nemusí být stejný jako nadpis v záhlaví H1 a nesmí být delší než 60 znaků.
description (popis): Shrnuje obsah článku. Většinou se zobrazuje na stránce s výsledky hledání, ale nepoužívá se k řazení výsledků hledání. Měl by mít 115–145 znaků (včetně mezer).
author (autor): Pole autora musí obsahovat uživatelské jméno autora na GitHubu.
ms.date: Datum poslední významné aktualizace. U stávajících článků datum aktualizujte, pokud zkontrolujete a aktualizujete celý článek. U malých oprav, jako jsou opravy překlepů apod., nejde o aktualizaci.

Ke každému článku jsou připojená další metadata, ale většinu hodnot metadat obvykle používáme na úrovni složky zadané v souboru docfx.json.

Základy jazyka Markdown (GFM) a speciální znaky

Základní informace o jazyce Markdown, variantě GitHub Flavored Markdown (GFM) a rozšířeních specifických pro OPS najdete v článku Referenční informace k jazyku Markdown.

Markdown používá pro formátování speciální znaky, například *, ', a #. Pokud chcete některý z těchto znaků přidat do obsahu, máte na výběr dvě možnosti:

Před speciální znak umístěte zpětné lomítko, \* abyste ho "utekli" (například pro znak *).
Pro znak použijte kód entity HTML (například * pro znak *).

Názvy souborů

Pro názvy souborů platí následující pravidla:

Smí obsahovat jenom malá písmena, číslice a pomlčky.
Nesmí obsahovat mezery ani interpunkční znaménka. K oddělení slov a čísel v názvu souboru používejte pomlčky.
Používejte slovesa, která vyjadřují určitou činnost, třeba develop (vyvíjet), buy (koupit), build (sestavit) nebo troubleshoot (řešit potíže). Nepoužívejte slova s koncovkou -ing.
Nepoužívejte krátká slova (nepoužívejte členy a spojky a, and, the, in, or atd.).
Musí být ve formátu Markdown a mít příponu souboru .md.
Názvy souborů musí být krátké, protože tvoří část adresy URL vašich článků.

Nadpisy

Používejte velká písmena jako při psaní věty. První slovo v nadpisu musí začínat velkým písmenem.

Styl textu

Kurzíva
Použijte pro soubory, složky, cesty (dlouhé položky dejte na samostatný řádek) a nové výrazy.

Tučné
Použijte pro prvky uživatelského rozhraní.

Code
Použijte pro vložený kód, klíčová slova jazyka, názvy balíčků NuGet, příkazy příkazového řádku, názvy databázových tabulek a sloupců a pro adresy URL, které nemají fungovat jako odkaz, na který se dá kliknout.

Odkazy

Informace o ukotveních, interních odkazech, odkazech na jiné dokumenty, zahrnutém kódu a externích odkazech najdete v obecném článku o odkazech.

Tým pro dokumentaci k .NET používá následující konvence:

Ve většině případů používáme relativní odkazy. V odkazech nedoporučujeme používat znak ~/, protože relativní odkazy se překládají ve zdroji na GitHubu. Pokud ale odkazujeme na soubor v závislém úložišti, použijeme v cestě znak ~/. Soubory v závislém úložišti jsou v GitHubu umístěné jinde, a proto se tyto odkazy nepřeloží správně s relativními odkazy bez ohledu na způsob jejich zápisu.
Specifikace jazyka C# a specifikace jazyka Visual Basic zahrnete do dokumentace k .NET tak, že uvedete zdroj z jazykových úložišť. Zdroje v Markdownu jsou spravované v úložištích csharplang a vblang.

Odkazy na specifikaci musí mířit na zdrojové adresáře s touto specifikací. Pro C# je to ~/_csharplang/spec a pro VB je to ~/_vblang/spec, jak vidíte v následujícím příkladu:

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

Odkazy na rozhraní API

Kompilační systém má několik přípon, které umožňují vytvořit odkaz na rozhraní .NET API bez použití externích odkazů. Použijte jednu z následujících syntaxí:

Automatické propojení: <xref:UID> nebo <xref:UID?displayProperty=nameWithType>

Parametr dotazu displayProperty vytvoří plně kvalifikovaný text odkazu. Ve výchozím nastavení text odkazu zobrazuje pouze název člena nebo typu.
Odkaz Markdownu: [link text](xref:UID)

Tento způsob použijte, když chcete přizpůsobit zobrazený text odkazu.

Příklady:

<xref:System.String> se zobrazí jako String.
<xref:System.String?displayProperty=nameWithType> se zobrazí jako System.String.
[String class](xref:System.String) se zobrazí jako třída String.

Další informace o použití tohoto zápisu najdete v části Použití křížového odkazu.

Některé uživatelské rozhraní obsahují speciální znaky ', # nebo *, hodnota UID musí být kódována ve formátu HTML a %60%23%2A v uvedeném pořadí. Někdy v tomto formátu uvidíte i závorky, není to ale povinné.

Příklady:

System.Threading.Tasks.Task'1 se změní na System.Threading.Tasks.Task%601
System.Exception.#ctor se změní na System.Exception.%23ctor
System.Lazy'1.#ctor(System.Threading.LazyThreadSafetyMode) se změní na System.Lazy%601.%23ctor%28System.Threading.LazyThreadSafetyMode%29

Identifikátory UID typů, seznam přetížení členů nebo určitého přetíženého člena najdete na adrese https://xref.learn.microsoft.com/autocomplete. Řetězec dotazu ?text=*\<type-member-name>* identifikuje typ nebo člena, jehož identifikátory UID chcete vidět. Třeba https://xref.learn.microsoft.com/autocomplete?text=string.format načte přetížení String.Format. Nástroj vyhledá zadaný parametr dotazu text v libovolné části identifikátoru UID. Můžete třeba hledat jméno člena (ToString), část jména člena (ToStri), typ a jméno člena (Double.ToString) atd.

Pokud za UID přidáte * (nebo %2A), odkaz pak představuje stránku přetížení, a ne konkrétní rozhraní API. Můžete ho použít například v případě, že chcete vytvořit odkaz na seznam<T>. Stránka metody BinarySearch obecným způsobem místo konkrétního přetížení, jako je Seznam<T>. BinarySearch(T; IComparer<T>). Můžete také použít * pro odkaz na stránku člena, pokud člen není přetížen; Díky tomu nemusíte do UID zahrnout seznam parametrů.

Pokud chcete vytvořit odkaz na určité přetížení metody, musíte do všech parametrů metody zahrnout úplně určený název typu. Například <xref:System.DateTime.ToString> odkazuje na metodu DateTime.ToString bez parametrů, zatímco <xref:System.DateTime.ToString(System.String,System.IFormatProvider)> odkazuje na metodu DateTime.ToString(String,IFormatProvider).

Chcete-li vytvořit odkaz na obecný typ, například System.Collections.Generic.List<T>, použijte znak ' (%60) následovaný počtem parametrů obecného typu. Například <xref:System.Nullable%601> odkazy na typ System.Nullable<T> a odkazy <xref:System.Func%602> na delegáta System.Func<T,TResult> .

Kód

Nejlepší způsob, jak zahrnout kód, je použít fragmenty kódu z funkční ukázky. Vytvořte ukázku podle pokynů v článku o příspěvcích pro .NET. Tím, že zahrnete fragmenty kódu z celých programů, zajistíte spustitelnost veškerého kódu v našem systému kontinuální integrace (CI). Pokud ale chcete předvést něco, co způsobuje chyby při kompilaci nebo spuštění, můžete použít vložené bloky kódu.

Informace o syntaxi Markdown pro zobrazení kódu v dokumentech najdete v tématu Jak do dokumentů vkládat kód.

Obrázky

Statický obrázek nebo animovaný GIF

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

Propojený obrázek

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

Videa

Videa z YouTube můžete vložit do souboru Markdownu. Pokud chcete získat správnou adresu URL videa, klikněte na něj pravým tlačítkem, vyberte Kopírovat kód pro vložení a zkopírujte adresu URL z prvku <iframe>.

> [!VIDEO <youtube_video_link>]

Například:

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

rozšíření learn.microsoft

learn.microsoft poskytuje několik dalších rozšíření GitHub Flavored Markdown.

Seznamy se zaškrtávacími políčky

Pro seznamy je k dispozici vlastní styl. Můžete zobrazit seznamy se zelenými zaškrtnutími.

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

Zobrazí se takto:

Vytvoření aplikace v .NET Core
Přidání odkazu do balíčku Microsoft.XmlSerializer.Generator
Úprava souboru MyApp.csproj a přidání závislostí
Přidání třídy a objektu XmlSerializer
Sestavení a spuštění aplikace

Příklad použití seznamů se zaškrtávacími políčky najdete v dokumentaci k .NET Core.

Tlačítka

Odkazy na tlačítka:

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