Hoe wordt Markdown gebruikt voor het schrijven van technische documentatie

De artikelen in de technische documentatie van de Adobe worden geschreven in een lichte opmaaktaal die Markering, wat zowel gemakkelijk leesbaar als gemakkelijk te leren is.

Aangezien wij de inhoud van Docs van de Adobe in GitHub opslaan, kan het een versie van Markdown gebruiken geroepen GitHub Flavoed Markdown (GFM), die aanvullende functionaliteit biedt voor veelvoorkomende opmaakbehoeften. Bovendien heeft de Adobe Markdown op een aantal manieren uitgebreid om bepaalde aan Help gerelateerde functies zoals notities, tips en ingesloten video's te ondersteunen.

Basisprincipes voor markdown

In de volgende secties worden de grondbeginselen van het ontwerpen in Markdown beschreven.

Koppen

Als u een kop wilt maken, gebruikt u een hash-teken (#) aan het begin van een regel:

# This is level 1 (article title)
## This is level 2
### This is level 3
#### This is level 4
##### This is level 5

Standaardtekst

Een alinea vereist geen speciale syntaxis in Markdown.

Tekst opmaken als vet, plaatst u deze in twee sterretjes. Tekst opmaken als cursief, plaatst u deze in één sterretje:

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

Als u opmaaktekens voor opmaak wilt negeren, gebruikt u \ vóór het teken:

This is not \*italicized\* type.

Genummerde lijsten en lijsten met opsommingstekens

Als u genummerde lijsten wilt maken, begint u met een regel met 1. of 1), maar gebruik beide indelingen niet in dezelfde lijst. U hoeft de getallen niet op te geven. GitHub doet dat voor jou.

1. This is step 1.
1. This is the next step.
1. This is yet another step, the third.

Weergegeven:

Als u opsommingstekens wilt maken, begint u met een regel met * of - of +, maar combineert u de indelingen niet in dezelfde lijst. (Gebruik in hetzelfde document geen opsommingstekens, zoals * en +.)

* First item in an unordered list.
* Another item.
* Here we go again.

Weergegeven:

U kunt lijsten binnen lijsten ook insluiten en inhoud tussen lijstpunten toevoegen.

1. Set up your table and code blocks.
1. Perform this step.

   ![screen](https://experienceleague.adobe.com/docs/contributor/assets/adobe_standard_logo.png?lang=nl)

1. Make sure that your table looks like this:

   | Hello | World |
   |---|---|
   | How | are you? |

1. This is the fourth step.

   >[!NOTE]
   >
   >This is note text.

1. Do another step.

Weergegeven:

Tabellen

Tabellen maken geen deel uit van de kernspecificatie Markering, maar de Adobe ondersteunt ze in zekere mate. Markering ondersteunt geen lijsten met meerdere regels in cellen. U kunt het beste voorkomen dat meerdere regels in tabellen worden gebruikt. U kunt tabellen maken door het verticale streepje (|) te gebruiken om kolommen en rijen te definiëren. Bij deze optie wordt de kolomkop gemaakt, bij elke kolom worden de leidingen van elkaar gescheiden. Neem een lege regel voor de tabel op, zodat deze correct wordt weergegeven.

| Header | Another header | Yet another header |
|--- |--- |--- |
| row 1 | column 2 | column 3 |
| row 2 | row 2 column 2 | row 2 column 3 |

Weergegeven:

Eenvoudige tabellen werken naar behoren in Markering. Tabellen die meerdere alinea's of lijsten in een cel bevatten, zijn echter moeilijk te gebruiken. Voor dergelijke inhoud raden we u aan een andere indeling te gebruiken, zoals koppen en tekst.

Zie voor meer informatie over het maken van tabellen:

Koppelingen

De syntaxis Markdown voor een gealigneerde verbinding bestaat uit [link text] deel, dat de tekst is die zal worden met hyperlink, gevolgd door (file-name.md) gedeelte, dat de URL of bestandsnaam is waarnaar wordt gekoppeld:

[link text](file-name.md)

[Adobe](https://www.adobe.com)

Weergegeven:

Adobe

Gebruik relatieve koppelingen voor koppelingen naar artikelen (kruisverwijzingen) in de opslagplaats. U kunt alle relatieve koppelingsoperanden gebruiken, zoals ./ (huidige map), …/ (één map terug) en …/…/ (twee mappen terug).

See [Overview example article](../../overview.md)

Zie voor meer informatie over koppelen de Koppelingen artikel van deze handleiding voor het koppelen van syntaxis.

Afbeeldingen

![Adobe Logo](/docs/contributor/assets/adobe_standard_logo.png "Hover text")

Weergegeven:

Codeblokken

Markering ondersteunt de plaatsing van codeblokken, zowel inline in een zin als als een apart 'afgezonderd' blok tussen zinnen. Zie voor meer informatie Eigen ondersteuning van markeringen voor codeblokken

Achtertikken gebruiken (`) om inline-codestijlen in een alinea te maken. Als u een specifiek codeblok met meerdere regels wilt maken, voegt u drie achtertikken toe (```) voor en na het codeblok (in Markdown een "fenced codeblok" genoemd en alleen een "code block" component in AEM). Voor afgezonderde codeblokken voegt u de codetaal toe na de eerste set backtikken, zodat de syntaxis van de code correct wordt gemarkeerd met Markering. Voorbeeld: ``javascript`

Voorbeelden:

This is `inline code` within a paragraph of text.

Weergegeven:

Dit is inline code in een alinea met tekst.

Dit is een afgezonderd codeblok:

function test() {
 console.log("notice the blank line before this function?");

Extensies voor aangepaste markeringen

Artikelen in Adoben maken gebruik van de standaardopmaak voor de meeste artikelen, zoals alinea's, koppelingen, lijsten en koppen. Voor een rijkere opmaak kunnen artikelen uitgebreide opmaakfuncties gebruiken, zoals:

Gebruik het blokcitaat van de Prijsverhoging ( >) aan het begin van elke lijn om een uitgebreide component, zoals een nota samen te voegen.

Enkele gebruikelijke opmaakelementen, zoals koppen en codeblokken, bevatten uitgebreide eigenschappen. Als u de standaardeigenschappen moet wijzigen, voegt u de parameters tussen de franse accolades /{ /} toe na de component. Uitgebreide eigenschappen worden in context beschreven.

Notitieblokken

U kunt uit deze typen notitieblokken kiezen om de aandacht op specifieke inhoud te vestigen:

Over het algemeen moeten notenblokken spaarzaam worden gebruikt omdat ze verstorend kunnen zijn. Hoewel ze ook ondersteuning bieden voor codeblokken, afbeeldingen, lijsten en koppelingen, kunt u proberen om de notitieblokken eenvoudig en eenvoudig te houden.

>[!NOTE]
>
>This is a standard NOTE block.

>[!TIP]
>
>This is a standard TIP.

>[!IMPORTANT]
>
>This is an IMPORTANT note.

Weergegeven:

Video's

Ingesloten video's worden niet native gerenderd in Markdown, maar u kunt deze extensie Markdown gebruiken.

>[!VIDEO](https://video.tv.adobe.com/v/29770/?quality=12)

Weergegeven:

Meer als dit

De component "Meer als dit" in AEM wordt aan het einde van een artikel weergegeven. Gerelateerde koppelingen worden weergegeven. Als het artikel wordt gerenderd, kan het dezelfde opmaak krijgen als niveau 2-koppen (##) zonder dat het aan de miniinhoudsopgave wordt toegevoegd.

Weergegeven:

UICONTROL en DNL

Al onze Help-inhoud voor Markdown is gelokaliseerd met behulp van in eerste instantie automatische vertaling. Als de hulp nooit is gelokaliseerd, dan houden wij de machinevertaling. Als de Help-inhoud echter in het verleden is gelokaliseerd, fungeert de door de computer vertaalde inhoud als plaatsaanduiding tijdens het vertalen van de inhoud.

``

Tijdens machinevertaling, items getagd met `` worden gecontroleerd aan de hand van een lokalisatiedatabase voor de juiste vertaling. Als de UI niet gelokaliseerd is, zal deze markering het systeem toestaan om de verwijzing UI in het Engels voor die bepaalde taal (d.w.z. te verlaten. Analytische verwijzingen in het Italiaans).

Broninhoud voorbeeld:

``

In de regel gebruiken we een lijst 'Niet vertalen' om de machinevertalingsprogramma's te vertellen wat ze in het Engels moeten houden. De meest voorkomende items zijn de lange namen van oplossingen, zoals "Adobe Analytics", "Adobe Campaign" en "Adobe Target". Er kunnen zich echter gevallen voordoen waarin de motor gedwongen moet worden het Engels te gebruiken, omdat de term in kwestie op een specifieke of algemene manier kan worden gebruikt. Dit zou het meest voor de hand liggende geval zijn: korte namen voor oplossingen zoals "Analytics", "Campaign", "Target" enz. Het zou voor een machine moeilijk zijn om te begrijpen dat dit oplossingsnamen en geen algemene termen zijn. De tag kan ook worden gebruikt voor namen/functies van derden die altijd in het Engels overblijven of voor kortere tekstgedeelten zoals woordgroepen of zinnen die in het Engels moeten blijven staan.

Broninhoud voorbeeld:

Gotchas en probleemoplossing

Alt-tekst

Alt-tekst met onderstrepingstekens wordt niet correct gerenderd. In plaats van dit bijvoorbeeld te gebruiken:

![Settings_Step_2](/assets/settings_step_2.png)

We raden u aan afbreekstreepjes (-) te gebruiken in plaats van onderstrepingstekens (_) in bestandsnamen.

![Settings-Step-2](/assets/settings-step-2.png)

Apostroffen en aanhalingstekens

Als u tekst kopieert naar een Markeringen-editor, kan de tekst 'slimme' (gekrulde) apostroffen of aanhalingstekens bevatten. Deze moeten worden gecodeerd of gewijzigd in standaardapostroffen of aanhalingstekens. Anders krijgt u oneven tekens zoals deze wanneer het bestand wordt gepubliceerd: It’s

Hier volgen de coderingen voor de "slimme" versies van deze leestekens:

Hoekhaken

Als u punthaken in tekst (geen code) in uw dossier-bijvoorbeeld gebruikt om placeholder te wijzen-moet u de punthaken manueel coderen. Anders denkt Markdown dat ze een HTML-tag moeten zijn.

Coderen <script name> als <script name>

Ampersanden in titels

Ampersands (&) zijn niet toegestaan in titels. Gebruik in plaats hiervan "en" of gebruik de & coderen.

Zie ook

Markeringsmiddelen