Leer en inglés

Compartir a través de


Metadatos para la documentación de Microsoft Learn

Utilizamos metadatos en Microsoft Learn para la creación de informes de análisis de contenido, la detectabilidad del contenido mediante la búsqueda y el impulso de aspectos de la experiencia del sitio. Los metadatos se pueden aplicar en el artículo (en la parte frontal de YAML) o globalmente en el archivo docfx.js del repositorio.

Si va a editar un artículo existente, probablemente no tendrá que cambiar ningún metadato. Sin embargo, si va a agregar un nuevo artículo, hay ciertos atributos de metadatos necesarios que deberá incluir en la parte frontal de YAML del archivo.

Este es un ejemplo de metadatos aplicados en la materia principal de YAML de un artículo 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 -->

Nota

Los atributos de metadatos ms.prod y ms.technology se retiran de la plataforma Learn. A partir de enero de 2024, los valores de estas taxonomías se consolidarán en ms.service y ms.subservice para informar sobre el contenido por producto.

Metadatos necesarios

En la tabla siguiente se muestran los atributos de metadatos necesarios. Si omite cualquiera de estos, es probable que reciba un error de validación durante la compilación.

Campo Valor ¿Por qué?
author El id. de la cuenta de GitHub del autor. Identifica al autor mediante el id. de GitHub en caso de que haya preguntas sobre el contenido o problemas con él. En algunos casos, la automatización de GitHub podría notificar al autor de la actividad relacionada con el archivo.
description Resumen del contenido. Entre 75 y 300 caracteres. Se usa en la búsqueda del sitio. A veces se usa en una página de resultados del motor de búsqueda para mejorar la optimización del motor de búsqueda.
ms.author Alias de Microsoft del autor, sin "@microsoft.com". Si no es un empleado de Microsoft, busque un empleado de Microsoft adecuado para usarlo en este campo. Identifica el propietario del artículo. El propietario es responsable de las decisiones sobre el contenido del artículo, así como de los informes y la inteligencia empresarial sobre el artículo.
ms.date fecha con formato MM/DD/AAAA. Se muestra en la página publicada para indicar la última vez que el artículo se editó de manera sustancial o se garantizó que está actualizado. La fecha se indica sin hora y se interpreta como 0:00 y en la zona horaria UTC. La fecha que se muestra a los usuarios se convierte a su zona horaria.
ms.service o bien
ms.prod
Identificador del servicio o producto. Utilice uno u otro, pero nunca ambos. Este valor se suele establecer globalmente en el archivo docfx.json. Se usa para la creación de informes y la evaluación de problemas.

ms.prod y ms.service son distinciones que preceden a Microsoft Learn, diseñadas para distinguir entre los productos específicos que se ejecutan en un equipo (local) y los servicios en la nube (anteriores).
ms.topic Normalmente tienen uno de los siguientes valores:

article, conceptual, contributor-guide, overview, quickstart, reference, sample, tutorial.
Identifica el tipo de contenido con fines informativos.
title Título de la página. Este es el título de página que se muestra en la pestaña del explorador. Son los metadatos más importantes para el SEO.

Los atributos distinguen mayúsculas de minúsculas. Escríbalos exactamente como se muestra y use dos puntos y un espacio entre los atributos y el valor. Si un valor de atributo incluye dos puntos (:), una almohadilla (#) o cualquier otro carácter especial, debe incluir comillas simples (') o dobles ("). Por ejemplo:

---
title: 'Quickstart: How to use hashtags (#) to make a point on the internet'
---
# Heading 1 <!-- the article title to show on the web page -->

Metadatos opcionales

Además de los metadatos necesarios, hay muchos atributos de metadatos opcionales que puede agregar. En la tabla siguiente se muestran algunos de los atributos de metadatos opcionales.

Campo Valor ¿Por qué?
ms.custom Solo para uso por parte del escritor o el equipo.

Se usa normalmente para realizar el seguimiento de documentos o conjuntos de contenido específicos en las herramientas de telemetría. Es un valor de cadena único y es la herramienta de consumo la que se encarga de analizarlo. Ejemplo: ms.custom: "experiment1, content_reporting, all_uwp_docs, CI_Id=101022"

Límite de caracteres: la longitud máxima del valor de cadena es de 125 caracteres.
ms.custom es un campo personalizado que los escritores pueden usar para realizar un seguimiento de proyectos especiales o un subconjunto de contenido.
ms.reviewer El alias de Microsoft de una persona que revisa el contenido.
ms.subservice Un valor más específico que se puede utilizar con ms.service para generar informes más específicos sobre el contenido de un servicio. Solo use ms.subservice si también usa ms.service. ms.subservice por sí solo no conforma metadatos válidos. El autor debe asociarlo a un valor ms.service primario. Este atributo es una manera de explorar en profundidad los informes de un elemento ms.service determinado.
ms.technology Un valor más específico que se puede utilizar con ms.prod para generar informes más específicos sobre el contenido de un producto. Solo use ms.technology si también usa ms.prod. ms.technology por sí solo no conforma metadatos válidos. El autor debe asociarlo a un valor ms.prod primario. Este atributo es una manera de explorar en profundidad los informes de un elemento ms.prod determinado.
ROBOTS NOINDEX, UNFOLLOW Use ROBOTS en la sección de metadatos para evitar que el proceso de compilación y publicación muestre contenido en las páginas de búsqueda. Cuando quiera usar ROBOTS (y sí, se escribe todo en mayúsculas, aunque otras etiquetas de metadatos no):
- Agregue ROBOTS: NOINDEX a la sección de metadatos.
- NOINDEX hace que el recurso no se muestre en los resultados de la búsqueda.
- Solo use NOFOLLOW cuando archive un conjunto de contenido completo.
no-loc Lista de palabras del artículo que nunca deben traducirse (localizarse). Use estos metadatos para evitar la "sobrelocalización".

Consulte también