Documentação dos metadados do Microsoft Learn
Usamos metadados no Microsoft Learn para relatórios de análise de conteúdo, detectabilidade do conteúdo por meio de pesquisa e para controlar aspectos impulsionadores da experiência no site. Os metadados podem ser aplicados no artigo (no front matter do YAML) ou globalmente no arquivo docfx.json do repositório.
Se você estiver fazendo uma edição em um artigo existente, provavelmente não precisará alterar nenhum metadado. No entanto, se você estiver adicionando um novo artigo, precisará incluir certos atributos de metadados obrigatórios no front matter do YAML do arquivo.
Veja um exemplo de metadados aplicados no front matter do YAML de um artigo de 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 -->
Observação
Os atributos de metadados ms.prod e ms.technology estão sendo retirados da plataforma Learn. A partir de janeiro de 2024, os valores nessas taxonomias serão consolidados em ms.service e ms.subservice para relatórios sobre conteúdo por produto.
A tabela a seguir mostra os atributos de metadados obrigatórios. Se você omitir qualquer um deles, provavelmente receberá um erro de validação durante o build.
Campo | Valor | Por quê? |
---|---|---|
author |
A ID da conta do GitHub do autor. | Identifica o autor pela ID do GitHub caso haja perguntas ou problemas com o conteúdo. Em alguns casos, a automação do GitHub pode notificar o autor da atividade que envolve o arquivo. |
description |
Um resumo do conteúdo, de 75 a 300 caracteres. | Usado na pesquisa de sites. Às vezes usado em páginas de resultados de mecanismos de pesquisa para melhorar a SEO. |
ms.author |
O alias da Microsoft do autor, sem "@microsoft.com". Se você não for um funcionário da Microsoft, encontre um que seja adequado e cujo alias possa ser usado nesse campo. | Identifica o proprietário do artigo. O proprietário é responsável pelas decisões sobre o conteúdo do artigo, pelo relatório e pelo BI do artigo. |
ms.date |
Uma data no formato MM/DD/AAAA. | Exibido na página publicada para indicar a última vez em que o artigo foi substancialmente editado ou atualizado. A data é inserida sem as horas, é interpretada como 0:00 e está no fuso horário UTC. A data exibida aos usuários é convertida no fuso horário em que eles estão. |
ms.service ou ms.prod |
O identificador do serviço ou do produto. Use um ou outro, nunca ambos. Esse valor muitas vezes é definido globalmente no arquivo docfx.json. | Usado para triagem e relatório de issues. ms.prod e ms.service são distinções feitas que antecedem o Microsoft Learn, destinadas a distinguir entre produtos específicos executados em um computador (on-prem) e os serviços de nuvem (iniciais). |
ms.topic |
Geralmente um dos seguintes valores:article , conceptual , contributor-guide , overview , quickstart , reference , sample , tutorial . |
Identifica o tipo de conteúdo para fins de relatório. |
title |
O título de página. | Este é o título de página exibido na guia do browser. São os metadados mais importantes para a SEO. |
Os atributos diferenciam maiúsculas de minúsculas. Insira-os exatamente conforme listado e use dois pontos e um espaço entre os atributos e o valor. Se um valor de atributo incluir dois-pontos (:), um hash (#) ou qualquer outro caractere especial, você deverá colocá-lo em aspas simples (') ou duplas ("). Por exemplo:
---
title: 'Quickstart: How to use hashtags (#) to make a point on the internet'
---
# Heading 1 <!-- the article title to show on the web page -->
Além dos metadados obrigatórios, há muitos atributos de metadados opcionais que você pode adicionar. A tabela a seguir mostra alguns dos atributos de metadados opcionais.
Campo | Valor | Por quê? |
---|---|---|
ms.custom |
Somente para uso do escritor ou da equipe. Normalmente usado para acompanhar documentos ou conjuntos de conteúdo específicos em ferramentas de telemetria. É um valor de cadeia de caracteres único, e cabe à ferramenta de consumo analisá-lo. Exemplo: ms.custom: "experiment1, content_reporting, all_uwp_docs, CI_Id=101022" Limite de caracteres: o comprimento máximo do valor da cadeia de caracteres é de 125 caracteres. |
ms.custom é um campo personalizado que os escritores podem usar para acompanhar projetos especiais ou um subconjunto de conteúdo. |
ms.reviewer |
O alias da Microsoft de uma pessoa que revisa o conteúdo. | |
ms.subservice |
Um valor mais específico que pode ser usado com ms.service para habilitar relatórios mais específicos sobre o conteúdo de um serviço. Somente use ms.subservice se você também estiver usando ms.service . |
ms.subservice por si só não é um metadado válido. O autor deve associá-lo a um valor ms.service pai. Esse atributo é uma forma de fazer drill down de modo ainda mais detalhado de um determinado ms.service nos relatórios. |
ms.technology |
Um valor mais específico que pode ser usado em conjunto com ms.prod para permitir relatórios mais específicos sobre o conteúdo de um produto. Somente use ms.technology se você também estiver usando ms.prod . |
ms.technology por si só não é um metadado válido. O autor deve associá-lo a um valor ms.prod pai. Esse atributo é uma forma de fazer drill down de modo ainda mais detalhado de um determinado ms.prod nos relatórios. |
ROBOTS |
NOINDEX , UNFOLLOW |
Use ROBOTS na seção de metadados para impedir que o processo de build e publicação mostre o conteúdo nas páginas de pesquisa. Quando você desejar usar ROBOTS (e sim, ele deve ser escrito com todas as letras maiúsculas, embora outras tags de metadados não devam ser escritas da mesma forma):– Adicione ROBOTS: NOINDEX à seção de metadados.- NOINDEX faz com que o ativo não apareça nos resultados da busca.– Use NOFOLLOW somente quando você arquivar um conjunto inteiro de conteúdo. |
no-loc |
Uma lista de palavras no artigo que nunca devem ser traduzidas (localizadas). | Use esse metadado para evitar a tradução de palavras que devem ficar no linguagem original. |