Condividi tramite

Usare collegamenti nella documentazione

  • Articolo

Questo articolo descrive come usare i collegamenti ipertestuali delle pagine ospitate in Microsoft Learn. È facile aggiungere collegamenti all'interno di markdown, con alcune convenzioni. I collegamenti possono indirizzare gli utenti a contenuto all'interno della stessa pagina, in altre pagine vicine o in siti e URL esterni.

Il back-end di Microsoft Learn usa Open Publishing Services (OPS), che supporta Markdown conforme a CommonMark analizzato tramite il motore di analisi Markdig . Questo sapore markdown è per lo più compatibile con GitHub Flavored Markdown (GFM), poiché la maggior parte dei documenti è archiviata in GitHub e può essere modificata lì. Altre funzionalità vengono aggiunte tramite le estensioni per Markdown.

Importante

Tutti i collegamenti devono essere protetti (https vs http) ogni volta che la destinazione lo supporta.

Testo del collegamento

Le parole che vengono incluse nel testo del collegamento devono essere semplici. Devono quindi essere parole normali o il titolo della pagina alla quale porta il collegamento.

Importante

Non usare "clicca qui" come testo del collegamento. È una scelta inefficace per l'ottimizzazione dei motori di ricerca e non descrive adeguatamente la destinazione.

Risposta corretta:

  • For more information, see the [contributor guide index](https://github.com/Azure/azure-content/blob/master/contributor-guide/contributor-guide-index.md).

  • For more details, see the [SET TRANSACTION ISOLATION LEVEL](/sql/t-sql/statements/set-transaction-isolation-level-transact-sql) reference.

Risposta errata:

  • For more details, see [https://msdn.microsoft.com/library/ms173763.aspx](https://msdn.microsoft.com/library/ms173763.aspx).

  • For more information, click [here](https://github.com/Azure/azure-content/blob/master/contributor-guide/contributor-guide-index.md).

Collegamenti da un articolo a un altro

Esistono due tipi di collegamenti ipertestuali supportati dal sistema di pubblicazione: URL e collegamenti di file.

Un collegamento URL può essere un percorso URL relativo alla radice di https://learn.microsoft.como un URL assoluto che include la sintassi url completa, ad esempio https://github.com/MicrosoftDocs/PowerShell-Docs.

  • Usare collegamenti URL quando si crea un collegamento a contenuto al di fuori del docset corrente o tra un riferimento generato automaticamente e articoli concettuali all'interno del docset.
  • Il modo più semplice per creare un collegamento relativo consiste nel copiare l'URL dal browser e quindi nel rimuovere https://learn.microsoft.com/en-us dal valore incollato nel codice Markdown.
  • Non includere impostazioni locali negli URL per le proprietà Microsoft, ad esempio rimuovere /en-us dall'URL.

Un collegamento a file viene usato per collegare un articolo a un altro all'interno del docset.

  • Tutti i percorsi di file usano caratteri barra (/) anziché caratteri barra rovesciata.

  • Un articolo si collega a un altro articolo nella stessa directory:

    [link text](article-name.md)

  • Un articolo si collega a un articolo nella directory padre della directory corrente:

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

  • Un articolo si collega a un articolo in una sottodirectory della directory corrente:

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

  • Un articolo si collega a un articolo in una sottodirectory della directory padre della directory corrente:

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

  • Alcuni articoli sono costituiti da un .yml file e .md , in cui il .yml file contiene metadati e .md contiene il contenuto. In tal caso, collegarsi al .yml file:

    [link text](../directory/article-name.yml) (non [link text](../directory/article-name-content.md))

Nota

Nessuno degli esempi precedenti usa ~/ come parte del collegamento. Per creare un collegamento a un percorso assoluto che inizia dalla radice del repository, iniziare il collegamento con /. Quando ci si sposta nei repository di origine in GitHub, l'inserimento di ~/ genera collegamenti non validi. Iniziare il percorso con / risolve correttamente il problema.

Il contenuto pubblicato in Microsoft Learn ha la struttura dell'URL seguente:

https://learn.microsoft.com/<locale>/<product-service>/[<feature-service>]/[<subfolder>]/<topic>[?view=<view-name>]

Esempi:

https://learn.microsoft.com/azure/load-balancer/load-balancer-overview

https://learn.microsoft.com/powershell/azure/overview?view=azurermps-5.1.1
  • <locale> - Lingua dell'articolo (esempio: en-us o de-de)
  • <product-service> - Nome del prodotto o del servizio (esempio: powershell, dotnet o azure)
  • [<feature-service>] (facoltativo) - Nome della funzionalità o del servizio secondario del prodotto (esempio: csharp o load-balancer)
  • [<subfolder>] (facoltativo) - Nome di una sottocartella all'interno di una funzionalità
  • <topic> - Nome del file dell'articolo per l'argomento (esempio: load-balancer-overview o overview)
  • [?view=\<view-name>] (facoltativo) - Nome visualizzazione usato dal selettore della versione per contenuto con più versioni disponibili (esempio: azps-3.5.0)

Suggerimento

Nella maggior parte dei casi, gli articoli nello stesso docset hanno lo stesso frammento <product-service> nell'URL. Ad esempio:

  • Stesso docset:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/dotnet/framework/install
  • Docset diverso:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/visualstudio/whats-new

Per un collegamento segnalibro a un'intestazione nel file corrente, usare un simbolo hash seguito dalle parole dell'intestazione in lettere minuscole. Rimuovere i segni di punteggiatura dall'intestazione e sostituire gli spazi con trattini:

[Managed Disks](#managed-disks)

Per creare un collegamento a un'intestazione di segnalibro in un altro articolo, usare il collegamento relativo al file o al sito più un simbolo hash, seguito dalle parole dell'intestazione. Rimuovere i segni di punteggiatura dall'intestazione e sostituire gli spazi con trattini:

[Managed Disks](../../linux/overview.md#managed-disks)

È anche possibile copiare il collegamento segnalibro dall'URL. Per trovare l'URL, posizionare il puntatore del mouse sulla riga di intestazione in Microsoft Learn. Verrà visualizzata un'icona di collegamento:

Icona di collegamento nell'intestazione dell'articolo

Fare clic sull'icona di collegamento e quindi copiare il testo di ancoraggio del segnalibro dall'URL (ovvero, la parte dopo l'hash).

Nota

L'estensione Learn Markdown include anche strumenti per creare collegamenti.

L'aggiunta di collegamenti di ancoraggio esplicito che usano il tag HTML <a> non è necessaria né consigliata, tranne che nelle pagine hub e di destinazione. Usare invece i segnalibri generati automaticamente come descritto in Collegamenti segnalibro. In caso di pagine hub e di destinazione, dichiarare ancoraggi come descritto di seguito:

## <a id="anchortext" />Header text

or

## <a name="anchortext" />Header text

E usare i comandi seguenti per collegarsi all'ancoraggio:

To go to a section on the same page:
[text](#anchortext)

To go to a section on another page.
[text](filename.md#anchortext)

Nota

Il testo di ancoraggio deve sempre essere minuscolo e non deve contenere spazi.

I collegamenti XRef sono il modo consigliato per collegarsi alle API, perché semplificano la personalizzazione del testo del collegamento. Inoltre, vengono convalidati in fase di compilazione e, se l'URL del riferimento ALL'API dovesse cambiare, il collegamento funzionerebbe comunque. Per creare collegamenti a pagine di riferimento API generate automaticamente nel docset corrente o in altri docset, usare collegamenti XRef con l'ID univoco (UID) del tipo di membro.

Suggerimento

L'estensione helper link di riferimento API per VS Code semplifica l'inserimento di collegamenti Xref api .NET in file Markdown e XML.

Controllare se l'API a cui si vuole eseguire il collegamento viene pubblicata in Microsoft Learn digitando tutto o parte del nome completo nel browser API .NET o nella casella di ricerca UWP di Windows. Se non vengono visualizzati risultati, il tipo non è ancora disponibile in Microsoft Learn.

È possibile usare una delle sintassi seguenti:

  • Collegamenti automatici:

    <xref:UID>
<xref:UID?displayProperty=nameWithType>

    Per impostazione predefinita, il testo del collegamento mostra solo il nome del membro o del tipo. Il parametro di query displayProperty=nameWithType facoltativo produce testo di collegamento completo, ovvero spazio dei nomi.tipo per i tipi e tipo.membro per i membri dei tipi, inclusi i membri del tipo enumerazione.

  • Collegamenti in stile Markdown:

    [link text](xref:UID)

    Usare collegamenti in stile Markdown per i collegamenti XRef 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

  • [Classe String] (xref:System.String) viene visualizzato come classe String.

Il parametro di query displayProperty=fullName funziona allo stesso modo di displayProperty=nameWithType per le classi. In altre parole, il testo del collegamento diventa spaziodeinomi.nomeclasse. Tuttavia, per i membri, il testo del collegamento viene visualizzato come namespace.classname.membername, che potrebbe essere indesiderato.

Nota

Gli UID fanno distinzione tra maiuscole e minuscole. Ad esempio, <xref:System.Object> risolve correttamente, ma <xref:system.object> non.

Determinare l'UID

L'UID è in genere il nome completo della classe o del membro. Per determinare l'UID, fare clic con il pulsante destro del mouse sulla pagina di Microsoft Learn per un tipo o un membro, selezionare Visualizza origine e quindi copiare il valore del contenuto per ms.assetid.

ms.assetid nell'origine per la pagina Web

Codifica con simbolo di percentuale degli URL

I caratteri speciali nell'UID devono essere codificati in percentuale come indicato di seguito:

Carattere Codifica HTML
* *

Esempio di codifica:

  • System.Exception.#ctor viene codificato come System.Exception.%23ctor

Tipi generici

I tipi generici sono tipi come System.Collections.Generic.List<T>. Se si passa a questo tipo nel browser delle API .NET e se ne osserva l'URL, si nota che <T> nell'URL è scritto come -1, che in realtà rappresenta `1:

https://learn.microsoft.com/dotnet/api/system.collections.generic.list-1

Metodi

Per eseguire il collegamento a un metodo, è possibile collegarsi alla pagina del metodo generale aggiungendo un asterisco (*) dopo il nome del metodo o a un overload specifico. Usare, ad esempio, la pagina generale quando si vuole creare un collegamento al metodo <xref:System.Object.Equals*?displayProperty=nameWithType> senza tipi di parametro specifici. Ad esempio:

<xref:System.Object.Equals*?displayProperty=nameWithType> crea un collegamento a Object.Equals

Per creare un collegamento a un overload specifico, aggiungere le parentesi dopo il nome del metodo e includere il nome completo del tipo di ogni parametro. Non inserire alcuno spazio tra i nomi dei tipi. In caso contrario, il collegamento non funzionerà. Ad esempio:

<xref:System.Object.Equals(System.Object,System.Object)?displayProperty=nameWithType> crea un collegamento a Object.Equals(Object, Object)

Dato che i file di inclusione sono posizionati in un'altra directory, è necessario usare percorsi relativi più lunghi. Per impostare un collegamento a un articolo da un file di inclusione, usare questo formato:

[link text](../articles/folder/article-name.md)

Suggerimento

L'estensione Learn Authoring Pack per Visual Studio Code consente di inserire correttamente collegamenti e segnalibri relativi senza individuare i percorsi.

Un selettore è un componente di esplorazione visualizzato in un articolo della documentazione sotto forma di elenco a discesa. Quando il lettore seleziona un valore nell'elenco, il browser apre l'articolo selezionato. L'elenco del selettore in genere contiene collegamenti ad articoli strettamente correlati, ad esempio articoli sullo stesso argomento in linguaggi di programmazione diversi.

In presenza di selettori incorporati in un file di inclusione, per i collegamenti è necessario usare la struttura seguente:

> [AZURE.SELECTOR-LIST (Dropdown1 | Dropdown2 )]
- [(Text1 | Example1 )](../articles/folder/article-name1.md)
- [(Text1 | Example2 )](../articles/folder/article-name2.md)
- [(Text2 | Example3 )](../articles/folder/article-name3.md)
- [(Text2 | Example4 )](../articles/folder/article-name4.md)

È possibile usare i collegamenti in stile riferimento per rendere più leggibile il contenuto di origine. I collegamenti in stile riferimento sostituiscono la sintassi dei collegamenti inline con una sintassi semplificata che consente di spostare gli URL lunghi alla fine dell'articolo. Ecco un esempio tratto da Daring Fireball:

Testo inline:

I get 10 times more traffic from [Google][1] than from [Yahoo][2] or [MSN][3].

Collegamenti di riferimento alla fine dell'articolo:

<!--Reference links in article-->
[1]: http://google.com/
[2]: http://search.yahoo.com/
[3]: http://search.msn.com/

Assicurarsi di includere lo spazio dopo i due punti, prima del collegamento. Quando si imposta un collegamento ad altri articoli tecnici, se si dimentica di includere lo spazio il collegamento non funzionerà nell'articolo pubblicato.

Per impostare un collegamento a una pagina in un'altra area di proprietà Microsoft, ad esempio una pagina dei prezzi, la pagina del contratto di servizio o qualsiasi altro contenuto che non sia un articolo della documentazione, usare un URL assoluto omettendo le impostazioni locali. L'obiettivo è che i collegamenti funzionino in GitHub e nel sito di rendering:

[link text](https://azure.microsoft.com/pricing/details/virtual-machines/)

Per un'esperienza utente ottimale, è consigliabile evitare il più possibile i reindirizzamenti degli utenti a un altro sito. Basare quindi i collegamenti a siti di terze parti, a volte necessari, su queste informazioni:

  • Responsabilità:: impostare un collegamento a contenuti di terze parti quando le informazioni da condividere sono di proprietà di terzi. Ad esempio, non è compito di Microsoft comunicare agli utenti come usare gli strumenti per sviluppatori Android, è una responsabilità di Google. Se necessario, Microsoft può spiegare come usare gli strumenti per sviluppatori di Android con Azure, ma è Google ad avere la responsabilità di pubblicare contenuti con istruzioni per l'uso dei suoi strumenti.
  • Approvazione del PM: richiedere che Microsoft approvi il contenuto di terze parti. Con l'inserimento di questo tipo di collegamenti Microsoft fa una dichiarazione implicita in merito all'attendibilità del contenuto collegato e si impegna nei confronti dei clienti che seguono le istruzioni.
  • Revisioni di aggiornamento: assicurarsi che le informazioni di terze parti siano ancora aggiornate, corrette e pertinenti e che il collegamento non sia stato modificato.
  • Uscita dal sito: comunicare agli utenti che stanno passando a un altro sito. Se dal contesto non risulta chiaro, aggiungere una frase esplicativa. Ad esempio: "I prerequisiti includono Android Developer Tools, che è possibile scaricare nel sito di Android Studio".
  • Passaggi successivi: è consigliabile aggiungere un collegamento a, ad esempio, un blog MVP in una sezione "Passaggi successivi". Anche in questo caso, assicurarsi che gli utenti capiscano che stanno per passare a un altro sito.
  • Legale: microsoft è coperta legalmente in Collegamenti a siti di terze parti nel piè di pagina Condizioni per l'utilizzo in ogni pagina microsoft.com.