Metagegevens en Markdown-sjabloon voor .NET-documenten

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

Wanneer u een Markdown-bestand maakt, kopieert u de opgenomen sjabloon naar een nieuw bestand, vult u de metagegevens in zoals hieronder is opgegeven en stelt u de H1-kop boven in op de titel van het artikel.

Metagegevens

Het vereiste metagegevensblok bevindt zich in het volgende voorbeeldmetagegevensblok:

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

• Je moet een spatie hebben tussen de dubbele punt (:) en de waarde voor een metadatatag.
• Dubbele punten in een waarde (bijvoorbeeld een titel) veroorzaken verstoringen in de metagegevensparser. In dit geval plaatst u de titel tussen dubbele aanhalingstekens (bijvoorbeeld title: "Writing .NET Core console apps: An advanced step-by-step guide").
• titel: Wordt weergegeven in de zoekresultaten van de zoekmachine. De titel mag niet identiek zijn aan de titel in de H1-kop en moet 60 tekens of minder bevatten.
• beschrijving: Geeft een overzicht van de inhoud van het artikel. Deze wordt meestal weergegeven op de pagina met zoekresultaten, maar wordt niet gebruikt voor zoekclassificatie. De lengte moet 115-145 tekens zijn, inclusief spaties.
• auteur: Het veld Auteur moet de GitHub-gebruikersnaam van de auteur bevatten.
• ms.date: de datum van de laatste belangrijke update. Werk dit bij op bestaande artikelen als u het hele artikel hebt gecontroleerd en bijgewerkt. Kleine fixes, zoals typfouten of vergelijkbare, rechtvaardigen geen update.

Andere metagegevens worden aan elk artikel gekoppeld, maar meestal worden de meeste metagegevenswaarden toegepast op mapniveau, die zijn opgegeven in docfx.json.

Basic Markdown, GFM en speciale tekens

U kunt de basisprincipes van Markdown, GitHub Flavored Markdown (GFM) en OPS-specifieke extensies in het Naslagartikel voor Markdown leren.

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 twee dingen doen:

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

Bestandsnamen

Bestandsnamen gebruiken de volgende regels:

• Alleen kleine letters, cijfers en afbreekstreepjes bevatten.
• Geen spaties of leestekens. Gebruik de afbreekstreepjes om woorden en getallen in de bestandsnaam te scheiden.
• Gebruik actiewoorden die specifiek zijn, zoals ontwikkelen, kopen, bouwen, problemen oplossen. Geen woorden die eindigen op -ing.
• Gebruik geen kleine woorden: geen a, en, de, in, of, en dergelijke opnemen.
• Moet in Markdown staan en de bestandsextensie .md gebruiken.
• Houd bestandsnamen redelijk kort. Ze maken deel uit van de URL voor uw artikelen.

Headings

Gebruik hoofdlettergebruik in zinsstijl. Het eerste woord van een kop altijd hoofdletters maken.

Tekststijl

Italics
Gebruik voor bestanden, mappen, paden, (voor lange items, splitsen naar een eigen regel), nieuwe termen.

Vet
Gebruik voor UI-elementen.

Code
Gebruik deze functie voor inlinecode, taaltrefwoorden, NuGet-pakketnamen, opdrachtregelopdrachten, databasetabel- en kolomnamen en URL's waarop u niet wilt klikken.

Links

Zie het algemene artikel over koppelingen voor informatie over ankers, interne koppelingen, koppelingen naar andere documenten, code-insluitingen en externe koppelingen.

Het .NET-docs-team gebruikt de volgende conventies:

• In de meeste gevallen gebruiken we relatieve koppelingen en raden we het gebruik van ~/ in koppelingen af omdat relatieve koppelingen worden opgelost 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. Omdat de bestanden in de afhankelijke opslagplaats zich op een andere locatie in GitHub bevinden, worden de koppelingen niet correct omgezet met relatieve koppelingen, ongeacht de manier waarop ze zijn geschreven.
• De C#-taalspecificatie en de Visual Basic-taalspecificatie zijn opgenomen in de .NET-documenten door de bron uit de taalopslagplaatsen op te nemen. De Markdown-bronnen worden beheerd in de csharplang - en vblang-opslagplaatsen .

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

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

Koppelingen naar API's

Het buildsysteem heeft enkele extensies waarmee we een koppeling kunnen maken naar .NET-API's zonder externe koppelingen te hoeven gebruiken. U gebruikt een van de volgende syntaxis:

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

   De displayProperty queryparameter produceert een volledig gekwalificeerde koppelingstekst. Standaard wordt in koppelingstekst alleen de naam van het lid of type weergegeven.

2. Markdown koppeling: [link text](xref:UID)

   Gebruik deze tekst als u de weergegeven koppelingstekst wilt aanpassen.

Examples:

• <xref:System.String> wordt weergegeven als tekenreeks
• <xref:System.String?displayProperty=nameWithType> wordt weergegeven als System.String
• [String class](xref:System.String) wordt weergegeven als tekenreeksklasse

Zie Kruisverwijzing gebruiken voor meer informatie over het gebruik van deze notatie.

Sommige UID's bevatten de speciale tekens ', # of *, de UID-waarde moet worden gecodeerd als %60, %23 respectievelijk %2A . Soms ziet u haakjes gecodeerd, maar dit is geen vereiste.

Examples:

• 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

Als u een * (of %2A) toevoegt na de UID, vertegenwoordigt de koppeling de overbelastingspagina en niet een specifieke API. U kunt dit bijvoorbeeld gebruiken wanneer u op een algemene manier een koppeling wilt maken naar de pagina van de List<T>.BinarySearch Method, in plaats van naar een specifieke overload zoals List<T>.BinarySearch(T, IComparer<T>). U kunt ook * gebruiken om een koppeling te maken naar een lidpagina wanneer het lid niet overbelast is; Hierdoor hoeft u de parameterlijst niet op te nemen in de UID.

Als u een koppeling wilt maken naar een specifieke overbelasting van de methode, moet u de volledig gekwalificeerde typenaam van elk van de parameters van de methode opnemen. Bijvoorbeeld: <xref:System.DateTime.ToString> is gekoppeld aan de parameterloze methode DateTime.ToString, 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> koppeling naar het type System.Nullable<T>, terwijl <xref:System.Func%602> koppelt naar gedelegeerde System.Func<T, TResult>.

Code

De beste manier om code op te nemen, is door fragmenten uit een werkvoorbeeld op te nemen. Maak uw voorbeeld volgens de instructies in het bijdragen aan .NET-artikel . Het opnemen van fragmenten uit volledige programma's zorgt ervoor dat alle code wordt uitgevoerd via ons CI-systeem (Continuous Integration). Als u echter iets moet weergeven dat compilatietijd- of runtimefouten veroorzaakt, kunt u inlinecodeblokken gebruiken.

Zie Code opnemen in documenten voor informatie over de Markdown-syntaxis voor het weergeven van code in documenten.

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)

Videos

U kunt YouTube-video's insluiten in een Markdown-bestand. Als u de juiste URL van de video wilt ophalen, klikt u met de rechtermuisknop op de video, selecteert u Invoegcode kopiëren en kopieert u de URL uit het <iframe> element.

> [!VIDEO <youtube_video_link>]

Voorbeeld:

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

learn.microsoft-extensies

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

Gecontroleerde lijsten

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

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

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

Buttons

Knoplinks:

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

Dit wordt weergegeven als:

U ziet een voorbeeld van knoppen in actie in de Visual Studio-documenten.

Stapsgewijze instructies

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

In de C#-handleiding ziet u een voorbeeld van stapsgewijze stappen in actie.