Documentazione sui metadati per Microsoft Learn
I metadati vengono usati in Microsoft Learn per la creazione di report sull'analisi dei contenuti, l'individuabilità del contenuto tramite la ricerca e gli aspetti principali dell'esperienza del sito. I metadati possono essere applicati nell'articolo (nel front matter YAML) o a livello globale nel file di docfx.json per il repository.
Se si sta apportando una modifica a un articolo esistente, probabilmente non sarà necessario modificare i metadati. Tuttavia, se si aggiunge un nuovo articolo, sono necessari alcuni attributi di metadati necessari che è necessario includere nella prima questione yaML del file.
Ecco un esempio di metadati applicati nella materia iniziale YAML di un articolo markdown:
---
title: # the article title to show on the browser tab
description: # 115 - 145 character description to show in search results
author: {github-id} # the author's GitHub ID - will be auto-populated if set in settings.json
ms.author: {ms-alias} # the author's Microsoft alias (if applicable) - will be auto-populated if set in settings.json
ms.date: {@date} # the date - will be auto-populated when template is first applied
ms.topic: getting-started # the type of article
---
# Heading 1 <!-- the article title to show on the web page -->
Nota
Gli attributi dei metadati ms.prod e ms.technology vengono ritirati dalla piattaforma Learn. A partire da gennaio 2024, i valori in queste tassonomie verranno consolidati in ms.service e ms.subservice per la creazione di report sul contenuto per prodotto.
Nella tabella seguente vengono illustrati gli attributi di metadati necessari. Se si omette uno di questi, è probabile che venga visualizzato un errore di convalida durante la compilazione.
Campo | valore | Perché? |
---|---|---|
author |
ID dell'account GitHub dell'autore. | Identifica l'autore in base all'ID GitHub nel caso in cui si verifichino domande o problemi con il contenuto. In alcuni casi, l'automazione di GitHub potrebbe notificare all'autore dell'attività che coinvolge il file. |
description |
Riepilogo del contenuto. 75-300 caratteri. | Usato nella ricerca del sito. In alcuni casi viene usata in una pagina dei risultati del motore di ricerca per migliorare seO. |
ms.author |
Alias Microsoft dell'autore, senza "@microsoft.com". Se non si è un dipendente Microsoft, trovare un dipendente Microsoft adatto da usare in questo campo. | Identifica il proprietario dell'articolo. Il proprietario è responsabile delle decisioni sul contenuto dell'articolo e per la creazione di report e bi dell'articolo. |
ms.date |
data nel formato MM/gg/aaaa. | Visualizzato nella pagina pubblicata per indicare l'ultima volta che l'articolo è stato modificato o aggiornato in modo sostanziale. La data viene immessa senza ora e viene interpretata come 0:00 e nel fuso orario UTC. La data visualizzata agli utenti viene convertita nel fuso orario. |
ms.service o ms.prod |
Identificatore del servizio o del prodotto. Usare una o l'altra, mai entrambe. Questo valore viene spesso impostato a livello globale nel file docfx.json . | Usato per la valutazione dei problemi e la creazione di report. ms.prod e ms.service sono distinzioni che precedono Microsoft Learn, concepite per distinguere tra prodotti specifici eseguiti in un computer (locale) e i servizi cloud (iniziali). |
ms.topic |
In genere uno dei valori seguenti:article , conceptual , contributor-guide , overview quickstart , reference , sample . tutorial |
Identifica il tipo di contenuto a scopo di creazione di report. |
title |
Titolo della pagina. | Questo è il titolo della pagina visualizzato nella scheda del browser. Si tratta dei metadati più importanti per SEO. |
Gli attributi fanno distinzione tra maiuscole e minuscole. Immetterli esattamente come elencati e usare due punti e uno spazio tra gli attributi e il valore. Se un valore di attributo include due punti (:), un hash (#) o qualsiasi altro carattere speciale, è necessario racchiuderlo tra virgolette singole (') o doppie ("). Ad esempio:
---
title: 'Quickstart: How to use hashtags (#) to make a point on the internet'
---
# Heading 1 <!-- the article title to show on the web page -->
Oltre ai metadati necessari, è possibile aggiungere molti attributi di metadati facoltativi. Nella tabella seguente sono illustrati alcuni degli attributi di metadati facoltativi.
Campo | valore | Perché? |
---|---|---|
ms.custom |
Solo per writer o team. Comunemente usato per tenere traccia di documenti o set di contenuti specifici negli strumenti di telemetria. Si tratta di un singolo valore stringa e spetta allo strumento di utilizzo analizzarlo. Esempio: ms.custom: "experiment1, content_reporting, all_uwp_docs, CI_Id=101022" Limite di caratteri: la lunghezza massima del valore stringa è di 125 caratteri. |
ms.custom è un campo personalizzato che gli autori possono usare per tenere traccia di progetti speciali o di un subset di contenuto. |
ms.reviewer |
Alias Microsoft di una persona che esamina il contenuto. | |
ms.subservice |
Valore più specifico che può essere usato con ms.service per abilitare report più specifici sul contenuto di un servizio. Usare ms.subservice solo se si usa ms.service anche . |
ms.subservice per sé non sono metadati validi. L'autore deve associarlo a un valore padre ms.service . Questo attributo è un modo per eseguire il drill-down nella creazione di report per un determinato ms.service oggetto . |
ms.technology |
Valore più specifico che può essere usato insieme ms.prod a per abilitare report più specifici sul contenuto di un prodotto. Usare ms.technology solo se si usa ms.prod anche . |
ms.technology per sé non sono metadati validi. L'autore deve associarlo a un valore padre ms.prod . Questo attributo è un modo per eseguire il drill-down nella creazione di report per un determinato ms.prod oggetto . |
ROBOTS |
NOINDEX , UNFOLLOW |
Usare ROBOTS nella sezione dei metadati per impedire che il processo di compilazione e pubblicazione mostri il contenuto nelle pagine di ricerca. Quando si vuole usare ROBOTS (e sì, è tutto maiuscolo, anche se altri tag di metadati non sono):- Aggiungere ROBOTS: NOINDEX alla sezione dei metadati.- NOINDEX fa sì che l'asset non venga visualizzato nei risultati della ricerca.- Usare NOFOLLOW solo quando si archivia un intero set di contenuti. |
no-loc |
Elenco di parole nell'articolo che non devono mai essere tradotte (localizzate). | Usare questi metadati per impedire la "sovralocalizzazione". |