Modello di metadati e Markdown per i documenti .NET

Articolo
08/10/2023

Questo modello dotnet/docs contiene esempi di sintassi Markdown e linee guida per l'impostazione dei metadati.

Per creare un file Markdown, copiare in un nuovo file il modello incluso, completare i metadati come specificato di seguito e impostare l'intestazione H1 per il titolo dell'articolo.

Metadati

Il blocco di metadati necessario si trova nel seguente blocco di metadati di esempio:

---
title: [ARTICLE TITLE]
description: [usually a summary of your first paragraph. It gets displayed in search results, and can help drive the correct traffic if well written.]
author: [GITHUB USERNAME]
ms.date: [CREATION/UPDATE DATE - mm/dd/yyyy]
---
# The H1 should not be the same as the title, but should describe the article contents

Tra i due punti (:) e il valore di un elemento di metadati deve essere presente uno spazio.
I due punti in un valore (ad esempio in un titolo) interrompono l'esecuzione del parser di metadati. In questo caso, racchiudere il titolo tra virgolette doppie (ad esempio title: "Writing .NET Core console apps: An advanced step-by-step guide").
title: appare nei risultati dei motori di ricerca. Il titolo non deve essere identico al titolo incluso nell'intestazione H1 e non può contenere più di 60 caratteri.
description: riepiloga il contenuto dell'articolo. In genere viene visualizzato nella pagina dei risultati della ricerca ma non viene utilizzato per classificare i risultati. La lunghezza deve essere inclusa tra 115 e 145 caratteri, spazi inclusi.
author: deve contenere il nome utente GitHub dell'autore.
ms.date: data dell'ultimo aggiornamento significativo. Aggiornare questo valore negli articoli esistenti se è stata eseguita una revisione e un aggiornamento dell'intero articolo. Per aggiornamenti minori, quali correzioni ortografiche o simili, non è necessario aggiornare il valore.

A ogni articolo sono associati altri metadati, ma in generale la maggior parte dei metadati viene applicata a livello della cartella e specificata in docfx.json.

Nozioni di base su Markdown, GFM e caratteri speciali

Per le nozioni di base su Markdown, GitHub Flavored Markdown (GFM) e sulle estensioni specifiche per OPS, vedere l'articolo Informazioni di riferimento su Markdown.

Markdown usa caratteri speciali come *, 'e # per la formattazione. Se si vuole includere uno di questi caratteri nel contenuto, seguire una di queste due procedure:

Inserire una barra rovesciata prima del carattere speciale per "escape" (ad esempio, \* per un oggetto *).
Usare il codice di entità HTML per il carattere , ad esempio * per un oggetto *.

Nomi di file

Per i nomi di file sono valide le seguenti regole:

Contengono solo lettere minuscole, numeri e trattini.
Non usare spazi o segni di punteggiatura. Usare il trattino per separare le parole e i numeri nel nome del file.
Usare verbi di azione specifici, ad esempio sviluppare, acquistare, compilare, risolvere. Non usare parole al gerundio.
Non usare parole estremamente brevi, ad esempio "un", "e", "il", "in", "o" e così via.
Usare il formato Markdown e l'estensione file md.
Usare nomi di file brevi. I nomi vengono inclusi nell'URL dell'articolo.

Titoli

Usare le maiuscole/minuscole come nelle frasi comuni. Usare sempre la maiuscola per la prima parola di un titolo.

Stile del testo

Corsivo
Usarlo per file, cartelle, percorsi (per elementi lunghi, suddivisi sulla stessa riga), termini nuovi.

Grassetto
Usarlo per elementi dell'interfaccia utente.

Code
Usarlo per il codice inline, le parole chiave del linguaggio, i nomi di pacchetti NuGet, i comandi della riga di comando, i nomi di tabella e colonna del database e gli URL sui quali non è possibile fare clic.

Collegamenti

Vedere l'articolo generale Collegamenti per informazioni su ancoraggi, collegamenti interni, collegamenti ad altri documenti, inclusioni di codice e collegamenti esterni.

Il team di documentazione di .NET utilizza le convenzioni seguenti:

Nella maggior parte dei casi si usano collegamenti relativi e si sconsiglia l'uso di ~/ nei collegamenti, perché i collegamenti relativi vengono risolti nell'origine in GitHub. Tuttavia quando si definisce il collegamento a un file in un repository dipendente, viene usato il carattere ~/ per specificare il percorso. Dato che i file nel repository dipendente si trovano in una posizione diversa in GitHub, i collegamenti non vengono risolti correttamente con collegamenti relativi, indipendentemente da come sono stati scritti.
La specifica del linguaggio C# e la specifica del linguaggio Visual Basic sono incluse nei documenti .NET mediante l'aggiunta dell'origine dai repository del linguaggio. Le origini di markdown vengono gestite nei repository csharplang e vblang.

I collegamenti a una specifica devono fare riferimento alle directory di origine che includono le specifiche corrispondenti. Per C# la directory è ~/_csharplang/spec e per VB la directory è ~/_vblang/spec come illustrato nell'esempio seguente:

[C# Query Expressions](~/_csharplang/spec/expressions.md#query-expressions)

Collegamenti alle API

Il sistema di build dispone di estensioni che consentono il collegamento alle API .NET senza dover ricorrere a collegamenti esterni. Si usa una delle sintassi seguenti:

Collegamento automatico: <xref:UID> o <xref:UID?displayProperty=nameWithType>

Il parametro di query displayProperty produce un testo del collegamento completo. Per impostazione predefinita, il testo del collegamento mostra solo il nome del membro o del tipo.
Collegamento Markdown: [link text](xref:UID)

Può essere usato quando si vuole personalizzare il testo del collegamento visualizzato.

Esempi:

<xref:System.String> viene visualizzato come String
<xref:System.String?displayProperty=nameWithType> viene visualizzato come System.String
[String class](xref:System.String) viene visualizzato come String class

Per altre informazioni sull'uso di questa notazione, vedere Using cross reference (Uso del riferimento incrociato).

Alcuni ID UID contengono i caratteri speciali ', # o *, il valore UID deve essere codificato rispettivamente come %60, %23 e %2A rispettivamente. A volte sono presenti parentesi con codifica, ma questo non è un requisito.

Esempi:

System.Threading.Tasks.Task'1 diventa System.Threading.Tasks.Task%601
System.Exception.#ctor diventa System.Exception.%23ctor
System.Lazy'1.#ctor(System.Threading.LazyThreadSafetyMode) diventa System.Lazy%601.%23ctor%28System.Threading.LazyThreadSafetyMode%29

È possibile trovare gli UID dei tipi, un elenco di overload di membro o un membro in overload specifico in https://xref.learn.microsoft.com/autocomplete. La stringa di query ?text=*\<type-member-name>* identifica il tipo o il membro di cui si vogliono visualizzare gli UID. Ad esempio, https://xref.learn.microsoft.com/autocomplete?text=string.format recupera gli overload di String.Format. Lo strumento cerca il parametro query text fornito in qualsiasi parte dell'UID. Ad esempio è possibile cercare il nome membro (ToString), il nome membro parziale (ToStri), il tipo e il nome membro (Double.ToString) e così via.

Se si aggiunge un oggetto * (o %2A) dopo l'UID, il collegamento rappresenta la pagina di overload e non un'API specifica. Ad esempio, è possibile usare tale opzione quando si vuole collegare all'elenco<T>. Pagina Metodo BinarySearch in modo generico anziché un overload specifico, ad esempio List<T>. BinarySearch(T, IComparer<T>). È anche possibile usare * per collegare una pagina membro quando il membro non è in overload; ciò consente di salvare la necessità di includere l'elenco dei parametri nell'interfaccia utente.

Per il collegamento all'overload di un metodo specifico, è necessario includere il nome del tipo completo di ciascun parametro del metodo. Ad esempio, <xref:System.DateTime.ToString> collega al metodo DateTime.ToString senza parametri, mentre <xref:System.DateTime.ToString(System.String,System.IFormatProvider)> collega al metodo DateTime.ToString(String,IFormatProvider).

Per collegare un tipo generico, ad esempio System.Collections.Generic.List<T>, usare il carattere ' (%60) seguito dal numero di parametri di tipo generici. Ad esempio, <xref:System.Nullable%601> i collegamenti al tipo T System.Nullable<>, mentre <xref:System.Func%602> i collegamenti al delegato System.Func<T,TResult>.

Codice

Il miglior metodo per includere codice è l'inclusione di frammenti di codice da un esempio funzionante. Creare l'esempio in base alle istruzioni fornite nell'articolo Contributing to .NET docs (Contributo ai documenti .NET). L'inclusione di frammenti da programmi completi garantisce che tutto il codice sia conforme al sistema di integrazione continua (CI). Se tuttavia è necessario visualizzare un elemento che provoca errori di compilazione o di runtime, è possibile usare i blocchi di codice inline.

Per informazioni sulla sintassi di Markdown per la visualizzazione del codice in docs, vedere Come includere codice in docs.

Immagini

Immagine statica o GIF animata

![this is the alt text](../images/Logo_DotNet.png)

Immagine collegata

[![alt text for linked image](../images/Logo_DotNet.png)](https://dot.net)

Video

È possibile incorporare video youTube in un file Markdown. Per ottenere l'URL corretto del video, fare clic con il pulsante destro del mouse sul video, selezionare Copia codice di incorporamento e copiare l'URL dall'elemento <iframe>.

> [!VIDEO <youtube_video_link>]

Ad esempio:

> [!VIDEO https://www.youtube.com/embed/Q2mMbjw6cLA]

estensioni learn.microsoft

learn.microsoft offre alcune estensioni aggiuntive per GitHub Flavored Markdown.

Elenchi con segni di spunta

Per gli elenchi è disponibile uno stile personalizzato. È possibile contrassegnare gli elenchi con segni di spunta verdi.

> [!div class="checklist"]
> * How to create a .NET Core app
> * How to add a reference to the Microsoft.XmlSerializer.Generator package
> * How to edit your MyApp.csproj to add dependencies
> * How to add a class and an XmlSerializer
> * How to build and run the application

Il rendering è il seguente:

Come creare un'app .NET Core
Come aggiungere un riferimento al pacchetto Microsoft.XmlSerializer.Generator
Come modificare MyApp.csproj per aggiungere dipendenze
Come aggiungere una classe e un elemento XmlSerializer
Come compilare ed eseguire l'applicazione

Per un esempio di elenchi con segni di spunta, vedere la documentazione di .NET Core.

Pulsanti

Collegamenti ai pulsanti:

> [!div class="button"]
> [button links](dotnet-contribute.md)