Dela via

Metodtips för Markdown

Den här artikeln innehåller specifika riktlinjer för hur du använder Markdown i vår dokumentation. Det är inte en självstudiekurs för Markdown. Om du behöver en guide för Markdown, se detta Markdown-fuskblad.

Bygg-pipelinen som bygger vår dokumentation använder markdig för att bearbeta Markdown-dokumenten. Markdig parsar dokumenten baserat på reglerna i den senaste CommonMark-specifikationen . OPS följer CommonMark-specifikationen och lägger till vissa tillägg för plattformsspecifika funktioner, till exempel tabeller och aviseringar.

CommonMark-specifikationen är striktare när det gäller att bygga vissa Markdown-element. Var uppmärksam på informationen i det här dokumentet.

Vi använder markdownlint-tillägget i VS Code för att framtvinga våra formateringsregler. Det här tillägget installeras som en del av Learn Authoring Pack.

Tomma linjer, blanksteg och flikar

Tomma linjer signalerar också slutet på ett block i Markdown.

  • Placera ett blanksteg mellan Markdown-block av olika typer. till exempel mellan ett stycke och en lista eller rubrik.
  • Använd inte mer än en tom rad. Flera tomma rader återges som en enda tom rad i HTML, och därför är de extra tomma raderna onödiga.
  • Placera inte flera på varandra följande tomma rader i ett kodblock, eftersom de bryter kodblocket.

Avståndet är betydande i Markdown.

  • Ta bort extra blanksteg i slutet av raderna. Avslutande blanksteg kan ändra hur Markdown renderas.
  • Använd alltid blanksteg i stället för flikar (hårda flikar).

Titlar och rubriker

Använd endast ATX-rubriker (# formatmall, i motsats till = eller - formatrubriker).

  • Använd meningsfall – endast egennamn och den första bokstaven i en titel eller rubrik ska vara versal
  • Inkludera ett enda blanksteg mellan # och den första bokstaven i rubriken
  • Omge rubriker med en enda tom rad
  • Använd inte mer än en H1 per dokument
    • Det bör vara den första rubriken
    • Den bör matcha rubriken på artikeln
  • Öka rubriknivåer med en – hoppa inte över nivåer
  • Begränsa djup till H3 eller H4
  • Undvik att använda fet eller annan markering i rubriker

Begränsa radlängden till 100 tecken

För konceptuella artiklar och cmdletreferenser begränsar du raderna till 100 tecken. För about_ artiklar begränsar du radlängden till 79 tecken. Om du begränsar linjelängden förbättras läsbarheten för git diff och historik. Det gör det också lättare för andra författare att göra bidrag.

Använd Reflow Markdown-tillägget i VS Code för att omforma stycken så att de passar den föreskrivna radlängden.

Vissa innehållstyper kan inte enkelt formateras om. Koden inuti kodblock kan till exempel också vara svår att flöda om, beroende på innehållet och kodspråket. Du kan inte ändra layouten på en tabell. I dessa fall bör du använda din bästa bedömning för att hålla innehållet så nära gränsen på 100 tecken som möjligt.

Betoning

Markdown har stöd för fetstil och kursiv stil. Med Markdown kan du använda antingen * eller _ markera betoningen. Men för att vara konsekvent och visa avsikt:

  • Använd ** för fetstil
  • Använd _ för kursiv stil

Genom att följa det här mönstret blir det lättare för andra att förstå avsikten med markeringen när det finns en blandning av fetstil och kursiv stil i ett dokument.

Listor

Om listan har flera meningar eller stycken kan du överväga att använda en undernivårubrik i stället för en lista.

Omge listor med en enda tom rad.

Osorterade listor

  • Avsluta inte listobjekt med en punkt om de inte innehåller flera meningar.
  • Använd bindestreckstecknet (-) för punktlistor för listobjekt för att undvika förvirring med betoningsmarkering som använder asterisken (*).
  • Om du vill inkludera ett stycke eller andra element under ett punktobjekt infogar du en radbrytning och justerar indraget med det första tecknet efter punkten.

Till exempel:

This is a list that contains child elements under a bullet item.

- First bullet item

  Sentence explaining the first bullet.

  - Child bullet item

    Sentence explaining the child bullet.

- Second bullet item
- Third bullet item

Det här är en lista som innehåller underordnade element under ett punktobjekt.

  • Första punktobjektet

    Mening som förklarar den första punkten.

    • Underordnat punktobjekt

      Mening som förklarar den underordnade punkten.

  • Andra punktobjektet

  • Tredje punkt

Ordnade listor

  • Alla objekt i en numrerad lista bör använda talet 1. i stället för att öka varje objekt.
    • Markdown-rendering ökar värdet automatiskt.
    • Detta gör det enklare att ordna om objekt och standardiserar indragningen för underordnat innehåll.
  • Om du vill inkludera ett stycke eller andra element under ett numrerat objekt justerar du indraget med det första tecknet efter objektnumret.

Till exempel:

1. For the first element, insert a single space after the `1`. Long sentences should be wrapped to
   the next line and must line up with the first character after the numbered list marker.

   To include a second element, insert a line break after the first and align indentations. The
   indentation of the second element must line up with the first character after the numbered list
   marker.

1. The next numbered item starts here.

Den resulterande Markdown återges på följande sätt:

  1. För det första elementet infogar du ett enda blanksteg efter 1. Långa meningar ska omslutas till nästa rad och måste radas upp med det första tecknet efter den numrerade listmarkören.

    Om du vill inkludera ett andra element infogar du en radbrytning efter den första och justerar indrag. Indraget för det andra elementet måste stämma överens med den första bokstaven efter den numrerade listmarkören.

  2. Nästa numrerade objekt börjar här.

Avbildningar

Syntaxen för att inkludera en bild är:

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

Example:
![Introduction](./media/overview/Introduction.png)

Var alt text är en kort beskrivning av bilden och <folderPath> är en relativ sökväg till bilden.

  • Alternativ text krävs för att stödja skärmläsare för synskadade.
  • Bilder ska lagras i en media/<article-name> mapp i mappen som innehåller artikeln.
    • Skapa en mapp som matchar filnamnet för din artikel under media mappen . Kopiera bilderna för den artikeln till den nya mappen.
  • Dela inte bilder mellan artiklar.
    • Om en bild används av flera artiklar måste varje mapp ha en kopia av bilden.
    • Detta förhindrar att en ändring av en bild i en artikel påverkar en annan artikel.

Följande bildfiltyper stöds: *.png, *.gif, *.jpeg, *.jpg, *.svg

Markdown-tillägg – aviseringsrutor

Learn Authoring Pack innehåller verktyg som stöder funktioner som är unika för vårt publiceringssystem. Aviseringar är ett Markdown-tillägg för att skapa blockkvoter som återges med färger och ikoner som belyser innehållets betydelse. 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.

Aviseringarna ser ut så här i Microsoft Learn:

Anteckningsblock

Anmärkning

Information som användaren bör lägga märke till även om hen skummar.

Tipsblock

Tips/Råd

Valfri information som hjälper en användare att bli mer framgångsrik.

Viktigt block

Viktigt!

Viktig information som krävs för att användaren ska lyckas.

Varningsblock

Försiktighet

Negativa potentiella konsekvenser av en åtgärd.

Varningsblock

Varning

Farliga vissa konsekvenser av en åtgärd.

Markdown-tillägg – tabeller

En tabell är ett arrangemang av data med rader och kolumner som består av:

  • En enskild rubrikrad
  • En avgränsarrad som skiljer huvudrubriken från datan
  • Noll eller fler datarader

Varje rad består av celler som innehåller godtycklig text avgränsad med rör (|). Ett ledande och avslutande rör rekommenderas också för tydlighetens skull. Blanksteg mellan rör och cellinnehåll trimmas. Blocknivåelement kan inte infogas i en tabell. Allt innehåll i en rad måste finnas på en enda rad.

Avgränsarraden består av celler vars enda innehåll är bindestreck (-), och eventuellt ett inledande eller avslutande kolon (:), eller båda, för att indikera vänster, höger eller mittjustering.

För små tabeller bör du överväga att använda en lista i stället. Listor är:

  • Enklare att underhålla och läsa
  • Kan omjusteras för att passa inom gränsen på 100 tecken
  • Mer tillgänglig för användare som använder skärmläsare för visuell hjälp

Mer information finns i avsnittet Tabeller i Markdown-referens för Microsoft Learn.

  • Hyperlänkar måste använda Markdown-syntax .[friendlyname](url-or-path)

  • Publiceringssystemet stöder tre typer av länkar:

    • URL-länkar
    • Fillänkar
    • Korsreferenslänkar

  • Alla URL:er till externa webbplatser bör använda HTTPS om det inte är giltigt för målwebbplatsen.

  • Länkar måste ha ett eget namn, vanligtvis rubriken på den länkade artikeln

  • Undvik att använda backticks, fetstil eller andra markeringar inom hakparenteserna i en hyperlänk.

  • Oformaterade URL:er kan användas när du dokumenterar en specifik URI men måste omges av bakåtvända apostrofer. Till exempel:

    By default, if you don't specify this parameter, the DMTF standard resource URI
`http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/` is used and the class name is appended to it.

  • Använd länkreferenser där det är tillåtet. Länkreferenser i stycken gör styckena mer läsbara.

    Länkreferenser delar upp en Markdown-länk i två delar:

    • länkreferens - [friendlyname][id]
    • länkdefinitionen – [id]: url-or-path
  • URL-länkar till andra artiklar på learn.microsoft.com måste använda platsrelativa sökvägar. Det enklaste sättet att skapa en platsrelativ länk är att kopiera URL:en från webbläsaren och sedan ta bort https://learn.microsoft.com/en-us från det värde som du klistrar in i markdown.
  • Inkludera inte nationella inställningar i URL:er för Microsoft-egenskaper (ta bort /en-us från URL) eller Wikipedia-länkar.
  • Ta bort eventuella onödiga frågeparametrar från URL:en. Exempel som bör tas bort:
    • ?view=powershell-5.1 – används för att länka till en specifik version av PowerShell
    • ?redirectedfrom=MSDN – lades till i URL:en när du omdirigeras från en gammal artikel till dess nya plats
  • Om du behöver länka till en viss version av ett dokument måste du lägga till parametern &preserve-view=true i frågesträngen. Till exempel: ?view=powershell-5.1&preserve-view=true
  • På Microsoft-webbplatser innehåller URL-länkar inte filnamnstillägg (till exempel nej .md)
  • En fillänk används för att länka från en referensartikel till en annan, eller från en konceptuell artikel till en annan i samma dokumentuppsättning.
    • Om du behöver länka från en konceptuell artikel till en referensartikel måste du använda en URL-länk.
    • Om du behöver länka till en artikel i en annan dokumentuppsättning eller mellan lagringsplatser måste du använda en URL-länk.
  • Använd relativa filsökvägar (till exempel: ../folder/file.md)
  • Alla filsökvägar använder snedstreckstecken (/)
  • Inkludera filnamnstillägget (till exempel .md)

Korsreferenslänkar är en särskild funktion som stöds av publiceringssystemet. Du kan använda korsreferenslänkar i konceptuella artiklar för att länka till .NET API eller cmdlet-referens.

  • Länkar till .NET API-referens finns i Använda länkar i dokumentationen i den centrala deltagarguiden.

  • Länkar till cmdlet-referensen har följande format: xref:<module-name>.<cmdlet-name>. Om du till exempel vill länka till cmdleten Get-Content i modulen Microsoft.PowerShell.Management .

    [Get-Content](xref:Microsoft.PowerShell.Management.Get-Content)

Djuplänkning

Djuplänkning tillåts på både URL- och fillänkar.

  • Fästpunktstexten måste vara gemen
  • Lägg till fästpunkten i slutet av sökvägen. Till exempel:
    • [about_Splatting](about_Splatting.md#splatting-with-arrays)
    • [custom key bindings](https://code.visualstudio.com/docs/getstarted/keybindings#_custom-keybindings-for-refactorings)

Mer information finns i Använda länkar i dokumentationen.

Kodintervall

Kodintervall används för infogade kodfragment i ett stycke. Använd enkla backticks för att markera ett kodfragment. Till exempel:

PowerShell cmdlet names use the `Verb-Noun` naming convention.

Det här exemplet återges som:

PowerShell-cmdlet-namn använder namngivningskonventionen Verb-Noun .

Kodblock

Kodblock används för kommandoexempel, kodexempel med flera rader, frågespråk och utdata. Det finns två sätt att ange att ett textavsnitt i en artikelfil är ett kodblock: genom att omsluta det med trippla backticks (```) eller genom att göra ett indrag.

Använd aldrig indrag eftersom det är för lätt att få fel och det kan vara svårt för en annan författare att förstå din avsikt när de behöver redigera din artikel.

Inhägnade kodblock kan innehålla en valfri tagg som anger språksyntaxen i blocket. Publiceringsplattformen stöder en lista med språktaggar. Språktaggen används för att ange syntaxmarkering när artikeln återges på webbsidan. Språktaggen är inte skiftlägeskänslig, men du bör använda gemener förutom några specialfall.

  • Kodstängsel utan taggar kan användas för syntaxblock eller andra typer av innehåll där syntaxmarkering inte krävs.
  • När du visar utdata från ett kommando använder du ett taggat kodstängsel med språktaggen Output. Den renderade rutan är märkt som Utdata och har ingen syntaxmarkering.
  • Om utdata finns på ett visst språk som stöds använder du lämplig språktagg. Många kommandon matar till exempel ut JSON, så använd taggen json .
  • Om du använder en språktagg som inte stöds återges kodblocket utan syntaxmarkering. Språktaggen blir etiketten för den renderade kodrutan på webbsidan. Versalera taggen så att etiketten är versal på webbsidan.

Nästa steg

PowerShell-stilguide

  • Last updated on