Dela via

Riktlinjer för formatering av text

  • Artikel

Konsekvent och lämplig användning av fet stil, kursiv stil och kod för textelement förbättrar läsbarheten och förhindrar att texten missförstås.

Fetstil

Använd fet stil för UI-element som menyalternativ, namn på dialogrutor och namn på indatafält.

Exempel

  • Detta: Högerklicka på projektnoden i Solution Explorer och välj sedan Lägg till > nytt objekt.
  • Inte så här: Högerklicka på projektnoden i Solution Explorer och välj sedan Lägg till > nytt objekt.
  • Inte så här: Högerklicka på projektnoden i Solution Explorer och välj sedan Lägg till > nytt objekt.

Kursiv stil

Använd kursiv stil för:

  • Nya termer du introducerar med en definition eller förklaring.
  • Filnamn, mappnamn, sökvägar.
  • Användarindata.

Exempel

  • Så här: En app körs i en App Service-plan i App Service. En App Service-plan definierar en uppsättning beräkningsresurser som en webbapp körs på.
  • Inte så här: I App Service körs en app i en "App Service-plan". En App Service-plan definierar en uppsättning beräkningsresurser som en webbapp ska köras på.
  • Detta: Ersätt koden i HttpTriggerCSharp.cs med följande kod.
  • Inte så här: Ersätt koden i HttpTriggerCSharp.cs med följande kod.
  • Detta: Ange ContosoUniversity som Namn och välj sedan Lägg till.
  • Inte så här: Ange "ContosoUniversity" som Namn och välj sedan Lägg till.

Kodstil

Använd kodstil för:

  • Kodelement som till exempel metodnamn, egenskapsnamn och nyckelord.
  • SQL-kommandon
  • Namn på NuGet-paket
  • Kommandoradskommandon*
  • Namn på tabeller och kolumner i databaser
  • Resursnamn som inte ska lokaliseras (till exempel namn på virtuella datorer)
  • Webbadresser som du inte vill ska vara klickbara

Varför? Äldre formatguider kan påbjuda fetstil för många av de här textelementen. De flesta artiklar är dock lokaliserade, och kodstilen anger för översättaren att den delen av texten som lämnas oöversatt.

Kodformatet kan vara infogat (omgivet av ") eller inhägnat kodblock (omgivet av "") som sträcker sig över flera rader. Sätt längre kodfragment och sökvägar i inhägnade kodblock.

* Använd snedstreck i filsökvägar i kommandoradskommandon om de stöds på alla plattformar. Använd omvänt snedstreck för att illustrera kommandon som körs i Windows, när endast omvänt snedstreck stöds. Till exempel fungerar snedstreck på .NET CLI på alla plattformar, så du använder dotnet build foldername/filename.csproj i stället dotnet build foldername\filename.csprojför .

Exempel på infogat format

  • Så här: Som standard tolkar Entity Framework en egenskap som har namnet Id eller ClassnameID som den primära nyckeln.
  • Inte så här: Som standard tolkar Entity Framework en egenskap som har namnet ID eller ClassnameID som den primära nyckeln.
  • Så här: Paketet Microsoft.EntityFrameworkCore har stöd för körning av EF Core.
  • Inte så här: Paketet Microsoft.EntityFrameworkCore har stöd för körning av EF Core.

Exempel på inhägnade kodblock

  • Så här: Inga kommandon skickas till databasen via uttryck som bara ändrar en IQueryable, till exempel följande kod:

        ```csharp
    var students = context.Students.Where(s => s.LastName == "Davolio")
    ```

  • Inte så här: Inga kommandon skickas till databasen med instruktioner som bara ändrar en IQueryable, till exempel var students = kontext. Students.Where(s => s.LastName == "Davolio").

  • Så här: För att till exempel köra skriptet Get-ServiceLog.ps1 i mappen C:\Scripts skriver du:

        ```powershell
    C:\Scripts\Get-ServiceLog.ps1
    ```

  • Inte så här: För att till exempel köra skriptet Get-ServiceLog.ps1 i mappen C:\Scripts skriver du: "C:\Scripts\Get-ServiceLog.ps1."

  • Alla inhägnade kodblock måste ha en godkänd språktagg. Du hittar en lista med stöd språktaggar som stöds i Så här inkluderar du kod i dokument.

Platshållare

Om du vill att användaren ska ersätta en del av en indatasträng med sina egna värden använder du platshållartext markerad med vinkelparenteser (mindre än < och större än > tecken).

Alternativ 1: Använd kodformatering för att omge platshållarordet eller den omfattande frasen. Du kan till exempel använda enkla backticks för infogad kodformatering för en enda fras eller trippel-ticks för kodstängd formatering.

`az group delete -n <ResourceGroupName>`

Återges som:

az group delete -n <ResourceGroupName>

eller

Alternativ 2: Använd ett omvänt snedstreck \ för att undkomma vinkelparentestecken i Markdown, till exempel \< och \>. Även om endast den första flykten på den vänstra vinkelparentesen \< krävs, fungerar det för att undvika den avslutande hakparentesen \> för konsekvens. Den renderade HTML-koden visar inte escape-tecknet för läsaren:

az group delete -n \<ResourceGroupName\>

Återges som:

az group delete -n <ResourceGroupName>

Informera läsaren om platshållaren: I texten före sådana platshållarexempel förklarar du för läsaren att texten inom hakparenteser måste tas bort och ersättas med verkliga värden. Vi rekommenderar användning av kursiv stil för användarindata. Du kan formatera kursiv stil inom vinkelparenteserad infogad kod:

I följande exempel ersätter du platshållartexten <ResourceGroupName> med ditt eget resursgruppsnamn.

Varning

Microsoft Learn-webbplatsen återger <inte platshållartext> som använder vinkelparenteser i fall där hakparenteserna inte är korrekt undantagna eller om texten inte är kodformaterad. Microsoft Learn-kompileringsprocessen tolkar platshållarfrasen> som en HTML-tagg som kan vara farlig för läsarens webbläsare och flaggar <den som en otillåten html-tagg. Du ser ett förslag i byggrapporten och platshållarordet återges inte i Microsoft Learn-sidans utdata när det händer.

Om du vill undvika innehållsförlust på platshållare använder du code formatering eller escape-tecken (\< \>) enligt beskrivningen tidigare.

Vi avråder från att använda klammerparenteser { } som syntaktiska platshållare. Läsare kan blanda ihop klammerparenteser med samma notation som används i:

  • Ersättningsbar text
  • Formatsträngar
  • Stränginterpolering
  • Textmallar
  • Liknande programmeringskonstruktioner

Hölje och avstånd: Du kan separera platshållarnamn med bindestreck ("kebabfall") eller med understreck, eller så kan du göra det med hjälp av Pascal-skiftläge. Ett kebabfall kan generera syntaxfel och understreck kan vara i konflikt med understreck. All-caps kan vara i konflikt med namngivna konstanter på många språk, men det kan också uppmärksamma platshållarnamnet.

<Resource-Group-Name> eller <ResourceGroupName>

Rubriker och länktext

Använd inte ett infogat format, till exempel kursiv stil eller fetstil på rubriker eller hyperlänktext.

Varför?

Användare ser hyperlänktext och identifierar dem som textelement med klickbara länkar. Att formatera en länk som kursiv stil kan till exempel dölja det faktum att texten är en länk. Rubriker har egna format och om de blandas med andra format ser det inte bra ut.

Exempel på rubriker och länktext

  • Detta: Filen function.json genereras av NuGet-paketet Microsoft.NET.Sdk.Functions.

  • Inte så här: Filen function.json genereras av NuGet-paketet Microsoft.NET.Sdk.Functions.

  • Så här:

    ### The Microsoft.NET.Sdk.Functions package

  • Inte så här:

    ### The *Microsoft.NET.Sdk.Functions* package

Tangenter och kortkommandon

Följ de här riktlinjerna när du hänvisar till tangenter eller tangentkombinationer:

  • Skriv den första bokstaven i namn på tangenter med en versal.
  • Omge nyckelnamnen med <kbd> och </kbd> HTML-taggarna.
  • Använd "+" för att koppla nycklar som användaren väljer samtidigt.

Exempel på nycklar och kortkommandon

  • Detta: Välj Alt+Ctrl+S.
  • Inte så här: Tryck på ALT+CTRL+S.
  • Inte så här: Tryck på ALT+CTRL+S.

Undantag

Riktlinjerna för formatering är inte strikta regler. Du kan kringgå dem om de gör texten mer svårläst. En HTML-tabell som innehåller många kodelement kan till exempel vara svåröverskådlig. Då kan du använda fetstil i stället.

Om du väljer ett alternativt textformat där du normalt skulle använda kod måste du kontrollera att texten kan översättas i lokaliserade versioner av artikeln. Kodstilen är den enda stil som automatiskt förhindrar översättning. I situationer där du vill förhindra lokalisering utan att använda kodstil kan du läsa Strängar som inte ska lokaliseras.