Usar el texto preliminar de YAML

Información del texto preliminar de YAML

Frontmatter de YAML es una convención de autoría popularizada por Jekyll que ofrece una forma de añadir 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.ts.

• versions
• redirect_from
• title
• shortTitle
• intro
• permissions
• product
• layout
• children
• childGroups
• featuredLinks
• showMiniToc
• allowTitleToDifferFromFilename
• changelog
• defaultPlatform
• defaultTool
• learningTracks
• includeGuides
• journeyTracks
• 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, consulte 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.ts.
• Este valor de texto preliminar es necesario actualmente para todas las páginas.

•         `*` se usa para indicar todas las publicaciones 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 que se aplica a Free, Pro y Team y GitHub Enterprise Server versión 3.11 y posteriores:

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

Ejemplo que solo se aplica a GitHub Enterprise Server:

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 para Free, Pro y Team, y GitHub Enterprise Server versiones 3.1 y 3.2 solamente.

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 más información, consulta 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

•         **Obligatorio**.
  

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
categorías	27
temas del 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 mostrará 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, consulte mini índices de contenido generados 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.ts.
• Tipo: Boolean. El valor predeterminado es false.
• Opcional.

changelog

• Propósito: Representar una lista de elementos extraídos de GitHub Changelog en páginas de aterrizaje del producto (components/landing). La única excepción es educación, que procede de https://github.blog/category/community/education.
• Tipo: Object, propiedades: * label: debe estar presente y corresponde a las etiquetas usadas en el GitHub Changelog * prefix: cadena opcional que inicia cada título del registro de cambios que se debe omitir en el canal 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 el flujo de documentos.
• 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: invalide la selección inicial de herramientas para 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 las API de GitHub. Para más información sobre el selector de herramientas, consulte Uso de Markdown y Liquid en la documentación de GitHub. Si se omite esta frontmatter, el contenido específico de la herramienta que coincide con la interfaz de usuario web de GitHub se muestra de forma predeterminada. 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

journeyTracks

• Propósito: defina recorridos para las páginas de aterrizaje del recorrido.
• Tipo: Array de objetos con las siguientes propiedades: * id (obligatorio): identificador único del recorrido. El identificador solo debe ser único para los recorridos dentro de una única página de aterrizaje de recorrido. * title (obligatorio): mostrar el título del recorrido (admite variables Liquid) * description (opcional): descripción del recorrido (admite variables Liquid) * guides (obligatorio): matriz de objetos de guía que componen este recorrido. Cada objeto de guía tiene: * href (obligatorio): ruta de acceso al artículo * alternativeNextStep (opcional): texto personalizado para guiar a los usuarios a rutas de acceso alternativas en el recorrido. Admite variables Liquid y [AUTOTITLE].
• Solo se aplica cuando se usa con layout: journey-landing.
• Opcional.

Ejemplo:

journeyTracks:
  - id: 'getting_started'
    title: 'Getting started with GitHub Actions'
    description: 'Learn the basics of GitHub Actions.'
    guides:
      - href: '/actions/quickstart'
      - href: '/actions/learn-github-actions'
        alternativeNextStep: 'Want to skip ahead? See [AUTOTITLE](/actions/using-workflows).'
      - href: '/actions/using-workflows'
  - id: 'advanced'
    title: 'Advanced GitHub Actions'
    description: 'Dive deeper into advanced features.'
    guides:
      - href: '/actions/using-workflows/workflow-syntax-for-github-actions'
      - href: '/actions/deployment/deploying-with-github-actions'

type

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

communityRedirect

• Propósito: establezca un vínculo personalizado y un nombre 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 "En este artículo" generada automáticamente e incluye los vínculos a todos los H2 del artículo. Solo los encabezados H2 se incluyen en las mini tablas de contenido. 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 frontmatter showMiniToc, ajustado a false, para evitar que mini TOC aparezca para un artículo.

Las mini TOCs no aparecen en las páginas de inicio de producto, las páginas de inicio 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 esté en formato kebab-case del título que se usa en la metadata title del artículo. Esto puede resultar complicado cuando un título tiene signos de puntuación (como "planes de facturación de GitHub"). 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 de la tabla de contenidos para el sitio de Docs. Cada subdirectorio de producto, categoría y tema de mapa contiene un archivo index.md que proporciona una visión general del contenido y enlaces a cada artículo secundario. Cada index.md debe contener una propiedad de frontmatter children con una lista de vínculos relativos a las páginas secundarias del producto, categoría o tema de 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.