Extensies voor DFM en Markdown

Markdown is een lichtgewicht opmaakcodetaal met een syntaxis voor platte tekst. U kunt deze converteren naar HTML en vele andere indelingen met een hulpprogramma met dezelfde naam. Markdown vormt de basis van de conceptuele ontwerptaal voor onze documentatie. Het maken van nieuwe artikelen is net zo gemakkelijk als het schrijven van een eenvoudig tekstbestand met uw favoriete teksteditor.

Markdown ondersteund door OPS

DocFX, waarvan OPS gebruikmaakt, ondersteunt DocFX Flavored Markdown (DFM). DFM is in hoge mate compatibel met GitHub Flavored Markdown (GFM) en biedt nog enkele andere functies, waaronder het insluiten van kruisverwijzingen en bestanden. Er zijn verschillen tussen DFM en GFM (http://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html#differences-between-dfm-and-gfm) die van invloed kunnen zijn op de preview van inhoud in GitHub, Visual Studio Team Services of uw eigen editor.

Markdown - Zelfstudies

Dit zijn twee zeer handige zelfstudies voor Markdown en GitHub Flavored Markdown:

Een editor kiezen

U kunt voor het bewerken van Markdown elke Markdown-editor gebruiken. Enkele suggesties: MarkdownPad, Visual Studio Code, Markdown Mode.

De meeste daarvan bieden live preview zodat u tijdens het schrijven van het artikel een eenvoudig voorbeeld kunt zien. De preview wijkt af van de uiteindelijke rendering voor extensies en plekken waar DFM verschilt van GFM.

Markdown-extensies ondersteund door Open Publishing

In de volgende gedeelten worden ondersteunde extensies in Open Publishing beschreven.

Insluiten van bestanden

U kunt andere bestanden insluiten in het huidige bestand. Ingesloten bestanden moeten zich bevinden in een map met de naam /includes binnen uw docset. Zorg ervoor dat u de map insluit als een resource in het docfx.json-bestand. De ingesloten bestanden moeten ook worden geconfigureerd in DFM-syntaxis.

Notitie

Een YAML-header wordt niet ondersteund wanneer het bestand is ingesloten.

Er zijn drie type insluiting voor bestanden: inline, blok en afbeelding.

Inline-insluiting

Inline-insluiting van bestanden maakt gebruikt van de volgende syntaxis, waarbij <title> staat voor de titel en <filepath> voor het pad van het ingesloten bestand. Het bestandspad moet een relatief bestandspad zijn. Absolute paden worden niet ondersteund. Het deel <filepath> kan worden verpakt door ' of ". Merk op dat in het geval van inline-insluiting van bestanden het ingesloten bestand wordt beschouwd als een bestand dat alleen inline-tags bevat. ###header binnen het bestand wordt bijvoorbeeld niet omgezet omdat <h3> een bloktag is. Maar [a](b) wordt omgezet naar <a href='b'>a</a> omdat <a> een inline-tag is.

...Other inline content... [!include[<title>](<filepath>)]

Blokinsluiting

Blokinsluitingen van bestanden moeten plaatsvinden binnen één enkele regel zonder voorvoegseltekens vóór de openings-[. De inhoud van het ingesloten bestand wordt omgezet met behulp van de DFM-syntaxis.

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

Afbeeldingen

De syntaxis voor het insluiten van een afbeelding is ![[alt text]]({folderPath})

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

Geef beschrijvende alt-tekst op voor een afbeelding. We ondersteunen zelfs GIF-animaties!

Een voorbeeld, dat dezelfde syntaxis gebruikt: ![Responsive design](../images/responsivedesign.gif)

Responsief ontwerp

Opmerking, waarschuwing, tip, Belangrijk

Gebruik een specifieke syntaxis binnen een ingesprongen blok om aan te geven dat de inhoud die volgt van het type opmerking is.

> [!NOTE]
> This is a note.

> [!WARNING]
> This is a warning.

> [!TIP]
> This is a tip.

> [!IMPORTANT]
> This is important.

En deze wordt als volgt weergegeven:

Notitie

Dit is een opmerking.

Waarschuwing

Dit is een waarschuwing.

Tip

Dit is een tip.

Belangrijk

Dit is belangrijk.

Gecontroleerde lijsten

Notitie

Deze functie is alleen beschikbaar op docs.microsoft.com.

Er is een aangepaste stijl beschikbaar voor lijsten met opsommingstekens. U kunt lijsten met vinkjes renderen. Hier volgt een voorbeeld:

  • Aanmelden bij Azure
  • Een resourcegroep maken
  • De configuratie voorbereiden
  • Een virtuele machine maken
  • De firewall configureren
  • Een snapshot van de virtuele machine maken
  • Beheertaken uitvoeren

Voor het renderen van de voorgaande lijst schrijft u de volgende Markdown:

> [!div class="checklist"]
> * Sign in to Azure
> * Create a resource group
> * Prepare the configuration
> * Create a virtual machine
> * Configure the firewall
> * Snapshot the virtual machine
> * Run management tasks

Deze Markdown-extensie kan overal worden gebruikt. We raden u toch aan dit toe te spitsen op de scenario’s "Wat gaat u leren" (aan het begin van een artikel) of "Wat hebt u geleerd" (aan het eind van een artikel), waar u op heldere wijze de hoofdpunten in een artikel of handleiding wilt laten zien. Laat het toevoegen van willekeurige of ad hoc lijsten met opsommingstekens in uw artikelen achterwege.

Actie volgende stap

Notitie

Deze functie is alleen beschikbaar op docs.microsoft.com.

Een extensie biedt een consistente manier om een actie voor een volgende stap aan het einde van uw artikelen weer te geven. Hier volgt een voorbeeld:

Voor het renderen van de voorgaande actie, schrijft u de volgende Markdown:

> [!div class="nextstepaction"]
> [Create and manage VM disks](https://docs.microsoft.com/en-us/azure/virtual-machines/linux/tutorial-manage-disks)

Gebruik deze Markdown-extensie alleen aan het eind van een artikel, met de uitdrukkelijke bedoeling lezers door te sturen naar een volgend artikel dat ze moeten lezen nadat ze het huidige artikel hebben bekeken. Gebruik deze extensie op geen enkele andere manier.

Het is heel gebruikelijk om koppelingen naar andere inhoud in OPS toe te voegen. OPS de koppelingen in de volgende situaties omzetten en valideren.

Verwijzen naar inhoud binnen een docset

In OPS worden docsets door het buildysteem behandeld als de grens voor referentievalidatie. Voor elke koppelingsverwijzing binnen een docset kan het buildsysteem die koppeling omzetten en valideren in de gewone GFM-syntaxis. U kunt gebruikmaken van een relatief pad, zoals in het volgende voorbeeld, om een koppelingsverwijzing binnen dezelfde docset te maken.

[My link text](../active-directory/active-directory-article-name.md)

Verwijzen naar inhoud in externe docsets

OPS ondersteunt momenteel niet het omzetten en valideren van logica voor verwijzingen tussen docsets. Als u wilt verwijzen naar een bestand in een andere docset, moet u een verwijzing tussen docsets toevoegen met behulp van een verwijzing via een absoluut pad. Bijvoorbeeld:

[My link text](/active-directory/active-directory-article-name)

De tekst "/ active-directory/active-directory-artikel-name" maakt deel uit van de URL zonder het domein. Deze maakt een koppeling naar https://{Domain}/active-directory/active-directory-article-name.

U kunt een ankerkoppeling gebruiken om naar een bepaald deel van een artikel te gaan.

Markdown-koppen H2 (##) tot en met H6 (######) zijn automatische ankers. De anker-id is de volledige tekst van de kop, in kleine letters, zonder interpunctie en met verbindingsstreepjes in plaats van spaties. De id voor de kop ## 2. Getting started with Markdown bijvoorbeeld is 2-getting-started-with-markdown.

Om een koppeling naar deze kop in het huidige bestand te maken, gebruikt u:

[getting started](#2-getting-started-with-markdown)

Het wordt als volgt gerenderd:

aan de slag

Om een koppeling naar een kop vanuit een ander artikel te maken, gebruikt u de relatieve koppeling naar het huidige artikel, plus # gevolgd door de anker-id, zoals:

[getting started with GFM](../gfm.md##2-getting-started-with-markdown)

Expliciete ankers die gebruikmaken van <a> zijn niet vereist, maar zijn wel nodig in hub- en landingspagina’s:

## <a id="AnchorText"> </a>Header text of ## <a name="AnchorText"> </a>Header text

En het volgende voor de koppeling er naartoe:

  • Go to [text](#AnchorText) om naar het gedeelte op dezelfde pagina te gaan.
  • Go to [text](FileName.md#AnchorText) om naar het gedeelte op een andere pagina te gaan.

Als u een koppeling naar een API-onderwerp wilt maken op basis van uid, gebruikt u een xref-koppeling:

<xref:uid>

Zoals: <xref:System.String> of <xref:microsoft.azure.keyvault.keyidentifier.iskeyidentifier>

Als u naar een overzichtspagina voor overbelasting wilt gaan, voegt u 2%a toe:

<xref:System.String.Format2%A>

Als u een koppeling naar een specifieke overbelasting wilt maken, neemt u de parameters op in de uid:

<xref:System.String.Format(System.String,System.Object)>

Als u de volledige API-naam in de koppeling wilt weergeven, zoals System.String in plaats van String, voegt u ?displayProperty=fullName toe:

<xref:System.String?displayProperty=fullName>

API-doeldocs moeten zich in dezelfde repo of in een verwijzingsmap in de repo bevinden. Zie DocFx: Links and Cross References voor meer informatie.

Sectiedefinitie

U moet mogelijk een sectie definiëren. Deze syntaxis wordt voornamelijk gebruikt voor codetabellen. Zie het volgende voorbeeld:

> [!div class="tabbedCodeSnippets" data-resources="OutlookServices.Calendar"]
> ```cs
> <cs code text>
> ```
> ```javascript
> <js code text>
> ```

De eraan voorafgaande blockquote markdown-tekst wordt weergegeven als:

<cs code text>
<js code text>

Codefragmenten

Zie Codefragmenten.

Metagegevens

Zie Metagegevens.

Selectors

U kunt een selector gebruiken wanneer u verschillende pagina's voor hetzelfde artikel met elkaar wilt verbinden en lezers wilt kunnen laten schakelen tussen die pagina's.

Notitie

Deze extensie werkt anders tussen docs.microsoft.com en MSDN.

Single selector

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

En deze wordt als volgt weergegeven:

Multi-selector

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

En deze wordt als volgt weergegeven:

Videosyntaxis

Op dit moment ondersteunt OPS de videosyntaxis voor Channel 9- (CH9) en YouTube-video's. U kunt een video insluiten met de volgende syntaxis zodat OPS de video kan renderen.

> [!VIDEO <channel9_video_link>]
> [!VIDEO <youtube_video_link>]

Voorbeeld:

> [!VIDEO https://channel9.msdn.com/Series/Youve-Got-Key-Values-A-Redis-Jump-Start/03/player]
> [!Video https://www.youtube.com/embed/iAtwVM-Z7rY]

Deze wordt weergegeven als:

<iframe src="https://channel9.msdn.com/Series/Youve-Got-Key-Values-A-Redis-Jump-Start/03/player" width="640" height="320" allowFullScreen="true" frameBorder="0"></iframe>
<iframe src="https://www.youtube.com/embed/iAtwVM-Z7rY" width="640" height="320" allowFullScreen="true" frameBorder="0"></iframe>

En deze wordt als volgt weergegeven op gepubliceerde pagina's:

Notitie

De URL van de CH9-video moet beginnen met https en eindigen met /player. Anders wordt de hele pagina en niet alleen de video ingesloten.

Bestandspaden omzetten

  • Een relatief pad (zoals foo/bar.md) is het pad dat relatief is ten opzichte van het bestand waarin dit pad is geschreven. In het geval van een include is het relatief ten opzichte van het ingesloten bestand. Stel, dat artikel A.md B.md insluit. In B.md is dan een relatief pad opgenomen. Dat pad is dan relatief ten opzichte van B.md in plaats van A.md.
  • Het relatieve pad wordt omgezet tijdens de build (waarbij de .md-extensie wordt verwijderd) en er wordt een build-waarschuwing gegenereerd als het doelbestand niet bestaat.
  • U kunt “../” gebruiken om het bestand te koppelen aan een bestand in de bovenliggende map, maar dat bestand moet dan wel in dezelfde docset aanwezig zijn. U kunt “../” niet gebruiken om een bestand te koppelen aan een andere docset-map.
  • We ondersteunen ook een speciale vorm van relatieve paden die begint met ~ (bijvoorbeeld, ~/foo/bar.md), hetgeen staat voor een bestand relatief ten opzichte van de hoofdmap van een docset. Ook dit type pad wordt tijdens de build gevalideerd en omgezet.
  • Naast Markdown-koppelingen en -afbeeldingen, kunt u een relatief pad gebruiken in een HTML-koppeling (<a>) en een afbeelding (<img>).
  • Een absoluut pad (een pad dat begint met /) is een pad naar de uitvoerwebsite. Wij verwerken geen absolute paden; we laten die voor wat ze zijn in de uitvoer-HTML. Als u een absoluut pad gebruikt, moet u de basis-URL toevoegen en zelf de .md-extensie verwijderen.

HTML-whitelist

U kunt HTML-code in uw inhoud insluiten, zolang dit op de GitHub-whitelist staat. Het is ook mogelijk iframe-elementen te gebruiken voor het insluiten van video’s, ook al is dat niet opgenomen op de GFM-whitelist. HTML die wordt gerenderd door de verschillende processors voor opmaaktalen wordt om beveiligingsredenen verwerkt via een HTML SanitizationFilter. HTML-elementen die niet op de whitelist staan, worden verwijderd. HTML-kenmerken die niet op de whitelist staan, worden verwijderd uit de behouden elementen.

De volgende HTML-elementen, onderverdeeld naar categorie, staan in de whitelist:

Type Elementen
Koppen h1, h2, h3, h4, h5, h6
Prose p, div, blockquote
Opgemaakt pre
Inline b, i, strong, em, tt, code, ins, del, sup, sub, kbd, samp, q, var
Lijsten ol, ul, li, dl, dt, dd
Tabellen table, thead, tbody, tfoot, tr, td, th
Breaks br, hr
Ruby (Oost-Azië) ruby, rt, rp
Video (niet in GFM-whitelist) iframe
Opmerkingen Opmerkingen

De volgende kenmerken, onderverdeeld op basis van element, staan in de whitelist:

Element Kenmerken
a href (http://, https://, mailto://, github-windows:// en github-mac:// alleen URI-schema’s en relatieve paden)
iframe src, allowFullScreen, frameBorder, scrolling
img src (http:// and https:// URI schemes and relative paths only)
div itemscope, itemtype
Alle abbr, accept, accept-charset, accesskey, action, align, alt, axis, border, cellpadding, cellspacing, char, charoff, charset, checked, cite, clear, cols, colspan, color, compact, coords, datetime, dir, disabled, enctype, for, frame, headers, height, hreflang, hspace, ismap, label, lang, longdesc, maxlength, media, method, multiple, name, nohref, noshade, nowrap, prompt, readonly, rel, rev, rows, rowspan, rules, scope, selected, shape, size, span, start, summary, tabindex, target, title, type, usemap, valign, value, vspace, width, itemprop

Zoals u ziet, is het kenmerk id niet in de whitelist opgenomen.

Tabellen

De eenvoudigste manier om een tabel in Markdown te maken is gebruik te maken van pipes en regels.

U kunt de kolommen uitlijnen met behulp van dubbele punten:

|-----:| - this is right aligned
|:-----| -  this is left aligned
|:-----:| - this is centered

U kunt een tabel zonder kop maken. Ga bijvoorbeeld als volgt te werk om een lijst met meerdere kolommen te maken:

|   |   |
| - | - |
| This | table |
| has no | header |

Als u HTML-tabellen gebruikt en uw Markdown wordt niet gerenderd tussen de twee tabellen, moet u een afsluitende br-tag toevoegen na de afsluitende table-tag.

Meer informatie over het maken van tabellen in Markdown vindt u hier:

Tabelterugloop

Belangrijk

Deze klassen werken alleen op de site docs.microsoft.com.

mx-tdBreakAll

Als u een tabel in Markdown maakt, kan de tabel worden uitgebreid naar het navigatievenster rechts, waardoor de tabel onleesbaar wordt. Dat is op te lossen door bij het renderen van Docs de tabel op te splitsen wanneer dat nodig is. U laat eenvoudig de tabel teruglopen met de aangepaste klasse [!div class="mx-tdBreakAll"].

Hier ziet u een Markdown-voorbeeld van een tabel met drie rijen die teruglopen door gebruik te maken van een div met de klassenaam 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.|

Deze wordt als volgt weergegeven:

Naam Syntaxis Verplicht voor installatie op de achtergrond? Beschrijving
Quiet /quiet Ja Het installatieprogramma wordt uitgevoerd zonder dat de UI of prompts worden weergegeven.
NoRestart /norestart Nee Onderdrukt elke poging tot herstarten. De UI geeft standaard een prompt vóór de herstart.
Help /help Nee Biedt hulp- en naslaginformatie. Geeft het juiste gebruik van de setup-opdracht weer, samen met een overzicht van alle opties en alle gedrag.

mx-tdCol2BreakAll

Er kunnen soms hele lange woorden in de tweede kolom van een tabel staan. Om ervoor te zorgen dat lange woorden (zoals paden) netjes worden gesplitst, kunt u de klasse mx-tdCol2BreakAll toepassen met behulp van de div wrapper syntaxis zoals eerder besproken.