Dela via

Metadata- och Markdown-mall för .NET-dokument

  • Artikel

Den här dotnet/docs-mallen innehåller exempel på Markdown-syntax, samt anvisningar för hur du anger metadata.

När du skapar en Markdown-fil kopierar du mallen som ingår till en ny fil, fyller i de metadata som anges nedan och anger H1-rubriken ovan som rubrik för artikeln.

Metadata

Metadatablocket som krävs finns i följande exempel på metadatablock:

---
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
  • Du måste ha ett mellanrum mellan kolontecknet (:) och värdet för ett metadataelement.
  • Kolontecknet i ett värde (exempelvis en rubrik) bryter metadatatolkaren. I det här fallet omger du rubriken med dubbla citattecken (exempelvis title: "Writing .NET Core console apps: An advanced step-by-step guide").
  • title: Visas i sökmotorresultaten. Rubriken ska inte vara identisk med din H1-rubrik och får innehålla maximalt 60 tecken.
  • description: Sammanfattar innehållet i artikeln. Detta visas vanligtvis på sökresultatsidan, men används inte vid sökrankning. Längden ska vara 115–145 tecken inklusive mellanslag.
  • author: Författarfältet ska innehålla författarens GitHub-användarnamn.
  • ms.date: Datum för den senaste viktiga uppdateringen. Uppdatera detta i befintliga artiklar om du har granskat och uppdaterat hela artikeln. Små korrigeringar som stavfel eller liknande kräver inte någon uppdatering.

Andra metadata bifogas varje artikel men vi tillämpar de flesta metadatavärden på mappnivå, vilket anges i docfx.json.

Grundläggande Markdown, GFM och specialtecken

Du kan lära dig grunderna i Markdown, GitHub Flavored Markdown (GFM) och OPS-specifika undantag i artikeln Markdown-referens.

Markdown använder specialtecken som *, och # för formatering. Om du vill inkludera ett eller flera av dessa tecken i ditt innehåll, måste du göra något av följande:

  • Placera ett omvänt snedstreck före specialtecknet för att "fly" det (till exempel \* för ett *).
  • Använd HTML-entitetskoden för tecknet (till exempel * för en *).

Filnamn

Filnamn använder sig av följande regler:

  • Innehåller endast gemener, siffror och bindestreck.
  • Inga blanksteg eller skiljetecken. Använd bindestreck för att avgränsa ord och siffror i filnamnet.
  • Använd åtgärdsverb som är specifika, exempelvis ”utveckla”, ”köpa”, ”bygga” och ”felsöka”. Inga ord som slutar på ”-ing”.
  • Inga korta ord – ta inte med ord som ”en”, ”ett”, ”och”, ”den”, ”i” osv.
  • Måste finns i Markdown och ha filnamnstillägget .md.
  • Håll filnamnen så korta som möjligt. De ingår i URL:en för dina artiklar.

Sidhuvud

Använd gemener och versaler i meningen på ett normalt sätt. En rubrik ska alltid ha en inledande versal.

Textformat

Kursiv stil
Använd för filer, mappar, sökvägar (vid långa objekt kan du dela upp till en egen rad), nya termer.

Fet stil
Används för gränssnittselement.

Code
Använd för infogad kod, språknyckelord, NuGet-paketnamn, kommandoradskommandon, databastabell- och kolumnnamn, samt URL:er som inte ska vara klickbara.

Se den allmänna artikeln om Länkar för att få information om fästpunkter, interna länkar, länkar till andra dokument, kodinkluderingar och externa länkar.

Teamet för .NET-dokument använder följande konventioner:

  • I de flesta fall använder vi relativa länkar och vi uppmuntrar inte att ~/ används i länkar, eftersom relativa länkar omvandlas i GitHub-källan. Men när vi länkar till en fil på en beroende lagringsplats, använder vi tecknet ~/ för sökvägen. Eftersom filerna på den beroende lagringsplatsen finns på en annan plats i GitHub, kommer länkarna inte att omvandlas korrekt med relativa länkar oavsett hur de skrivs.
  • Språkspecifikationen för C# och Visual Basic ingår i .NET-dokumenten eftersom källan från språklagringsplatserna inkluderas. Markdown-källorna hanteras på lagringsplatserna csharplang och vblang.

Länkar till specifikationen måste peka på källkatalogerna där dessa specifikationer finns. För C# är det ~/_csharplang/spec och för VB är det ~/_vblang/spec, som i följande exempel:

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

Systemet innehåller vissa tillägg som vi kan använda för att länka till .NET-API:er utan att externa länkar behöver användas. Du kan använda någon av följande syntax:

  1. Automatisk länk: <xref:UID> eller <xref:UID?displayProperty=nameWithType>

    Frågeparametern displayProperty producerar en fullständigt kvalificerad länktext. Som standard visar länktexten bara medlems- eller typnamnet.

  2. Markdown-länk: [link text](xref:UID)

    Använd när du vill anpassa den länktext som visas.

Exempel:

  • <xref:System.String> renderas som Sträng
  • <xref:System.String?displayProperty=nameWithType> renderas som System.Sträng
  • [String class](xref:System.String) renderas som Sträng-klass

Mer information om hur du använder den här notationen finns i Använd korsreferens.

Vissa användargränssnitt innehåller specialtecken , # eller *, UID-värdet måste vara HTML-kodat som %60respektive %23%2A . Ibland ser du parenteser kodade, men det är inget krav.

Exempel:

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

Du kan hitta UID:erna för typer, en överlagrad medlemslista eller en specifik överlagrad medlem på https://xref.learn.microsoft.com/autocomplete. Frågesträngen ?text=*\<type-member-name>* identifierar typen eller medlemmen vars UID:er du vill se. https://xref.learn.microsoft.com/autocomplete?text=string.format hämtar t.ex. överlagringar för String.Format. Verktyget söker efter angiven text-frågeparameter i alla delar av UID:n. Du kan exempelvis söka efter medlemsnamn (ToString), delar av medlemsnamn (ToStri), typ och medlemsnamn (Double.ToString), etc.

Om du lägger till en * (eller %2A) efter UID:t representerar länken överlagringssidan och inte ett specifikt API. Du kan till exempel använda det när du vill länka till listan<T>. Sidan BinarySearch-metod på ett allmänt sätt i stället för en specifik överlagring, till exempel lista<T>. BinarySearch(T, IComparer<T>). Du kan också använda * för att länka till en medlemssida när medlemmen inte är överbelastad. Detta gör att du inte behöver inkludera parameterlistan i UID: et.

Om du vill länka till en specifik metodöverlagring, måste du inkludera det fullständiga typnamnet för var och en av metodens parametrar. Till exempel <länkar xref:System.DateTime.ToString> till den parameterlösa metoden DateTime.ToString, medan <xref:System.DateTime.ToString(System.String,System.IFormatProvider)> länkar till metoden DateTime.ToString(String,IFormatProvider).

Om du vill länka till en generisk typ, till exempel System.Collections.Generic.List<T>, använder du tecknet ' (%60) följt av antalet parametrar av generisk typ. Till exempel <xref:System.Nullable%601> länkar till T-typen System.Nullable<>, medan <xref:System.Func%602> länkar till ombudet System.Func<T,TResult>.

Kod

Bästa sättet att inkludera kod på är att inkludera kodfragment från ett arbetsexempel. Skapa ditt exempel genom att följa anvisningarna i artikeln om att bidra till .NET. Genom att kodfragment inkluderas från de fullständiga programmen, säkerställer man att all kod körs via vårt CI-system för kontinuerlig integrering. Men om du behöver visa något som orsakar kompileringstid eller körningsfel, kan du använda infogade kodblock.

Mer information om Markdown-syntaxen för att visa kod i dokument finns i Så här inkluderar du kod i dokumenten.

Bilder

Statisk bild eller animerad GIF

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

Länkad bild

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

Video

Du kan bädda in YouTube-videor i en Markdown-fil. Om du vill ha videons korrekta URL högerklickar du på videon. Välj sedan Kopiera inbäddad kod och kopiera URL:en från <iframe>-elementet.

> [!VIDEO <youtube_video_link>]

Till exempel:

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

learn.microsoft-tillägg

learn.microsoft tillhandahåller några ytterligare tillägg till GitHub Flavored Markdown.

Kontrollerade listor

Det finns en anpassad stil för listor. Du kan rendera listor med gröna bockmarkeringar.

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

Detta renderas som:

  • Så här skapar du en .NET Core-app
  • Så här lägger du till en referens till paketet Microsoft.XmlSerializer.Generator
  • Så här redigerar du ditt MyApp.csproj och lägger till beroenden
  • Så här lägger du till en klass och en XmlSerializer
  • Så här skapar och kör du programmet

Du kan se ett exempel på de kontrollerade listor som används i .NET Core-dokumenten.

Knappar

Knapplänkar:

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

Detta renderas som:

knapplänkar

Du kan se ett exempel på de knappar som används i Visual Studio-dokumenten.

Anvisningar

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

Du kan se ett exempel på se anvisningar som används i C#-guiden.