Come utilizzare Markdown per la scrittura della documentazione tecnica

Gli articoli della documentazione tecnica di Adobe sono scritti in un linguaggio di markup leggero chiamato Markdown, facile da leggere e da apprendere.

Poiché il contenuto dei documenti Adobe viene archiviato in GitHub, è possibile utilizzare una versione di Markdown denominata GitHub Flavored Markdown (GFM), che offre funzionalità aggiuntive per le esigenze di formattazione comuni. Inoltre, Adobe ha esteso Markdown in diversi modi per supportare determinate funzionalità relative alla Guida, come note, suggerimenti e video incorporati.

Nozioni di base su Markdown

Le sezioni seguenti descrivono le nozioni di base sull’authoring in Markdown.

Intestazioni

Per creare un’intestazione, utilizza un cancelletto (#) all’inizio di una riga:

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

Testo di base

Un paragrafo non richiede una sintassi speciale in Markdown.

Per formattare il testo in grassetto, è necessario racchiuderlo in due asterischi. Per formattare il testo in corsivo, è necessario racchiuderlo in un singolo asterisco:

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

Per ignorare i caratteri di formattazione di Markdown, utilizza \ prima del carattere:

This is not \*italicized\* type.

Elenchi numerati ed elenchi puntati

Per creare elenchi numerati, inizia una riga con 1. o 1), ma non combinare i formati all’interno dello stesso elenco. Non è necessario specificare i numeri, che sono gestiti automaticamente da GitHub.

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

Visualizzato:

Per creare degli elenchi puntati, inizia una riga con * o - o + ma non combinare i formati all’interno dello stesso elenco (non mescolare formati punto elenco, ad esempio * e + all’interno dello stesso documento).

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

Visualizzato:

È inoltre possibile incorporare elenchi all’interno di elenchi e aggiungere contenuto tra gli elementi di un elenco.

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=it)

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.

Visualizzato:

Tabelle

Le tabelle non fanno parte della specifica di base di Markdown ma sono supportate in parte da Adobe. Gli elenchi su più righe in una cella non sono supportati da Markdown. Si consiglia di evitare di utilizzare più righe nelle tabelle. Puoi creare tabelle utilizzando il carattere barra verticale (|) per delineare colonne e righe. I trattini creano l’intestazione di ogni colonna, mentre le barre verticali separano ciascuna colonna. Includi una riga vuota prima della tabella affinché venga riprodotta correttamente.

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

Visualizzato:

Le tabelle semplici funzionano correttamente in Markdown, mentre le tabelle che includono più paragrafi o elenchi all’interno di una cella sono difficili da utilizzare. Per tali contenuti, si consiglia di utilizzare un altro formato, ad esempio intestazioni e testo.

Per ulteriori informazioni sulla creazione di tabelle, vedi:

Collegamenti

La sintassi Markdown per un collegamento in linea è costituita dalla porzione [link text], che è il testo che avrà un collegamento ipertestuale, seguita dalla porzione (file-name.md), ovvero l’URL o il nome file al quale verrà effettuato il collegamento:

[link text](file-name.md)

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

Visualizzato:

Adobe

Per i collegamenti agli articoli (rimandi) all’interno dell’archivio, utilizza i collegamenti relativi. Puoi utilizzare tutti gli operandi di collegamento relativo, come ad esempio ./ (directory corrente), …/ (indietro di una directory), e …/…/ (indietro di due directory).

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

Per ulteriori informazioni sui collegamenti, consulta l’articolo Collegamenti di questa guida per la sintassi di collegamento.

Immagini

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

Visualizzato:

Blocchi di codice

Markdown supporta il posizionamento di blocchi di codice sia in linea in una frase sia come un blocco separato “delimitato” tra due frasi. Per informazioni, consulta il supporto nativo di Markdown per i blocchi di codice

Utilizza gli apici retroversi (`) per creare stili di codice in linea all’interno di un paragrafo. Per creare un blocco di codice specifico su più righe, aggiungi tre apici retroversi (```) prima e dopo il blocco di codice (denominato “blocco di codice delimitato” in Markdown e semplicemente componente “blocco di codice” in AEM). Per i blocchi di codice delimitati, aggiungi il linguaggio del codice dopo il primo set di apici retroversi affinché la sintassi del codice venga evidenziata correttamente da Markdown. Esempio: ```javascript

Esempi:

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

Visualizzato:

This is inline code within a paragraph of text.

Questo è un blocco di codice delimitato:

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

Estensioni personalizzate Markdown

Gli articoli Adobe utilizzano Markdown standard per la maggior parte della formattazione degli articoli, come paragrafi, collegamenti, elenchi e intestazioni. Per una formattazione più completa, gli articoli possono utilizzare funzioni estese di Markdown quali:

Utilizza il blockquote di Markdown ( > ) all’inizio di ogni riga per collegare un componente esteso, come ad esempio una nota.

Alcuni elementi comuni di Markdown come le intestazioni e i blocchi di codice includono proprietà estese. Se devi modificare le proprietà predefinite, aggiungi i parametri tra parentesi graffe /{ /} dopo il componente. Le proprietà estese vengono descritte nel contesto.

Blocchi per le note

Per richiamare l’attenzione su contenuti specifici, puoi scegliere tra questi quattro tipi di blocchi per le note:

In generale, i blocchi per le note devono essere utilizzati con cautela poiché possono risultare di disturbo. Anche se supportano a loro volta blocchi di codice, immagini, elenchi e collegamenti, prova a mantenere i blocchi per le note semplici e chiari.

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

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

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

Visualizzato:

Video

I video incorporati non vengono renderizzati in modo nativo in Markdown ma puoi utilizzare questa estensione Markdown.

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

Visualizzato:

Altri argomenti correlati

Il componente “Altri argomenti correlati” in AEM viene visualizzato alla fine di un articolo. Permette di visualizzare collegamenti correlati. Quando viene eseguito il rendering dell’articolo, questo può essere formattato come intestazione di livello 2 (##) senza essere aggiunto al minisommario.

Visualizzato:

UICONTROL e DNL

Tutto il contenuto della guida Markdown viene localizzato inizialmente utilizzando la traduzione automatica. Se la guida non è mai stata localizzata, viene mantenuta la traduzione automatica. Se invece il contenuto della guida è stato localizzato in passato, la traduzione automatica verrà temporaneamente utilizzata come segnaposto finché la traduzione umana non sarà stata finalizzata.

``

Durante la traduzione automatica, gli elementi con i tag `` vengono verificati rispetto a un database di localizzazione. Nel caso in cui l’interfaccia utente non sia localizzata, questo tag consentirà al sistema di lasciare il riferimento all’interfaccia utente in inglese per quella particolare lingua (ad es. riferimenti di Analytics in italiano).

Esempio di contenuto di origine:

[!DNL]

Di regola, usiamo un elenco di termini da “Non tradurre” per istruire i motori di traduzione automatica su ciò che mantenere in inglese. Gli elementi più importanti sono ad esempio nomi di soluzioni lunghi, come “Adobe Analytics”, “Adobe Campaign” e “Adobe Target”. Tuttavia, ci possono essere casi in cui è necessario costringere il motore a usare l’inglese perché il termine in questione può essere utilizzato in modo specifico o generale. Il caso più evidente sarebbe quello dei nomi brevi delle soluzioni come “Analytics”, “Campaign”, “Target”, ecc. In questo caso è difficile per una macchina capire che si tratta di nomi di soluzioni e non di termini generici. Il tag può essere utilizzato anche per nomi/funzioni di terze parti che rimangono sempre in inglese o per sezioni più brevi di testo, come un termine o una frase, che devono rimanere in inglese.

Esempio di contenuto di origine:

Suggerimenti e risoluzione dei problemi

Testo alternativo

Il testo alternativo che contiene caratteri di sottolineatura non viene visualizzato correttamente. Ad esempio, invece di utilizzare quanto segue:

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

La best practice prevede l’utilizzo dei trattini (-) anziché dei caratteri di sottolineatura (_) nei nomi dei file.

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

Apostrofi e virgolette

Se copi del testo in un editor di Markdown, il testo potrebbe contenere apostrofi o virgolette “intelligenti” (curvi). Questi devono essere codificati o modificati in apostrofi o virgolette semplici. In caso contrario, quando il file viene pubblicato si ottengono caratteri come questi: It’s

Queste sono le codifiche per le versioni “intelligenti” di tali segni di punteggiatura:

Parentesi acute

Se utilizzi delle parentesi acute nel testo (non nel codice) del file (ad esempio, per indicare un segnaposto) devi codificare manualmente le parentesi acute. In caso contrario, verranno interpretate da Markdown come un tag HTML.

Ad esempio, codifica <script name> come <script name>

E commerciale nei titoli

Le e commerciali (&) non sono consentite nei titoli. Utilizza invece “e” oppure la codifica &.

Vedi anche

Risorse su Markdown