Sjabloon voor metagegevens en Markdown voor .NET-documenten

Artikel
08/10/2023

Deze dotnet/docs-sjabloon bevat voorbeelden van Markdown-syntaxis en aanwijzingen voor het instellen van metagegevens.

Wanneer u een Markdown-bestand maakt, moet u de opgenomen sjabloon naar een nieuw bestand kopiëren, de metagegevens invullen zoals hierna is aangegeven en de kop H1 boven de titel van het artikel zetten.

Metagegevens

Het vereiste blok met metagegevens bevindt zich in het volgende voorbeeldblok met metagegevens:

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

Tussen de dubbele punt (:) en de waarde van een metagegevenselement moet een spatie staan.
Dubbele punten in een waarde (zoals een titel) verbreken de metagegevensparser. Omring in dit geval de titel met dubbele aanhalingstekens (bijvoorbeeld title: "Writing .NET Core console apps: An advanced step-by-step guide").
titel: Deze wordt in zoekprogrammaresultaten weergegeven. De titel mag niet identiek zijn aan de titel in uw kop H1 en moet maximaal 60 tekens bevatten.
beschrijving: Hierin wordt de inhoud van het artikel samengevat. Deze wordt meestal in de pagina met zoekresultaten weergegeven, maar wordt niet gebruikt voor de rangschikking van de zoekresultaten. De lengte dient 115 tot 145 tekens te bedragen, inclusief spaties.
auteur: Het veld Auteur moet de GitHub-gebruikersnaam van de auteur bevatten.
ms.date: De datum van de laatste belangrijke update. Werk deze bij voor bestaande artikelen als u het gehele artikel hebt bekeken en bijgewerkt. Kleine aanpassingen, zoals typfouten e.d., rechtvaardigen geen update.

Er zijn andere metagegevens aan elk artikel toegevoegd, maar wij passen gewoonlijk de meeste metagegevenswaarden toe op mapniveau, zoals is opgegeven in docfx.json.

Elementaire Markdown, GFM en speciale tekens

U kunt de basisbeginselen van Markdown, GitHub Flavored Markdown (GFM) en OPS-specifieke extensies leren in het artikel Markdown-naslaginformatie.

Markdown gebruikt speciale tekens, zoals *, ', en # voor opmaak. Als u een van deze tekens in uw inhoud wilt opnemen, moet u een van de volgende stappen ondernemen:

Plaats een backslash vóór het speciale teken om het te 'escapen' (bijvoorbeeld \* voor een *).
Gebruik de HTML-entiteitscode voor het teken (bijvoorbeeld * voor een *).

Bestandsnamen

Voor bestandsnamen zijn de volgende regels van toepassing:

Deze bevatten alleen kleine letters, cijfers en afbreekstreepjes.
Deze bevatten geen spaties of leestekens. Deze maken gebruik van afbreekstreepjes als scheidingsteken tussen woorden en getallen in de bestandsnaam.
Gebruik specifieke actieve werkwoorden, zoals ontwikkelen, kopen, maken, problemen oplossen. Geen onvoltooid tegenwoordige tijd.
Geen kleine woorden: gebruik niet 'een', 'en', 'de', 'in', 'of', 'enz.'
De indeling moet Markdown zijn en de bestandsextensie .md.
Houd de bestandsnamen redelijk kort. Deze maken deel uit van de URL voor uw artikelen.

Koppen

Gebruik zinnen met hoofdletters. Begin het eerste woord van een koptekst altijd met een hoofdletter.

Tekststijl

Cursief
Gebruik deze stijl voor bestanden, mappen, paden (voor lange items, op hun eigen regel gesplitst), nieuwe termen.

Vet
Gebruik deze stijl voor elementen in de gebruikersinterface.

Code
U kunt deze stijl gebruiken voor inline-code, sleutelwoorden voor de taal, NuGet-pakketnamen, opdrachten in opdrachtregels, databasetabel- en kolomnamen en URL's waarvan u niet wilt dat erop kan worden geklikt.

Koppelingen

Raadpleeg het algemene artikel over Koppelingen voor informatie over ankers, interne koppelingen, koppelingen naar andere documenten, insluiting van code en externe koppelingen.

Het .NET-documententeam maakt gebruik van de volgende conventies:

In de meeste gevallen gebruiken we de relatieve koppelingen en ontmoedigen het gebruik van ~/ in koppelingen, omdat relatieve koppelingen worden opgehaald in de bron op GitHub. Wanneer we echter een koppeling maken naar een bestand in een afhankelijke opslagplaats, gebruiken we het ~/-teken om het pad op te geven. Aangezien de bestanden in de afhankelijke opslagplaats zich op een andere locatie bevinden in GitHub, worden de koppelingen niet correct opgehaald met relatieve koppelingen, ongeacht de wijze waarop deze zijn geschreven.
De specificaties voor de computertaal C# en taal de Visual Basic zijn in de .NET-documenten opgenomen door de bron in te voegen vanuit de taalopslagplaatsen. De Markdown-bronnen worden beheerd in de opslagplaatsen csharplang en vblang.

Koppelingen naar specificaties moeten verwijzen naar de bronmappen waarin die specificaties zijn opgenomen. Voor C# is dit ~/_csharplang/spec en voor Visual Basic is dit ~/_vblang/spec, zoals in het volgende voorbeeld:

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

Koppelingen naar API's

Het build-systeem bevat enkele extensies waarmee we koppelingen kunnen maken met .NET-API's zonder externe koppelingen te hoeven gebruiken. U gebruikt een van de volgende typen syntaxis:

Automatisch koppelen: <xref:UID> of <xref:UID?displayProperty=nameWithType>

De queryparameter displayProperty produceert een volledig gekwalificeerde koppelingstekst. Standaard toont de koppelingstekst alleen de naam van het lid of het type.
Markdown-koppeling: [link text](xref:UID)

Gebruik deze als u de weergegeven koppelingstekst wilt aanpassen.

Voorbeelden:

<xref:System.String> weergeven als String
<xref:System.String?displayProperty=nameWithType> weergeven als System.String
[String class](xref:System.String) weergeven als String class

Bekijk Using cross reference (Kruisverwijzing gebruiken) voor meer informatie over het gebruik van deze notatie.

Sommige UID's bevatten de speciale tekens ', # of *, de waarde van de UID moet html zijn gecodeerd als %60respectievelijk en %2A%23. U ziet soms haakjes in de code, maar dat is geen vereiste.

Voorbeelden:

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

U kunt de UID's opzoeken van typen, evenals een lijst van overbelaste leden of een bepaald overbelast lid vanuit https://xref.learn.microsoft.com/autocomplete. Via de querytekenreeks ?text=*\<type-member-name>* wordt het type of lid geïdentificeerd waarvan of van wie de UID's zijn die u wilt zien. Met https://xref.learn.microsoft.com/autocomplete?text=string.format worden bijvoorbeeld de overbelastingen ten aanzien van String.Format opgehaald. Met het hulpprogramma zoekt u naar de opgegeven queryparameter text ergens in de UID. U kunt bijvoorbeeld zoeken naar de naam van het lid (ToString), een gedeelte daarvan (ToStri), de naam van het type en lid (Double.ToString) enz.

Als u een * (of %2A) toevoegt na de UID, vertegenwoordigt de koppeling vervolgens de overbelastingspagina en niet een specifieke API. U kunt deze bijvoorbeeld gebruiken wanneer u een koppeling wilt maken naar de lijst<T>. BinarySearch Method-pagina op een algemene manier in plaats van een specifieke overbelasting, zoals Lijst<T>. BinarySearch(T, IComparer<T>). U kunt * ook gebruiken om een koppeling naar een lidpagina te maken wanneer het lid niet overbelast is; Dit voorkomt dat u de lijst met parameters in de UID moet opnemen.

Als u een koppeling wilt maken met een overbelasting van een specifieke methode, moet u de volledig gekwalificeerde typenaam van alle parameters van de methode opnemen. Bijvoorbeeld: <xref:System.DateTime.ToString is gekoppeld aan de methode DateTime.ToString> zonder parameter, terwijl <xref:System.DateTime.ToString(System.String,System.IFormatProvider)> is gekoppeld aan de methode DateTime.ToString(String,IFormatProvider).

Als u een koppeling wilt maken naar een algemeen type, zoals System.Collections.Generic.List<T>, gebruikt u het teken ' (%60), gevolgd door het aantal algemene typeparameters. Bijvoorbeeld, <xref:System.Nullable%601> koppelingen naar het System.Nullable<T-type> , terwijl <xref:System.Func%602> koppelingen naar de gemachtigde System.Func<T,TResult> .

Code

De beste manier om code in te voegen is fragmenten van een werkend voorbeeld in te voegen. Maak uw voorbeeld op basis van de instructies in het artikel Bijdragen aan .NET. Wanneer u fragmenten uit volledige programma's invoegt, zorgt dit ervoor dat alle code via ons CI-systeem (Continue integratie) gaat. Als u echter iets moet weergeven wat voor compilatietijd- of runtimefouten zorgt, kunt u codeblokken in regels gebruiken.

Voor meer informatie over de Markdown-syntaxis om code in docs weer te geven, raadpleegt u Code in opnemen in docs-artikelen.

Afbeeldingen

Statische afbeelding of GIF-animatie

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

Gekoppelde afbeelding

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

Video's

U kunt YouTube-video's insluiten in een Markdown-bestand. Klik met de rechtermuisknop op de video, selecteer Insluitcode kopiëren en kopieer de URL vanuit het <iframe>-element om de juiste URL van de video te krijgen.

> [!VIDEO <youtube_video_link>]

Bijvoorbeeld:

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

learn.microsoft extensions

learn.microsoft biedt enkele extra extensies voor GitHub Flavored Markdown.

Gecontroleerde lijsten

Er is een aangepaste stijl beschikbaar voor lijsten. U kunt lijsten met groene vinkjes renderen.

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

Dit wordt weergegeven als:

Een .NET Core-app maken
Een verwijzing toevoegen aan het pakket Microsoft.XmlSerializer.Generator
MyApp.csproj zo bewerken dat u afhankelijkheden kunt toevoegen
Een klasse en een XmlSerializer toevoegen
De toepassing bouwen en uitvoeren

U kunt in de .NET Core-documenten een voorbeeld zien van gecontroleerde lijsten in actie.

Knoppen

Knopkoppelingen:

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