Docs Markdown-referens

Den här artikeln innehåller en alfabetisk referens för att skriva Markdown för docs.microsoft.com (Docs).

Markdown är ett förenklat märkspråk med syntax för oformaterad textformatering. Docs stöder CommonMark-kompatibel Markdown som parsas via parsningsmotorn Markdig. Docs stöder också anpassade Markdown-tillägg som ger mer omfattande innehåll på Docs-webbplatsen.

Du kan använda valfri textredigerare för att skriva Markdown, men vi Visual Studio kod med Docs-redigeringspaketet. Docs-redigeringspaketet innehåller redigeringsverktyg och förhandsgranskningsfunktioner som gör att du kan se hur dina artiklar kommer att se ut när de återges i Docs.

Alerts (obs, tips, viktigt, varning)

Aviseringar är ett Markdown-tillägg för att skapa blockcitat som återges i Docs med färger och ikoner som anger vikten av innehållet.

Undvik anteckningar, tips och viktiga rutor. Läsare tenderar att hoppa över dem. Det är bättre att placera den informationen direkt i artikeltexten.

Om du behöver använda aviseringar begränsar du dem till en eller två per artikel. Flera kommentarer bör aldrig finnas bredvid varandra i en artikel.

Följande aviseringstyper stöds:

> [!NOTE]
> Information the user should notice even if skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Essential information required for user success.

> [!CAUTION]
> Negative potential consequences of an action.

> [!WARNING]
> Dangerous certain consequences of an action.

De här aviseringarna ser ut så här i Docs:

Vinkelparentes

Om du använder hakparenteser i text i filen (till exempel för att ange en platshållare) måste du koda vinkelparenteserna manuellt. Annars tror Markdown att det är en HTML-tagg.

Koda till exempel <script name> som <script name> eller \<script name> .

Vinkelparenteser behöver inte vara frånslagna i text som formaterats som infogade kod eller i kodblock.

Apostrofer och citattecken

Om du kopierar från Word till en markdown-redigerare kan texten innehålla typografiska (sneda) apostrofer eller citationstecken. Dessa måste vara kodade eller ändras till raka apostrofer eller citattecken. Annars kan det se ut så här när filen publiceras: It’s

Så här skriver du ”smarta” skiljetecken:

• Vänster citattecken: “
• Höger citattecken: ”
• Höger, enkelt citattecken eller apostrof: ’
• Vänster, enkelt citattecken: ‘

Blockcitat

Blockcitat skapas med tecknet >:

> This is a blockquote. It is usually rendered indented and with a different background color.

Föregående exempel återges enligt följande:

Det här är en blockcit. Den återges vanligtvis med indrag och med en annan bakgrundsfärg.

Fet och kursiv stil

Om du vill formatera text somfet omsluter du den med två asterisker:

This text is **bold**.

Om du vill formatera text som kursivomsluter du den med en asterisk:

This text is *italic*.

Om du vill formatera text som både fet och kursivomsluter du den med tre asterisker:

This text is both ***bold and italic***.

Vägledning om när du ska använda fet och kursiv text finns i riktlinjer för textformatering.

Kodfragment

Docs Markdown stöder placering av kodfragment både infogade i en mening och som ett separat "inhägnat" block mellan meningar. Mer information finns i Så här lägger du till kod i docs.

Kolumner

Markdown-tillägget för kolumner ger Docs-författare möjlighet att lägga till kolumnbaserade innehållslayouter som är mer flexibla och kraftfulla än grundläggande Markdown-tabeller, som endast passar för verkliga tabelldata. Du kan lägga till upp till fyra kolumner och använda det valfria span attributet för att sammanfoga två eller flera kolumner.

Även om kolumntillägget fortfarande fungerar rekommenderar vi det inte längre för att skapa anpassade layouter. Vi har upptäckt att många anpassade kolumnlayouter har tillgänglighetsproblem eller på annat sätt bryter mot docs-stilriktlinjerna. Skapa inte anpassade layouter. Använd Docs-standardfunktioner.

Syntaxen för kolumner är följande:

:::row:::
   :::column span="":::
      Content...
   :::column-end:::
   :::column span="":::
      More content...
   :::column-end:::
:::row-end:::

Kolumner ska bara innehålla grundläggande Markdown, inklusive bilder. Rubriker, tabeller, flikar och andra komplexa strukturer bör inte inkluderas. En rad får inte ha något innehåll utanför kolumnen.

Följande Markdown skapar till exempel en kolumn som sträcker sig över två kolumnbredder och en standardkolumn span (ingen):

:::row:::
   :::column span="2":::
      **This is a 2-span column with lots of text.**

      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec vestibulum mollis nunc
      ornare commodo. Nullam ac metus imperdiet, rutrum justo vel, vulputate leo. Donec
      rutrum non eros eget consectetur.
   :::column-end:::
   :::column span="":::
      **This is a single-span column with an image in it.**

      ![Doc.U.Ment](media/markdown-reference/document.png)
   :::column-end:::
:::row-end:::

Detta renderas så här:

Kommentarer

Docs stöder HTML-kommentarer om du måste kommentera ut avsnitt i artikeln:

<!--- Here's my comment --->

Sidhuvud

Docs stöder sex nivåer av Markdown-rubriker:

# This is a first level heading (H1)

## This is a second level heading (H2)

...

###### This is a sixth level heading (H6)

• Det måste finnas ett blanksteg mellan den sista # och rubriktexten.
• Varje Markdown-fil måste ha en och endast en H1-rubrik.
• H1-rubriken måste vara det första innehållet i filen efter YML-metadatablocket.
• H2-rubriker visas automatiskt i navigeringsmenyn till höger i den publicerade filen. Rubriker på lägre nivå visas inte, så använd H2 strategiskt för att hjälpa läsarna att navigera i ditt innehåll.
• HTML-rubriker, till exempel <h1> , rekommenderas inte och i vissa fall kommer att orsaka build-varningar.
• Du kan länka till enskilda rubriker i en fil via bokmärkeslänkar.

HTML

Markdown stöder infogad HTML, men HTML rekommenderas inte för publicering till Docs, och förutom en begränsad lista med värden orsakar byggfel eller varningar.

Avbildningar

Följande filtyper stöds som standard för bilder:

• .jpg
• .png

För att stödja andra avbildningstyper, till exempel .gif, måste du lägga till dem som resurser i docfx.json:

"resource": [
  {
    "files" : [
      "**/*.png",
      "**/*.jpg,
      "**/*.gif"
    ],

Konceptuella standardbilder (markdown som är standard)

Den grundläggande Markdown-syntaxen för att bädda in en bild är:

![<alt text>](<folderPath>)

Example:
![alt text for image](../images/Introduction.png)

<alt text> är en kort beskrivning av bilden och <folder path> är en relativ sökväg till bilden. Alternativ text krävs för skärmläsare för personer med nedsatt syn. Det är också användbart om det finns en webbplatsbugg där bilden inte kan återges.

Understreck i alternativtext återges inte korrekt såvida du inte undviker dem genom att prefixera dem med ett omsnedstreck ( \_ ). Kopiera dock inte filnamn för användning som alternativtext. Till exempel, i stället för detta:

![ADextension_2FA_Configure_Step4](./media/bogusfilename/ADextension_2FA_Configure_Step4.PNG)

Skriv följande:

![Active Directory extension for two-factor authentication, step 4: Configure](./media/bogusfilename/ADextension_2FA_Configure_Step4.PNG)

Konceptuella standardbilder (Docs Markdown)

Det anpassade :::image::: Docs-tillägget stöder standardbilder, komplexa bilder och ikoner.

För standardavbildningar fungerar fortfarande den äldre Markdown-syntaxen, men det nya tillägget rekommenderas eftersom det stöder mer kraftfulla funktioner, till exempel att ange ett lokaliseringsomfång som skiljer sig från det överordnade ämnet. Andra avancerade funktioner, till exempel att välja från det delade bildgalleriet i stället för att ange en lokal bild, kommer att vara tillgängliga i framtiden. Den nya syntaxen är följande:

:::image type="content" source="<folderPath>" alt-text="<alt text>":::

Om type="content" (standard) krävs source både alt-text och.

Komplexa bilder med långa beskrivningar

Du kan också använda det här tillägget för att lägga till en bild med en lång beskrivning som läses av skärmläsare men som inte återges visuellt på den publicerade sidan. Långa beskrivningar är ett tillgänglighetskrav för komplexa bilder, till exempel grafer. Syntaxen är följande:

:::image type="complex" source="<folderPath>" alt-text="<alt text>":::
   <long description here>
:::image-end:::

Om type="complex" , , är en lång beskrivning och sourcealt-text:::image-end::: taggen alla obligatoriska.

När ändringarna är i förhandsversion eller publiceras kan du kontrollera om den långa beskrivningen finns genom att högerklicka på bilden och välja Granska (när du använder Microsoft Edge webbläsare, även om andra webbläsare har liknande funktioner). Den här åtgärden tar dig till bildkällan i HTML-koden, under vilken du hittar en visuellt dold klass. Expandera listrutan för den här klassen så hittar du din långa beskrivning:

Automatiska kantlinjer

Tillägget :::image::: stöder också egenskapen , som automatiskt lägger till en grå kantlinje på border 1 bildpunkt runt bilden. Egenskapen är som standard för bilder och , så du får kantlinjen automatiskt om du inte uttryckligen lägger till bordertrue egenskapen med värdet contentcomplexfalse . Egenskapen border är som standard för falseicon bilder.

Egenskapen border är det rekommenderade sättet att lägga till en kantlinje. Skapa inte egna kantlinjer manuellt.

Ange loc-scope

Ibland skiljer sig lokaliseringsomfånget för en bild från artikeln eller modulen som innehåller den. Detta kan orsaka en dålig global upplevelse: till exempel om en skärmbild av en produkt av misstag lokaliseras till ett språk som produkten inte är tillgänglig på. För att förhindra detta kan du ange det valfria attributet i bilder av typer och , och krävs för skärmbilder som visar en produkt med ett annat lokaliseringsomfång än den artikel eller modul loc-scopecontent som innehåller complex det.

Ikoner

Bildtillägget stöder ikoner, som är dekorativa bilder och som inte ska ha alternativtext. Syntaxen för ikoner är:

:::image type="icon" source="<folderPath>":::

Om type="icon" , ska anges men inte ska vara sourcealt-text det.

Egenskapen border är som standard för false ikoner. Om den dekorativa bilden kräver standardbildens kantlinje lägger du uttryckligen border="true" till den i :::image::: taggen.

Markdown-filer som ingår

Om markdown-filer måste upprepas i flera artiklar kan du använda en inkluderad fil. Funktionen includes instruerar Docs att ersätta referensen med innehållet i den inbyggda filen vid byggtiden. Du kan använda inkluderar på följande sätt:

• Infogade: Återanvänd ett vanligt textfragment infogade med i en mening.
• Block – Återanvänd en hel Markdown-fil som ett block som bäddas in i en del av artikeln.

En infogade fil eller blockindelningsfil är en Markdown-fil (.md). De kan innehålla alla sorters giltiga Markdowns. Inkludera filer finns vanligtvis i en gemensam innehåller underkatalog, i roten på lagringsplatsen. När artikeln publiceras integreras den inkluderade filen sömlöst i den publicerade artikeln.

Inkluderar syntax

Blockera in include är på sin egen rad:

[!INCLUDE [<title>](<filepath>)]

Infogade infogade infogade infogade är inom en rad:

Text before [!INCLUDE [<title>](<filepath>)] and after.

Där <title> är namnet på filen och är den relativa <filepath> sökvägen till filen. INCLUDE måste vara versaler och det måste finnas ett blanksteg före <title> .

Här följer krav och överväganden för inkluderingsfiler:

• Använd blockinkluderingar för stora mängder innehåll – ett stycke eller två, en delad procedur eller ett delat avsnitt. Använd dem inte för något som är mindre än en mening.
• Interna återges inte i den GitHub renderade vyn av din artikel eftersom de förlitar sig på Docs-tillägg. De återges först efter publiceringen.
• Skriv all text i en in include-fil i fullständiga meningar eller fraser som inte är beroende av föregående eller följande text i artikeln som refererar till indelningen. Om du ignorerar den här vägledningen skapas en oöversatt sträng i artikeln.
• Bädda inte in in inkludera filer i andra inkludningsfiler.
• /Includes -mappar undantas från versionen. Bilder som lagras i /includes mappar och refereras till i inkluderade filer visas därför inte i publicerat innehåll. Lagra avbildningar /media i en mapp utanför /includes mappen.
• Precis som med vanliga artiklar bör du inte dela media mellan inkluderingsfiler. Använd en särskild fil med ett unikt namn för varje inkludering och artikel. Lagra mediefilen i mediemappen som associeras med inkluderingen.
• Använd inte en inkludering som det enda innehållet i en artikel. Inkluderingar är avsedda att komplettera övrigt innehåll i en artikel.

Indrag

I Markdown avgör blanksteg före det första tecknet i en rad linjens justering i förhållande till föregående rader. Indrag påverkar särskilt numrerade och punktlistor för att rendera flera kapslingsnivåer i ett hierarkiskt format eller konturformat.

Om du vill göra indrag för text som ska justeras med ett föregående stycke eller ett objekt i en numrerad eller punktlista, använder du blanksteg.

Följande två exempel visar hur indragna stycken återges baserat på deras relation till andra stycken.

1. This is a numbered list example (one space after the period before the letter T).
   This sentence is indented three spaces.
   This code block is indented three spaces.
   
- This is a bulleted list example (one space after the bullet before the letter T).
  This sentence is indented two spaces.
  > [!TIP]
  > This tip is indented two spaces.
  - This is a second-level bullet (indented two spaces, with one space after the bullet before the letter T).
    This sentence is indented four spaces.
    > This quote block is indented four spaces.

Exemplet ovan renderas som:

1. Det här är ett numrerat listexempel (ett blanksteg efter perioden före bokstaven T).

   Den här meningen är indragen i tre blanksteg.

   This code block is indented three spaces.
   

• Det här är ett exempel på en punktlista (ett blanksteg efter punkten före bokstaven T).

  Den här meningen är indragen i två blanksteg.

  Tips

  Det här tipset har indrag i två blanksteg.

  • Det här är en punkt på andra nivån (indrag i två blanksteg, med ett blanksteg efter punkten före bokstaven T).

    Den här meningen är indragen i fyra blanksteg.

    Det här citatblocket har indrag med fyra blanksteg.

Länkar

Information om syntax för länkar finns i Använda länkar i dokumentationen.

Listor (numrerad lista, punktlista, checklista)

Numrerad lista

Om du vill skapa en numrerad lista kan du använda alla 1:ar. Talen återges i stigande ordning som en sekventiell lista när de publiceras. För ökad källläsbarhet kan du öka listorna manuellt.

Använd inte bokstäver i listor, inklusive kapslade listor. De renderas inte korrekt när de publiceras till Docs. Kapslade listor med siffror renderas som gemener när de publiceras. Till exempel:

1. This is
1. a parent numbered list
   1. and this is
   1. a nested numbered list
1. (fin)

Detta renderas så här:

1. This is
2. a parent numbered list
   1. and this is
   2. a nested numbered list
3. (fin)

Punktlista

Om du vill skapa en punktlista använder - eller följs av ett blanksteg i början av varje * rad:

- This is
- a parent bulleted list
  - and this is
  - a nested bulleted list
- All done!

Detta renderas så här:

• This is
• a parent bulleted list
  • and this is
  • a nested bulleted list
• All done!

Oavsett vilken syntax du - använder, * eller , använder den konsekvent i en artikel.

Checklista

Checklistor är tillgängliga för användning i Docs via ett anpassat Markdown-tillägg:

> [!div class="checklist"]
> * List item 1
> * List item 2
> * List item 3

Det här exemplet renderas på Docs så här:

Använd checklistor i början eller slutet av en artikel för att sammanfatta ”Detta kommer du att lära dig” eller ”Detta har du lärt dig”. Lägg inte till checklistor slumpmässigt i artiklarna.

Nästa steg

Du kan använda ett anpassat tillägg för att lägga till en åtgärdsknapp för nästa steg på Docs-sidor.

Syntaxen ser ut så här:

> [!div class="nextstepaction"]
> [button text](link to topic)

Till exempel:

> [!div class="nextstepaction"]
> [Learn about adding code to articles](code-in-docs.md)

Detta renderas så här:

Du kan använda alla länkar som stöds i en nästa steg-åtgärd, inklusive en Markdown-länk till en annan webbsida. I de flesta fall är nästa åtgärdslänk en relativ länk till en annan fil i samma dokumentuppsättning.

Icke-lokaliserade strängar

Du kan använda det anpassade no-loc Markdown-tillägget för att identifiera strängar med innehåll som du vill att lokaliseringsprocessen ska ignorera.

Alla strängar som anropas är fallkänsliga. Det innebär att strängen måste matcha exakt för att ignoreras för lokalisering.

Om du vill markera en enskild sträng som icke-lokaliserbar använder du följande syntax:

:::no-loc text="String":::

I följande exempel ignoreras bara den enda Document instansen av under lokaliseringsprocessen:

# Heading 1 of the Document

Markdown content within the :::no-loc text="Document":::.  The are multiple instances of Document, document, and documents.

Lorem :::no-loc text="Find a \"Quotation\""::: Ipsum.

Du kan också använda metadata i YAML-rubriken för att markera alla instanser av en sträng i den aktuella Markdown-filen som icke-lokaliserbara:

author: cillroy
no-loc: [Global, Strings, to be, Ignored]

I följande exempel ignoreras ordet både i metadata- och title Markdown-rubriken Document under lokaliseringsprocessen.

I metadata description och Markdowns huvudinnehåll document lokaliseras ordet eftersom det inte börjar med versaler D .

---
title: Title of the Document
author: author-name
description: Description for the document
no-loc: [Title, Document]
---
# Heading 1 of the Document

Markdown content within the document.

Väljare

Väljare är gränssnittselement som gör att användaren kan växla mellan flera varianter av samma artikel. De används i vissa dokumentuppsättningar för att hantera skillnader i implementering mellan tekniker eller plattformar. Väljare är vanligtvis mest tillämpliga för vårt mobilplattformsinnehåll för utvecklare.

Eftersom samma markdown för väljare finns i varje artikelfil som använder väljaren rekommenderar vi att du placerar väljaren för din artikel i en inkluderad fil. Sedan kan du referera till inkluderad fil i alla dina artikelfiler som använder samma väljare.

Det finns två typer av väljare: en enskild väljare och en flerväljare.

En väljare

> [!div class="op_single_selector"]
> - [Universal Windows](../articles/notification-hubs-windows-store-dotnet-get-started/)
> - [Windows Phone](../articles/notification-hubs-windows-phone-get-started/)
> - [iOS](../articles/notification-hubs-ios-get-started/)
> - [Android](../articles/notification-hubs-android-get-started/)
> - [Kindle](../articles/notification-hubs-kindle-get-started/)
> - [Baidu](../articles/notification-hubs-baidu-get-started/)
> - [Xamarin.iOS](../articles/partner-xamarin-notification-hubs-ios-get-started/)
> - [Xamarin.Android](../articles/partner-xamarin-notification-hubs-android-get-started/)

... renderas så här:

Flera val

> [!div class="op_multi_selector" title1="Platform" title2="Backend"]
> - [(iOS | .NET)](./mobile-services-dotnet-backend-ios-get-started-push.md)
> - [(iOS | JavaScript)](./mobile-services-javascript-backend-ios-get-started-push.md)
> - [(Windows universal C# | .NET)](./mobile-services-dotnet-backend-windows-universal-dotnet-get-started-push.md)
> - [(Windows universal C# | Javascript)](./mobile-services-javascript-backend-windows-universal-dotnet-get-started-push.md)
> - [(Windows Phone | .NET)](./mobile-services-dotnet-backend-windows-phone-get-started-push.md)
> - [(Windows Phone | Javascript)](./mobile-services-javascript-backend-windows-phone-get-started-push.md)
> - [(Android | .NET)](./mobile-services-dotnet-backend-android-get-started-push.md)
> - [(Android | Javascript)](./mobile-services-javascript-backend-android-get-started-push.md)
> - [(Xamarin iOS | Javascript)](./partner-xamarin-mobile-services-ios-get-started-push.md)
> - [(Xamarin Android | Javascript)](./partner-xamarin-mobile-services-android-get-started-push.md)

... renderas så här:

Upphöjd och upphöjd

Du bör endast använda upphöjd eller upphöjd text när det behövs för teknisk noggrannhet, till exempel när du skriver om matematiska formler. Använd dem inte för icke-standardformat, till exempel fotnoter.

Använd HTML för både upp- och nedsänkt text:

Hello <sub>This is subscript!</sub>

Detta renderas så här:

Hello _{This is subscript!}

Goodbye <sup>This is superscript!</sup>

Detta renderas så här:

Goodbye ^{This is superscript!}

Tables

Det enklaste sättet att skapa en tabell i Markdown är att använda lodräta streck och linjer. Om du vill skapa en standardtabell med en rubrik anger du en streckad linje efter första raden:

|This is   |a simple   |table header|
|----------|-----------|------------|
|table     |data       |here        |
|it doesn't|actually   |have to line up nicely!|

Detta renderas så här:

Du kan justera kolumnerna med hjälp av kolon:

| Fun                  | With                 | Tables          |
| :------------------- | -------------------: |:---------------:|
| left-aligned column  | right-aligned column | centered column |
| $100                 | $100                 | $100            |
| $10                  | $10                  | $10             |
| $1                   | $1                   | $1              |

Renderas så här:

Radbrytningar i ord i valfri tabellcell

Långa ord i en Markdown-tabell kan göra att tabellen expanderar till höger navigering och blir oläslig. Du kan lösa det genom att låta Docs-rendering automatiskt infoga radbrytningar i ord när det behövs. Du behöver bara avsluta tabellen med den anpassade klassen [!div class="mx-tdBreakAll"].

Här följer ett Markdown-exempel på en tabell med tre rader som hanteras av ett div med klassnamnet mx-tdBreakAll.

> [!div class="mx-tdBreakAll"]
> |Name|Syntax|Mandatory for silent installation?|Description|
> |-------------|----------|---------|---------|
> |Quiet|/quiet|Yes|Runs the installer, displaying no UI and no prompts.|
> |NoRestart|/norestart|No|Suppresses any attempts to restart. By default, the UI will prompt before restart.|
> |Help|/help|No|Provides help and quick reference. Displays the correct use of the setup command, including a list of all options and behaviors.|

Den återges så här:

Radbrytningar inom ord i andra kolumntabellceller

Du kanske bara vill att radbrytningar ska infogas automatiskt i ord i den andra kolumnen i en tabell. Om du vill begränsa radbrytningarna till den andra kolumnen använder du klassen med hjälp mx-tdCol2BreakAll av div omslutningssyntaxen som visades tidigare.

Inkonsekvent kolumnbredd mellan tabeller

Du kanske märker att kolumnbredden för tabellerna i dina artiklar ser udda ut eller inkonsekvent. Detta beror på att längden på texten i cellerna avgör tabellens layout. Det finns tyvärr inget sätt att styra hur tabellerna renderas. Det här är en begränsning i Markdown. Även om det skulle se bättre ut att ha bredden på tabellkolumnerna konsekvent, skulle detta också ha några nackdelar:

• Genom att sammanfläta HTML-kod med Markdown blir ämnena mer komplicerade och avråder communityn från att bidra.
• En tabell som du ser bra ut för en viss skärmstorlek kan sluta se oläslig ut på olika skärmstorlekar eftersom den gör återgivningen responsiv.

Datamatristabeller

En datamatristabell har både en rubrik och en viktad första kolumn, vilket skapar en matris med en tom cell i det övre vänstra hörnet. Docs har anpassad Markdown för datamatristabeller:

|                  |Header 1 |Header 2|
|------------------|---------|--------|
|**First column A**|Cell 1A  |Cell 2A |
|**First column B**|Cell 1B  |Cell 2B |

Exemplet renderas som:

Varje post i den första kolumnen måste vara fetstilt ( ), annars är tabellerna inte tillgängliga för skärmläsare eller giltiga **bold** för Docs.

HTML-tabeller

HTML-tabeller rekommenderas inte för Docs. De är inte läsbara för människor i källan – vilket är en viktig princip i Markdown.