Usar el texto preliminar de YAML

Información del texto preliminar de YAML

Texto preliminar de YAML es una convención de creación popularizada por Jekyll que proporciona una manera de agregar metadatos a las páginas. Es un bloque de contenido de clave-valor que reside en la parte superior de cada archivo de Markdown dentro de GitHub Docs. Para más información, consulte la documentación de texto preliminar de YAML.

Valores de texto preliminar de YAML

Los siguientes valores de texto preliminar tienen significados y requisitos especiales para GitHub Docs. También hay un esquema que usa el conjunto de pruebas para validar el texto preliminar de todas las páginas. Para obtener más información, vea lib/frontmatter.js.

• versions
• redirect_from
• title
• shortTitle
• intro
• permissions
• product
• layout
• children
• childGroups
• featuredLinks
• showMiniToc
• allowTitleToDifferFromFilename
• changelog
• defaultPlatform
• defaultTool
• learningTracks
• includeGuides
• type
• topics
• communityRedirect
• effectiveDate

versions

• Propósito: indica las versiones a las que se aplica una página. Para obtener más información sobre los diferentes tipos de control de versiones, vea "Documentación de control de versiones".
• Tipo: Object. Las claves permitidas se asignan a los nombres de producto y se pueden encontrar en el objeto versions en lib/frontmatter.js.
• Este valor de texto preliminar es necesario actualmente para todas las páginas.
• * se usa para indicar todas las versiones de la versión.
• Debe estar presente para todos los archivos index.md, pero el valor real se calcula en tiempo de ejecución en función de los elementos secundarios.

El sitio de documentos usa este valor de texto preliminar para generar «vínculos permanentes» para cada versión de un artículo. Para obtener más información, vea Vínculos permanentes.

Ejemplo aplicable a GitHub.com y versiones recientes de GitHub Enterprise Server:

title: About your personal dashboard
versions:
  fpt: '*'
  ghes: '>=3.11'

Ejemplo aplicable a todas las versiones compatibles de GitHub Enterprise Server, pero no a GitHub.com:

title: Downloading your license
versions:
  ghes: '*'

También puede crear una versión de una página para un intervalo de versiones. Esto versionaría la página solo con las versiones 3.1 y 3.2 de GitHub.com y GitHub Enterprise Server:

versions:
  fpt: '*'
  ghes: '>=3.1 <3.3'

redirect_from

• Propósito: enumera las direcciones URL que deben redirigirse a esta página.
• Tipo: Array
• Opcionales

Ejemplo:

title: Getting started with GitHub Desktop
redirect_from:
  - /articles/first-launch
  - /articles/error-github-enterprise-version-is-too-old
  - /articles/getting-started-with-github-for-windows

Para obtener más información, vea «Configuración de redireccionamientos».

title

• Propósito: establecer un título descriptivo para usarlo en la etiqueta <title> de la página representada y un elemento h1 en la parte superior de la página.
• Tipo: String
• Opcional. Si se omite, la página <title> seguirá establecida, aunque con un valor genérico como GitHub.com o GitHub Enterprise.

shortTitle

• Propósito: variante abreviada del título de página para usarlo en rutas y elementos de navegación.
• Tipo: String
• Opcional. Si se omite, se usará title.

Tipo de artículo	Longitud máxima de caracteres
artículos	31
categories	27
temas de mapa	30

Ejemplo:

title: Contributing to projects with GitHub Desktop
shortTitle: Contributing to projects

intro

• Propósito: establecer la introducción de la página. Esta cadena se representará después de title.
• Tipo: String
• Opcional.

permissions

• Propósito: establecer la declaración de permisos para el artículo. Esta cadena se representará después de intro.
• Tipo: String
• Opcional.

product

• Propósito: establece la llamada de producto para el artículo. Esta cadena se representará después de la instrucción intro y permissions.
• Tipo: String
• Opcional.

layout

• Propósito: representar el diseño de página adecuado.
• Tipo: String que coincide con el nombre del diseño. Para un diseño denominado components/landing, el valor sería product-landing.
• Opcional. Si se omite, se usa DefaultLayout.

children

• Propósito: enumerar los vínculos relativos que pertenecen al tema producto/categoría/mapa. Para obtener más información, vea Páginas de índice.
• Tipo: Array. El valor predeterminado es false.
• Obligatorio en las páginas index.md.

childGroups

• Propósito: representar los elementos secundarios en grupos en la página principal. Para obtener más información, vea Página principal.
• Tipo: Array. El valor predeterminado es false.
• Obligatorio en la página principal index.md.

featuredLinks

• Propósito: representar los títulos e introducciones de los artículos vinculados en las páginas de aterrizaje del producto y la página principal.
• Tipo: Object.
• Opcional.

La lista de vínculos populares son los que se muestran en la página de aterrizaje bajo el título "Populares". Como alternativa, puede personalizar el título "Populares" si establece la propiedad featuredLinks.popularHeading en una cadena nueva.

Ejemplo:

featuredLinks:
  gettingStarted:
    - /path/to/page
  startHere:
    - /guides/example
  popular:
    - /path/to/popular/article1
    - /path/to/popular/article2
  popularHeading: An alternate heading to Popular

showMiniToc

• Propósito: indicar si un artículo debe mostrar una mini tabla de contenidos (TDC) encima del resto del contenido. Para obtener más información, vea TDC generadas automáticamente.
• Tipo: Boolean. El valor predeterminado es true en los artículos y false en los temas de mapa y en las páginas index.md.
• Opcional.

allowTitleToDifferFromFilename

• Propósito: indica si se permite que una página tenga un título que difiere de su nombre de archivo. Por ejemplo, content/rest/reference/orgs.md tiene un título de Organizations en lugar de Orgs. Las páginas con este texto preliminar establecido en true no se marcarán en las pruebas ni se actualizarán mediante src/content-render/scripts/reconcile-filenames-with-ids.js.
• Tipo: Boolean. El valor predeterminado es false.
• Opcional.

changelog

• Propósito: representar una lista de elementos extraídos del Registro de cambios de GitHub en las páginas de aterrizaje del producto (components/landing). La única excepción es Educación, que se extrae de https://github.blog/category/community/education.
• Tipo: Object, propiedades:
  • label: debe estar presente y se corresponde a las etiquetas usadas en el Registro de cambios de GitHub
  • prefix: cadena opcional que inicia cada título del registro de cambios que se debe omitir en la fuente de documentación. Por ejemplo, con el prefijo GitHub Actions: especificado, los títulos del registro de cambios como GitHub Actions: Some Title Here se representarán como Some Title Here en la fuente de documentación.
• Opcional.

defaultPlatform

• Propósito: invalidar la selección de la plataforma inicial para una página. Si se omite este texto preliminar, se muestra de forma predeterminada el contenido específico de la plataforma que coincide con el sistema operativo del lector. Este comportamiento se puede cambiar para páginas individuales, para las que una selección manual es más razonable. Por ejemplo, la mayoría de los ejecutores GitHub Actions usan Linux y su sistema operativo es independiente del sistema operativo del lector.
• Tipo: String, uno de: mac, windowso linux.
• Opcional.

Ejemplo:

defaultPlatform: linux

defaultTool

• Propósito: invalidar la selección de la herramienta inicial de una página, donde la herramienta hace referencia a la aplicación que usa el lector para trabajar con GitHub (como la interfaz de usuario web de GitHub.com, la CLI de GitHub o GitHub Desktop), o bien las API de GitHub. Para más información sobre el selector de herramientas, vea "Uso de Markdown y Liquid en la documentación de GitHub". Si se omite este texto preliminar, se muestra de forma predeterminada el contenido específico de la herramienta que coincide con la interfaz de usuario web de GitHub. Si un usuario ha indicado una preferencia de herramienta (al hacer clic en una pestaña de herramientas), se aplicará la preferencia del usuario en lugar del valor predeterminado.
• Tipo: String, uno de: webui, cli, desktop, curl, codespaces, vscode, importer_cli, graphql, powershell, bash, javascript.
• Opcional.

defaultTool: cli

learningTracks

• Propósito: representar una lista de pistas de aprendizaje en la página de aterrizaje secundaria de un producto.
• Tipo: String. Esto debe hacer referencia a los nombres de las pistas de aprendizaje definidos en data/learning-tracks/*.yml.
• Opcionales

includeGuides

• Propósito: representar una lista de artículos, que se pueden filtrar por type y topics. Solo se aplica cuando se usa con layout: product-guides.
• Tipo: Array
• Opcional.

Ejemplo:

includeGuides:
  - /actions/guides/about-continuous-integration
  - /actions/guides/setting-up-continuous-integration-using-workflow-templates
  - /actions/guides/building-and-testing-nodejs
  - /actions/guides/building-and-testing-powershell

type

• Propósito: indicar el tipo de artículo.
• Tipo: String, uno de overview, quick_start, tutorial, how_to, reference, rai.
• Opcional.

topics

• Propósito: indicar los temas tratados por el artículo. Los temas se usan para filtrar guías en algunas páginas de aterrizaje. Por ejemplo, las guías de la parte inferior de "Guías para GitHub Actions" se pueden filtrar por temas y los temas se enumeran en la introducción de la guía. Consulte los modelos de contenido para obtener más detalles sobre cómo agregar temas. Una lista completa de los temas existentes se encuentra en el archivo de temas permitidos. Si los temas de texto preliminar del artículo y la lista de temas permitidos no están sincronizados, se producirá un error en la prueba de CI de los temas.
• Tipo: matriz de String
• Opcional: para cada artículo se prefieren los temas, pero es posible que haya casos en los que los artículos existentes todavía no tengan temas, o bien que la incorporación de un tema a un artículo nuevo no agregue ningún valor.

communityRedirect

• Propósito: establecer un vínculo personalizado y un nombre de vínculo para el vínculo Ask the GitHub community en el pie de página.
• Tipo: Object. Las propiedades son name y href.
• Opcional.

effectiveDate

• Propósito: establezca una fecha efectiva para los artículos de Términos del servicio, a fin de que los equipos de ingeniería puedan volver a pedir automáticamente a los usuarios que confirmen los términos.
• Tipo: string AÑO-MES-DÍA, por ejemplo, 2021-10-04 es el 4 de octubre de 2021
• Opcional.

Escape de comillas simples

Si ve dos comillas simples seguidas ('') en el texto preliminar de YAML donde debería ver una ('), esta es la manera preferida de YAML de evitar una sola comilla.

Como alternativa, puede cambiar las comillas simples que rodean el campo de texto preliminar por comillas dobles y dejar las comillas simples internas sin escape.

Mini TDC generadas automáticamente

Cada artículo muestra una mini tabla de contenidos (TDC), que es una sección generada automáticamente "En este artículo" que incluye vínculos a todos los H2 del artículo. Solo los encabezados H2 se incluyen en las mini TDC. Si un artículo usa encabezados H3 o H4 para dividir información de una manera que solo determinadas secciones son relevantes para una tarea determinada, puede ayudar a las personas a navegar al contenido más relevante para su caso mediante una TDC seccional.

Puede usar el valor de texto preliminar showMiniToc, ajustado a false, para evitar que la mini TDC aparezca para un artículo.

Las mini TDC no aparecen en las páginas de aterrizaje del producto, las páginas de aterrizaje de categoría ni en las páginas de temas de mapa.

No agregue secciones "En este artículo" codificadas de forma rígida en el origen de Markdown o, de lo contrario, la página mostrará mini TDC duplicadas.

Nombres de archivo

Al agregar un artículo nuevo, asegúrese de que el nombre de archivo es una versión con formato kebab-case del título que se usa en el texto preliminar title del artículo. Esto puede resultar complicado cuando un título tiene signos de puntuación. Una prueba marcará las discrepancias entre el título y el nombre de archivo. A fin de invalidar este requisito para un artículo determinado, puede agregar el texto preliminar allowTitleToDifferFromFilename.

Páginas de índice

Las páginas de índice son los archivos TDC del sitio de documentos. Cada subdirectorio de tema de producto, categoría y mapa tiene un archivo index.md que proporciona información general sobre el contenido y los vínculos a cada artículo secundario. Cada index.md debe contener una propiedad de texto preliminar children con una lista de vínculos relativos a las páginas secundarias del tema de producto, categoría o mapa. Las páginas de índice requieren una propiedad de texto preliminar versions y el valor real se calculará en tiempo de ejecución en función de las versiones de los artículos secundarios.

Página principal

La página principal es el archivo de tabla de contenido principal del sitio de documentación. La página principal debe tener una lista completa de children, como todas las páginas de índice, pero también debe especificar la propiedad de texto preliminar childGroups que se resaltará en el área de contenido principal.

childGroups es una matriz de asignaciones que contiene un elemento name para el grupo, un elemento icon opcional para el grupo y una matriz de children. El elemento children de la matriz debe estar presente en la propiedad de texto preliminar children.

Creación de páginas de guías de productos

Para crear una página de guías de producto (por ejemplo, la página Guía GitHub Actions), cree o modifique un archivo Markdown existente con estos valores de texto preliminar específicos:

• Use la plantilla de página de guías de producto haciendo referencia a layout: product-guides
• Incluya las pistas de aprendizaje en learningTracks. Opcional.
• Defina los artículos que se van a incluir con includeGuides. Opcional.

Si usa pistas de aprendizaje, se deben definir en data/learning-tracks/*.yml. Si usa includeGuides, asegúrese de que cada uno de los artículos de esta lista tiene topics y type en su sección de texto preliminar.