Ler em inglês

Partilhar via


Documentação de metadados para o Microsoft Learn

Usamos metadados no Microsoft Learn para relatórios de análise de conteúdo, descoberta de conteúdo por meio de pesquisa e aspetos de condução da experiência do site. Os metadados podem ser aplicados no artigo (na matéria frontal do YAML) ou globalmente no arquivo de docfx.json para o 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, há certos atributos de metadados necessários que você precisará incluir na matéria frontal do YAML do arquivo.

Aqui está um exemplo de metadados aplicados na matéria frontal do YAML de um artigo 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

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 de conteúdo por produto.

Metadados necessários

A tabela a seguir mostra os atributos de metadados necessários. Se você omitir qualquer um deles, provavelmente receberá um erro de validação durante a compilação.

Campo Value Porquê?
author O ID da conta do autor no GitHub. Identifica o autor pelo ID do GitHub caso haja dúvidas ou problemas com o conteúdo. Em alguns casos, a automação do GitHub pode notificar o autor da atividade envolvendo o arquivo.
description Um resumo do conteúdo. 75-300 caracteres. Usado na pesquisa do site. Às vezes usado em uma página de resultados do mecanismo de pesquisa para melhorar o SEO.
ms.author O alias Microsoft do autor, sem "@microsoft.com". Se você não for um funcionário da Microsoft, encontre um funcionário da Microsoft adequado para usar neste campo. Identifica o proprietário do artigo. O proprietário é responsável pelas decisões sobre o conteúdo do artigo, e pelo relatório e BI do artigo.
ms.date Uma data no formato MM/DD/AAAA. Exibido na página publicada para indicar a última vez que o artigo foi substancialmente editado ou garantido fresco. A data é inserida sem hora e é interpretada como 0:00 e no fuso horário UTC. A data exibida aos usuários é convertida em seu fuso horário.
ms.servicequer
ms.prod
O identificador de serviço ou produto. Use um ou outro, nunca os dois. Esse valor geralmente é definido globalmente no arquivo docfx.json . Usado para triagem de problemas e relatórios.

ms.prod e ms.service são distinções feitas que são anteriores ao Microsoft Learn, destinadas a distinguir entre produtos específicos executados em uma máquina (on-prem) e os serviços de nuvem (iniciais).
ms.topic Geralmente um dos seguintes valores:

article, conceptual, contributor-guide, , overview, quickstart, samplereference, tutorial.
Identifica o tipo de conteúdo para fins de relatório.
title O título da página. Este é o título da página exibido na guia do navegador. São os metadados mais importantes para SEO.

Os atributos diferenciam maiúsculas de minúsculas. Insira-os exatamente como 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 entre 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 -->

Metadados opcionais

Além dos metadados necessários, há muitos atributos de metadados opcionais que você pode adicionar. A tabela a seguir mostra alguns dos atributos de metadados opcionais.

Campo Value Porquê?
ms.custom Apenas para uso de redator ou equipe.

Comumente usado para rastrear documentos específicos ou conjuntos de conteúdo em ferramentas de telemetria. É um único valor de cadeia de caracteres, 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 analisa o conteúdo.
ms.subservice Um valor mais específico que pode ser usado para ms.service permitir relatórios mais específicos sobre o conteúdo de um serviço. Utilize ms.subservice apenas se também estiver a utilizar ms.serviceo . ms.subservice por si só não são metadados válidos. O autor deve associá-lo a um valor pai ms.service . Este atributo é uma maneira de detalhar ainda mais os relatórios para um determinado ms.service.
ms.technology Um valor mais específico que pode ser usado em conjunto para ms.prod permitir relatórios mais específicos sobre o conteúdo de um produto. Utilize ms.technology apenas se também estiver a utilizar ms.prodo . ms.technology por si só não são metadados válidos. O autor deve associá-lo a um valor pai ms.prod . Este atributo é uma maneira de detalhar ainda mais os relatórios para um determinado ms.prod.
ROBOTS NOINDEX, UNFOLLOW Use ROBOTS em sua seção de metadados para impedir que o processo de criação e publicação mostre conteúdo em páginas de pesquisa. Quando você quiser usar ROBOTS (e sim, está tudo em maiúsculas, mesmo que outras tags de metadados não estejam):
- Adicione ROBOTS: NOINDEX à sua seção de metadados.
- NOINDEX faz com que o ativo não apareça nos resultados da pesquisa.
- Use NOFOLLOW apenas quando você arquivar um conjunto de conteúdo inteiro.
no-loc Uma lista de palavras no artigo que nunca devem ser traduzidas (localizadas). Use esses metadados para evitar a "superlocalização".

Consulte também