Procedure consigliate per Markdown

Questo articolo fornisce indicazioni specifiche per l'uso di Markdown nella documentazione. Non è un'esercitazione per Markdown. Se hai bisogno di un tutorial su Markdown, consulta questa guida rapida Markdown.

La pipeline di compilazione che compila la documentazione usa markdig per elaborare i documenti Markdown. Markdig analizza i documenti in base alle regole della specifica CommonMark più recente. OPS segue la specifica CommonMark e aggiunge alcune estensioni per funzionalità specifiche della piattaforma, ad esempio tabelle e avvisi.

La specifica CommonMark è più restrittiva sulla costruzione di alcuni elementi Markdown. Prestare particolare attenzione ai dettagli forniti in questo documento.

L'estensione markdownlint in VS Code viene usata per applicare le regole di stile e formattazione. Questa estensione viene installata come parte di Learn Authoring Pack.

Linee vuote, spazi e tabulazioni

Le righe vuote indicano anche la fine di un blocco in Markdown.

• Inserire un singolo vuoto tra i blocchi Markdown di tipi diversi; ad esempio tra un paragrafo e un elenco o un'intestazione.
• Non usare più righe vuote. Il rendering di più righe vuote viene eseguito come una singola riga vuota in HTML, pertanto le righe vuote aggiuntive non sono necessarie.
• Non usare inserire più righe vuote consecutive in un blocco di codice, le righe vuote consecutive interrompono il blocco di codice.

La spaziatura è significativa in Markdown.

• Rimuovere spazi aggiuntivi alla fine delle linee. Gli spazi finali possono modificare come viene visualizzato Markdown.
• Usare sempre gli spazi anziché le tabulazioni (tabulazioni rigide).

Titoli e intestazioni

Usare solo intestazioni ATX (# stile, anziché = intestazioni di stile o - ).

• Utilizzare il caso della frase: solo i nomi propri e la prima lettera dei titoli o delle intestazioni devono essere maiuscoli.
• Includere uno spazio singolo tra il # e la prima lettera dell'intestazione
• Racchiudere le intestazioni con una singola riga vuota
• Non usare più H1 per documento
  • Deve essere la prima intestazione
  • Deve corrispondere al titolo dell'articolo
• Incrementa i livelli di intestazione di uno - non saltare i livelli
• Limitare la profondità a H3 o H4
• Evitare di usare il grassetto o altri markup nelle intestazioni

Limitare la lunghezza della riga a 100 caratteri

Per gli articoli concettuali e le informazioni di riferimento sui cmdlet, limitare le righe a 100 caratteri. Per about_ gli articoli, limitare la lunghezza della riga a 79 caratteri. La limitazione della lunghezza della linea migliora la leggibilità delle differenze e della git cronologia. Rende inoltre più semplice per altri scrittori fornire contributi.

Usare l'estensione Reflow Markdown in VS Code per rielaborare i paragrafi in modo da adattare la lunghezza della riga prevista.

Alcuni tipi di contenuto non possono essere facilmente riflowati. Ad esempio, il codice all'interno dei blocchi di codice può anche essere difficile da rielaborare, a seconda del contenuto e del linguaggio di codice. Non è possibile riadattare una tabella. In questi casi, usa il tuo giudizio migliore per mantenere il contenuto il più vicino possibile al limite di 100 caratteri.

Enfasi

Per enfasi, Markdown supporta il grassetto e il corsivo. Markdown consente di usare * o _ per contrassegnare l'enfasi. Tuttavia, per essere coerenti e mostrare la finalità:

• Usare ** per il grassetto
• Usare _ per il corsivo

Seguendo questo modello è più semplice per gli altri comprendere la finalità del markup quando è presente una combinazione di grassetto e corsivo in un documento.

Liste

Se l'elenco contiene più frasi o paragrafi, è consigliabile usare un'intestazione di livello superiore anziché un elenco.

Racchiudere elenchi con una singola riga vuota.

Elenchi non ordinati

• Non terminare gli elementi dell'elenco con un punto a meno che non contengano più frasi.
• Usare il trattino (-) per i punti elenco per evitare confusione con il markup di enfasi che usa l'asterisco (*).
• Per includere un paragrafo o altri elementi in un punto elenco, inserire un'interruzione di riga e allineare il rientro al primo carattere dopo il punto elenco.

Per esempio:

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

Si tratta di un elenco che contiene elementi figlio in un elemento punto elenco.

• Primo punto elenco

  Frase che spiega il primo punto elenco.

  • Sotto-elemento elenco puntato

    Frase che spiega il punto elenco figlio.

• Secondo elemento punto elenco

• Terzo elemento punto elenco

Elenchi ordinati

• Tutti gli elementi di un elenco numerato devono usare il numero 1. anziché incrementare ogni elemento.
  • Il rendering markdown incrementa automaticamente il valore.
  • In questo modo, la riordinamento degli elementi risulta più semplice e standardizza il rientro del contenuto subordinato.
• Per includere un paragrafo o altri elementi sotto un elemento numerato, allineare l'indentazione con il primo carattere dopo il numero dell'elemento.

Per esempio:

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.

Il rendering del markdown risultante viene eseguito nel modo seguente:

1. Per il primo elemento, inserire un singolo spazio dopo .1 Le frasi lunghe devono essere racchiuse nella riga successiva e devono essere allineate con il primo carattere dopo l'indicatore di elenco numerato.

   Per includere un secondo elemento, inserire un'interruzione di riga dopo il primo e allineare i rientri. Il rientro del secondo elemento deve essere allineato con il primo carattere dopo l'indicatore di elenco numerato.

2. L'elemento numerato successivo inizia qui.

Immagini

La sintassi per includere un'immagine è:

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

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

Dove alt text è una breve descrizione dell'immagine ed <folderPath> è un percorso relativo all'immagine.

• Il testo alternativo è necessario per supportare le utilità per la lettura dello schermo per gli ipovedenti.
• Le immagini devono essere archiviate in una media/<article-name> cartella all'interno della cartella contenente l'articolo.
  • Creare una cartella che corrisponda al nome file dell'articolo nella media cartella . Copiare le immagini per tale articolo in tale nuova cartella.
• Non condividere immagini tra articoli.
  • Se un'immagine viene usata da più articoli, ogni cartella deve avere una copia di tale immagine.
  • In questo modo si impedisce la modifica di un'immagine in un articolo che influisce su un altro articolo.

Sono supportati i tipi di file di immagine seguenti: *.png, *.gif, *.jpeg, *.jpg, *.svg

Estensione Markdown - Caselle di avviso

Learn Authoring Pack contiene strumenti che supportano funzionalità specifiche per il sistema di pubblicazione. Gli avvisi sono un'estensione Markdown per creare le virgolette che eseguono il rendering con colori e icone che evidenziano il significato del contenuto. Sono supportati i tipi di avviso seguenti:

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

Questi avvisi hanno un aspetto simile al seguente in Microsoft Learn:

Blocco note

Annotazioni

Le informazioni che l'utente deve notare anche quando legge velocemente.

Blocco suggerimenti

Suggerimento

Informazioni facoltative per consentire a un utente di avere maggiore successo.

Blocco importante

Importante

Informazioni essenziali necessarie per il successo dell'utente.

Blocco di cautela

Attenzione

Conseguenze negative potenziali di un'azione.

Blocco di avviso

Avvertimento

Certe conseguenze pericolose di un'azione.

Estensione Markdown - Tabelle

Una tabella è una disposizione dei dati con righe e colonne costituite da:

• Una singola riga di intestazione
• Riga delimitatore che separa l'intestazione dai dati
• Zero o più righe di dati

Ogni riga è costituita da celle contenenti testo arbitrario separato da pipe (|). Per maggiore chiarezza, è consigliabile anche un tubo iniziale e finale. Gli spazi tra pipe e contenuto delle celle vengono tagliati. Gli elementi a livello di blocco non possono essere inseriti in una tabella. Tutto il contenuto di una riga deve trovarsi in una singola riga.

La riga del delimitatore è costituita da celle il cui solo contenuto è trattino (-) e, facoltativamente, un punto iniziale o finale (:) o entrambi, per indicare rispettivamente l'allineamento sinistro, destro o centrale.

Per le tabelle di piccole dimensioni, è consigliabile usare invece un elenco. Gli elenchi sono:

• Più facile da gestire e leggere
• Può essere adattato per rientrare entro il limite di 100 caratteri.
• Più accessibile per gli utenti che usano le utilità per la lettura dello schermo per assistenza visiva

Per altre informazioni, vedere la sezione Tabelle delle informazioni di riferimento su Markdown per Microsoft Learn.

Collegamenti ipertestuali

• I collegamenti ipertestuali devono usare la sintassi [friendlyname](url-or-path)Markdown .

• Il sistema di pubblicazione supporta tre tipi di collegamenti:

  • Collegamenti URL
  • Collegamenti ai file
  • Collegamenti tra riferimenti

• Tutti gli URL ai siti Web esterni devono usare HTTPS, a meno che non sia valido per il sito di destinazione.

• I collegamenti devono avere un nome descrittivo, in genere il titolo dell'articolo collegato

• Evitare di usare apici inversi, grassetto o altri markup all'interno delle parentesi di un collegamento ipertestuale.

• Gli URL nudi possono essere usati quando si documenta un URI specifico, ma devono essere racchiusi tra i backtick. Per esempio:

  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.
  

• Usare i riferimenti ai collegamenti dove consentiti . I riferimenti ai collegamenti all'interno dei paragrafi rendono i paragrafi più leggibili.

  I riferimenti di collegamento dividono un collegamento Markdown in due parti:

  • riferimento al collegamento : [friendlyname][id]
  • definizione del collegamento : [id]: url-or-path

Collegamenti di tipo URL

• I collegamenti URL ad altri articoli in learn.microsoft.com devono usare percorsi relativi al sito. Il modo più semplice per creare un collegamento relativo al sito consiste nel copiare l'URL dal browser e quindi rimuovere https://learn.microsoft.com/en-us dal valore incollato in markdown.
• Non includere le impostazioni locali negli URL nelle proprietà Microsoft (rimuovi /en-us dall'URL) o nei collegamenti di Wikipedia.
• Rimuovere eventuali parametri di query non necessari dall'URL. Esempi da rimuovere:
  • ?view=powershell-5.1 - usato per il collegamento a una versione specifica di PowerShell
  • ?redirectedfrom=MSDN - aggiunto all'URL quando si viene reindirizzati da un articolo precedente alla nuova posizione
• Se è necessario collegare a una versione specifica di un documento, è necessario aggiungere il &preserve-view=true parametro alla stringa di query. Ad esempio: ?view=powershell-5.1&preserve-view=true
• Nei siti Microsoft i collegamenti URL non contengono estensioni di file (ad esempio, no .md)

Collegamenti di tipo file

• Un collegamento di file viene usato per collegare un articolo di riferimento a un altro o da un articolo concettuale a un altro nello stesso docset.
  • Se è necessario collegare un articolo concettuale a un articolo di riferimento, è necessario usare un collegamento URL.
  • Se è necessario collegare un articolo in un altro docset o tra repository, è necessario usare un collegamento URL.
• Usare percorsi file relativi (ad esempio: ../folder/file.md)
• Tutti i percorsi di file usano caratteri barra in avanti (/)
• Includere l'estensione del file (ad esempio, .md)

Collegamenti tra riferimenti

I collegamenti tra riferimenti sono una funzionalità speciale supportata dal sistema di pubblicazione. È possibile utilizzare collegamenti di riferimento negli articoli concettuali per connettersi alla documentazione dell'API .NET o dei cmdlet.

• Per i collegamenti alle informazioni di riferimento sulle API .NET, vedere Usare i collegamenti nella documentazione della Guida per i collaboratori centrale.

• I collegamenti ai riferimenti ai cmdlet hanno il formato seguente: xref:<module-name>.<cmdlet-name>. Ad esempio, per collegarsi al Get-Content cmdlet nel modulo Microsoft.PowerShell.Management .

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

Collegamento diretto

Il collegamento diretto è consentito sia sui link URL che sui link di file.

• Il testo dell'ancoraggio deve essere minuscolo
• Aggiungere l'ancoraggio alla fine del percorso di destinazione. Per esempio:
  • [about_Splatting](about_Splatting.md#splatting-with-arrays)
  • [custom key bindings](https://code.visualstudio.com/docs/getstarted/keybindings#_custom-keybindings-for-refactorings)

Per altre informazioni, vedere Usare i collegamenti nella documentazione.

Intervalli di codice

Gli intervalli di codice vengono usati per frammenti di codice inline all'interno di un paragrafo. Usare i singoli backtick per indicare un intervallo di codice. Per esempio:

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

In questo esempio viene eseguito il rendering come segue:

I nomi dei cmdlet di PowerShell usano la Verb-Noun convenzione di denominazione.

Blocchi di codice

I blocchi di codice vengono usati per esempi di comandi, esempi di codice su più righe, linguaggi di query e output. Esistono due modi per indicare che una sezione di testo in un file di articolo è un blocco di codice: circondandola con tre backtick (```) o rientrandola.

Non usare mai il rientro perché è troppo facile da sbagliare e può essere difficile per un altro scrittore comprendere le tue intenzioni quando è necessario modificare il tuo articolo.

I blocchi di codice delimitati possono includere un tag facoltativo che indica la sintassi del linguaggio contenuta nel blocco. La piattaforma di pubblicazione supporta un elenco di tag di lingua. Il tag di lingua viene usato per fornire l'evidenziazione della sintassi quando viene eseguito il rendering dell'articolo nella pagina Web. Il tag di lingua non fa distinzione tra maiuscole e minuscole, ma è consigliabile usare lettere minuscole ad eccezione di alcuni casi speciali.

• I blocchi di codice senza tag possono essere usati per blocchi di sintassi o altri tipi di contenuto in cui l'evidenziazione della sintassi non è necessaria.
• Quando viene visualizzato l'output di un comando, usare un blocco di codice con tag di lingua Output. La casella sottoposta a rendering viene etichettata come Output e non include l'evidenziazione della sintassi.
• Se l'output si trova in una lingua supportata specifica, usare il tag di lingua appropriato. Ad esempio, molti comandi producono JSON, quindi utilizza il tag json.
• Se si usa un tag di linguaggio non supportato, il blocco di codice verrà eseguito senza evidenziazione della sintassi. Il tag di lingua diventa l'etichetta per la casella del codice di cui è stato eseguito il rendering nella pagina Web. In maiuscolo il tag in modo che l'etichetta sia maiuscola nella pagina Web.

Passaggi successivi

guida di stile di PowerShell