Markdown gebruiken

Artikelen op docs.microsoft.com worden geschreven in de toegankelijke opmaakcodetaal Markdown, die eenvoudig te lezen en eenvoudig te leren is. Daarom is het al snel een standaardopmaaktaal geworden.

Omdat Docs-inhoud wordt opgeslagen in GitHub, kan een hoofdverzameling van Markdown, GitHub Flavored Markdown (GFM), worden gebruikt. Deze biedt aanvullende functionaliteit voor algemene opmaakbehoeften. Daarnaast wordt met OPS (Open Publishing Services) DFM (DocFX Flavored Markdown) geïmplementeerd, dat zeer compatibel is met GitHub Flavored Markdown (GFM). Hiermee wordt aanvullende functionaliteit toegevoegd om voor Docs specifieke functies in te schakelen.

Belangrijk

Microsoft-medewerkers moeten de Gauntlet Authoring Services en gerelateerde VS Code-extensie gebruiken voor het schrijven van artikelen. Sjablonen van de Gauntlet Template Service zorgen ervoor dat de juiste Markdown-opmaak wordt gebruikt, inclusief GFM en DFM.

Basisbeginselen van Markdown

Koppen

Als u een kop wilt maken, gebruikt u een hash (#), als volgt:

    # This is heading 1
    ## This is heading 2
    ### This is heading 3
    #### This is heading 4

Vetgedrukte en cursieve tekst

Als u tekst als vet wilt opmaken, zet u de tekst tussen dubbele sterretjes:

    This text is **bold**.

Als u tekst als cursief wilt opmaken, zet u de tekst tussen enkele sterretjes:

    This text is *italic*.

Als u tekst als vet en cursief wilt opmaken, zet u de tekst tussen driedubbele sterretjes:

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

Lijsten

Ongeordende lijst

Als u een ongeordende lijst of een lijst met opsommingstekens wilt opmaken, kunt u sterretjes of streepjes gebruiken. Zo wordt de volgende Markdown:

- List item 1
- List item 2
- List item 3

weergegeven als:

  • Lijstitem 1
  • Lijstitem 2
  • Lijstitem 3

Als u een lijst in een andere lijst wilt nesten, laat u de lijstitems van de onderliggende lijst inspringen. Zo wordt de volgende Markdown:

- List item 1
  - List item A
  - List item B
- List item 2

weergegeven als:

  • Lijstitem 1
    • Lijstitem A
    • Lijstitem B
  • Lijstitem 2

Geordende lijst

Als u een geordende lijst/stapsgewijze lijst wilt opmaken, gebruikt u de bijbehorende nummers. Zo wordt de volgende Markdown:

1. First instruction
2. Second instruction
3. Third instruction

weergegeven als:

  1. Eerste instructie
  2. Tweede instructie
  3. Derde instructie

Als u een lijst in een andere lijst wilt nesten, laat u de lijstitems van de onderliggende lijst inspringen. Zo wordt de volgende Markdown:

1. First instruction  
    a. Sub-instruction  
    b. Sub-instruction  

2. Second instruction  

weergegeven als:

  1. Eerste instructie
    a. Subinstructie
    b. Subinstructie

  2. Tweede instructie

Tabellen

Tabellen maken geen onderdeel uit van de Markdown-kernspecificatie, maar ze worden ondersteund door GFM. Tabellen kunt u maken met het sluisteken (|) en afbreekstreepjes (-). Met afbreekstreepjes maakt u de kolomkoppen. Met het sluisteken scheidt u de kolommen van elkaar. Voeg voor de tabel een lege regel in, zodat de tabel correct wordt weergegeven.

Zo wordt de volgende Markdown:

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

weergegeven als:

Pret met Tabellen
links uitgelijnde kolom rechts uitgelijnde kolom gecentreerde kolom
USD 100 USD 100 USD 100
USD 10 USD 10 USD 10
USD 1 USD 1 USD 1

Ga voor meer informatie over het maken van tabellen naar:

De Markdown-syntaxis voor een inlinekoppeling bestaat uit het gedeelte [link text], het gedeelte dat wordt gekoppeld, gevolgd door het gedeelte (file-name.md), de URL of de bestandsnaam waarnaar wordt gekoppeld:

[link text](file-name.md)

Ga voor meer informatie over koppelen naar:

  • De Markdown-syntaxishandleiding voor informatie over basisondersteuning voor koppelen van Markdown.
  • De sectie Koppelingen van deze handleiding voor meer informatie over aanvullende syntaxis voor koppelen, zoals ondersteund door DFM.

Codefragmenten

Markdown ondersteunt het plaatsen van codefragmenten inline in een zin, maar ook als een afzonderlijk, 'omheind' blok tussen zinnen. Zie voor meer informatie:

Met omheinde codeblokken kunt u eenvoudig syntaxis markeren voor uw codefragmenten. De algemene opmaak voor omheinde codeblokken is:

```alias
...
your code goes in here
...
```

Met de alias na de eerste drie apostroffen (`) wordt aangegeven welke syntaxismarkering moet worden gebruikt. Hieronder vindt u een lijst met veelgebruikte programmeertalen op het Azure-platform en het bijbehorende label:

Taal of CLI Taalalias
Azure CLI azurecli
AzCopy azcopy
C++ cpp
C# csharp
F# fsharp
Java java
JavaScript javascript
JSON json
Node.js nodejs
Objective-C objc
PHP php
PowerShell powershell
Python python
Ruby ruby
SQL / T-SQL sql
Swift swift
VB vb
XAML xaml
XML xml

Zie Taalnamen en aliassen voor een volledige lijst met ondersteunde talen.

Voorbeeld: C#

Markdown

```csharp
// Hello1.cs
public class Hello1
{
    public static void Main()
    {
        System.Console.WriteLine("Hello, World!");
    }
}
```

Weergave

// Hello1.cs
public class Hello1
{
    public static void Main()
    {
        System.Console.WriteLine("Hello, World!");
    }
}

Voorbeeld: SQL

Markdown

```sql
CREATE TABLE T1 (
  c1 int PRIMARY KEY,
  c2 varchar(50) SPARSE NULL
);
```

Weergave

CREATE TABLE T1 (
  c1 int PRIMARY KEY,
  c2 varchar(50) SPARSE NULL
);

Aangepaste OPS-extensies voor Markdown

Notitie

Met OPS (Open Publishing Services) wordt DFM (DocFX Flavored Markdown) geïmplementeerd, dat zeer compatibel is met GFM (GitHub Flavored Markdown). Met DFM wordt extra functionaliteit toegevoegd via Markup-extensies. Om die reden zijn voor naslagdoeleinden bepaalde artikelen uit de OPS-ontwerphandleiding opgenomen in deze handleiding. (Zie bijvoorbeeld Extensies voor DFM en Markdown en Codefragmenten in de inhoudsopgave.) Microsoft-medewerkers kunnen ook verwijzen naar de sectie Authoring van de volledige OPS-handleiding voor meer informatie. De volledige handleiding is in het Engels beschikbaar onder het knooppunt "Open Publishing Services", onder "Writing/Publishing Resources".

GFM wordt gebruikt voor de opmaak van docs-artikelen, zoals alinea’s, koppelingen, lijsten en koppen. Voor rijkere opmaak kunnen in artikelen DFM-functies worden gebruikt, zoals:

  • Notitieblokken
  • Omvat
  • Selectors
  • Ingebedde video's
  • Codefragmenten/voorbeelden

Raadpleeg Extensies voor DFM en Markdown en Codefragmenten in de inhoudsopgave voor de volledige lijst.

Notitieblokken

U kunt kiezen uit vier verschillende notitieblokken om de aandacht op specifieke inhoud te vestigen:

  • OPMERKING
  • WAARSCHUWING
  • TIP
  • BELANGRIJK

Notitieblokken dienen met beleid te worden gebruikt, omdat ze als storend kunnen worden ervaren. Hoewel notitieblokken ondersteuning bieden voor codeblokken, afbeeldingen, lijsten en koppelingen, wordt het aanbevolen ze simpel te houden.

Omvat

Als u herbruikbare tekst- of afbeeldingsbestanden hebt die moeten worden ingesloten in artikelbestanden, kunt u een verwijzing naar het in te sluiten bestand gebruiken via de DFM-functie voor het insluiten van bestanden. Met deze functie wordt aan OPS de opdracht gegeven het betreffende bestand tijdens het opbouwen in uw artikelbestand in te sluiten, zodat dit onderdeel wordt van het gepubliceerde artikel. Er zijn drie soorten insluitingen beschikbaar waarmee u inhoud opnieuw kunt gebruiken:

  • Inline: een gewoon stuk tekst inline hergebruiken in een andere zin.
  • Blok: een volledig Markdown-bestand als blok hergebruiken, genest in een sectie van een artikel.
  • Afbeelding: op deze manier worden afbeeldingen standaard ingesloten in Docs. Zie Art voor meer informatie.

Een inline- of blokinsluiting is niets meer of minder dan een eenvoudig Markdown-bestand (.md). Deze kunnen elke geldige Markdown bevatten. Alle ingesloten Markdown-bestanden moeten in een algemene /includes-submap worden geplaatst in de hoofdmap van de opslagplaats. Als het artikel wordt gepubliceerd, wordt het ingesloten bestand vervolgens naadloos geïntegreerd.

Dit zijn de vereisten en overwegingen voor insluitingen:

  • Gebruik insluitingen wanneer u dezelfde tekst in meerdere artikelen wilt gebruiken.
  • Gebruik blokinsluitingen voor aanzienlijke hoeveelheden inhoud: enkele alinea’s, een gedeelde procedure of een gedeelde sectie. Gebruik deze niet voor content die minder lang is dan een zin.
  • Insluitingen worden niet weergegeven in het GitHub-weergaveoverzicht van uw artikelen, omdat ze afhankelijk zijn van DFM-extensies. Ze worden pas weergegeven na publicatie.
  • Zorg ervoor dat de tekst in een insluiting uit volledige zinnen bestaat die niet afhankelijk zijn van voorafgaande of volgende tekst in het artikel waarin naar de insluiting wordt verwezen. Als u deze richtlijn negeert, ontstaat niet te vertalen tekst in het artikel waardoor de gelokaliseerde ervaring wordt onderbroken.
  • Voeg geen insluitingen in andere insluitingen in. Dit wordt niet ondersteund.
  • Plaats mediabestanden in een mediamap die specifiek is voor de submap met insluitingen, bijvoorbeeld de map <repo>/includes/media. In de hoofdmap van de mediamap mogen zich geen afbeeldingen bevinden. Als de insluiting geen afbeeldingen bevat, hoeft er geen bijbehorende mediamap te worden gemaakt.
  • Net als bij gewone artikelen dient u geen media te delen tussen insluitingsbestanden. Gebruik een afzonderlijk bestand met een unieke naam voor elke insluiting en elk artikel. Sla het mediabestand op in de mediamap die is gekoppeld aan de insluiting.
  • Zorg ervoor dat een artikel meer inhoud bevat dan alleen een insluiting. Insluitingen dienen als aanvulling op de inhoud in de rest van het artikel.

Selectors

Gebruik selectors in technische artikelen als u van een artikel meerdere versies maakt voor implementatie in verschillende technologieën of platformen. Dit is doorgaans het meest van toepassing voor onze inhoud voor mobiele platformen voor ontwikkelaars. Er zijn momenteel twee verschillende soorten selectors in DFM, een enkelvoudige selector en een meervoudige selector.

Omdat dezelfde selector Markdown in elk onderwerp in de selectie wordt geplaatst, wordt aanbevolen de selector voor uw onderwerp op te nemen in een insluiting. Deze kan vervolgens naar deze insluiting verwijzen in alle onderwerpen waarin dezelfde selector wordt gebruikt.

Ingebedde video's

U kunt DFM-extensies gebruiken om video's in een artikel in te sluiten. Zie het artikel Extensies voor DFM en Markdown in deze handleiding voor informatie over de syntaxis voor het insluiten van materiaal. Zie het artikel Video's in uw inhoud insluiten voor extra richtlijnen en insluitingsmogelijkheden.

Codefragmenten

DFM ondersteunt geavanceerde insluiting van code in een artikel, via de extensie voor codefragmenten. Dit biedt een geavanceerde weergave die gebruikmaakt van GFM-functies, zoals keuze van programmeertaal en syntaxiskleuren, plus leuke functies als:

  • Insluiting van gecentraliseerde codevoorbeelden/-fragmenten uit een externe opslagplaats.
  • Gebruikersinterface met tabbladen voor weergave van meerdere versies van codevoorbeelden in verschillende talen.

Tabelterugloop

Soms is een Markdown-tabel te breed en loopt deze door in de rechternavigatiebalk, waardoor de tabel onleesbaar wordt. Dit kan eenvoudig worden opgelost door de DFM-sectie-uitbreiding div te gebruiken met de klasse mx-tdBreakAll. Hiermee kunnen door OPS indien nodig regelafbrekingen worden ingevoegd. Zie voor meer informatie het artikel Extensies voor DFM en Markdown in deze handleiding.

Gotcha's en probleemoplossing

Alternatieve tekst

Alternatieve tekst met onderstrepingstekens wordt niet goed weergegeven. In plaats van bijvoorbeeld dit te gebruiken:

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

Typt u voor de onderstrepingstekens een escape-teken, zoals hier:

![ADextension\_2FA\_Configure\_Step4] (./media/bogusfilename/ADextension_2FA_Configure_Step4.PNG)

Apostroffen en aanhalingstekens

Als u tekst vanuit Word in een Markdown editor kopieert, bevat deze mogelijk gekrulde apostroffen of aanhalingstekens. Deze moeten worden gecodeerd of gewijzigd in rechte apostroffen of aanhalingstekens. Anders ziet de tekst er misschien zo uit wanneer u het bestand gaat publiceren: It’s

Hieronder vindt u de codering voor de gekrulde versies van deze leestekens:

  • Linker dubbel aanhalingsteken (openen): &#8220;
  • Rechter dubbel aanhalingsteken (sluiten): &#8221;
  • Rechter enkel aanhalingsteken of apostrof (sluiten): &#8217;
  • Linker enkel aanhalingsteken (openen) (wordt zelden gebruikt): &#8216;

Punthaken

Als u in lopende tekst (geen code) punthaken gebruikt, bijvoorbeeld om een tijdelijke aanduiding aan te geven, moet u de punthaken handmatig coderen. Anders zal Markdown deze aanzien voor HTML-code.

Voorbeeld: codeer <script name> als &lt;script name&gt;

Zie ook

Markdown-resources