Esta versión de GitHub Enterprise Server se discontinuará el 2026-03-17. No se realizarán lanzamientos de patch, ni siquiera para problemas de seguridad críticos. Para obtener rendimiento mejorado, seguridad mejorada y nuevas características, actualice a la versión más reciente de GitHub Enterprise Server. Para obtener ayuda con la actualización, póngase en contacto con el soporte técnico de GitHub Enterprise.

Usar el texto preliminar de YAML

Puede usar el encabezado de YAML para definir el control de versiones, agregar metadatos y controlar el diseño de los artículos.

En este artículo

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 ladocumentació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, vealib/frontmatter.ts.

versions

  • Propósito: indica lasversiones a las que se aplica una página. Para obtener más información sobre los diferentes tipos de control de versiones, consulteDocumentación de control de versiones.
  • Escriba:Object. Las claves permitidas se asignan a los nombres de producto y se pueden encontrar en el objetoversions enlib/frontmatter.ts.
  • Este valor de texto preliminar esnecesario actualmente para todas las páginas.
  • * se usa para indicar todas las versiones de la versión.
  • Debe estar presente para todos los archivosindex.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, veaVí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 solo con Free, Pro y Team y GitHub Enterprise Server versiones 3.1 y 3.2:

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, consultaConfiguración de redireccionamientos.

title

  • Propósito: establecer un título descriptivo para usarlo en la etiqueta<title> de la página representada y un elementoh1 en la parte superior de la página.
  • Tipo:String
  • Necesario.

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ículoLongitud máxima de caracteres
artículos31
categories27
temas de mapa30

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 detitle.
  • Tipo:String
  • Opcional.

permissions

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

product

  • Propósito: establece la llamada de producto para el artículo. Esta cadena se representará después de la instrucciónintro ypermissions.
  • 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 denominadocomponents/landing, el valor seríaproduct-landing.
  • Opcional. Si se omite, se usaDefaultLayout.

children

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

childGroups

  • Propósito: representar los elementos secundarios en grupos en la página principal. Para obtener más información, veaPágina principal.
  • Escriba:Array. El valor predeterminado esfalse.
  • Obligatorio en la página principalindex.md.
  • 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.
  • Escriba: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 propiedadfeaturedLinks.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, veaTDC generadas automáticamente.
  • Escriba:Boolean. El valor predeterminado estrue en los artículos yfalse en los temas de mapa y en las páginasindex.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 deOrganizations en lugar deOrgs. Las páginas con este texto preliminar establecido entrue no se marcarán en las pruebas ni se actualizarán mediantesrc/content-render/scripts/reconcile-filenames-with-ids.ts.
  • Escriba:Boolean. El valor predeterminado esfalse.
  • Opcional.

changelog

  • Propósito: representar una lista de elementos extraídos delRegistro de cambios de GitHub en las páginas de aterrizaje del producto (components/landing). La única excepción es Educación, que se extrae dehttps://github.blog/category/community/education.
  • Tipo:Object, propiedades:
    • label: debe estar presente y se corresponde a las etiquetas usadas en elRegistro 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 prefijoGitHub Actions: especificado, los títulos del registro de cambios comoGitHub Actions: Some Title Here se representarán comoSome 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,windowsolinux.
  • 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, consulteUso 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.
  • Escriba:String. Esto debe hacer referencia a los nombres de las pistas de aprendizaje definidos endata/learning-tracks/*.yml.
  • Opcionales

Nota:

La pista destacada se establece mediante una propiedad específica en el archivo YAML de pistas de aprendizaje. Vea el archivoLÉAME para más detalles.

includeGuides

  • Propósito: representar una lista de artículos, que se pueden filtrar portype ytopics. Solo se aplica cuando se usa conlayout: 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 destino 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 rutas de artículos que forman este recorrido
  • Solo se aplica cuando se usa conlayout: journey-landing.
  • Opcional.

Ejemplo:

journeyTracks:
  - id: 'getting_started'
    title: 'Getting started with GitHub Actions'
    description: 'Learn the basics of GitHub Actions.'
    guides:
      - '/actions/quickstart'
      - '/actions/learn-github-actions'
      - '/actions/using-workflows'
  - id: 'advanced'
    title: 'Advanced GitHub Actions'
    description: 'Dive deeper into advanced features.'
    guides:
      - '/actions/using-workflows/workflow-syntax-for-github-actions'
      - '/actions/deployment/deploying-with-github-actions'

type

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

topics

  • Propósito: indicar los temas tratados por el artículo. 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 elarchivo 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 laprueba de CI de los temas.
  • Tipo: matriz deString
  • 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ínculoAsk the GitHub community en el pie de página.
  • Escriba:Object. Las propiedades sonname yhref.
  • 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.

Nota:

El valor del texto preliminareffectiveDate es solo para uso del personal de GitHub.

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 losH2 del artículo. Solo los encabezadosH2 se incluyen en las mini TDC. Si un artículo usa encabezadosH3 oH4 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 unaTDC seccional.

Puede usar el valor de texto preliminarshowMiniToc, ajustado afalse, 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 formatokebab-case del título que se usa en el texto preliminartitle 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 preliminarallowTitleToDifferFromFilename.

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 archivoindex.md que proporciona información general sobre el contenido y los vínculos a cada artículo secundario. Cadaindex.md debe contener una propiedad de texto preliminarchildren 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 preliminarversions y el valor real se calculará en tiempo de ejecución en función de las versiones de los artículos secundarios.

Nota:

El sitio solo conoce las rutas incluidas en el texto preliminarchildren. Si existe un directorio o artículo, perono se incluye enchildren, su ruta volverá a 404.

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 dechildren, como todas laspáginas de índice, pero también debe especificar la propiedad de texto preliminarchildGroups que se resaltará en el área de contenido principal.

childGroups es una matriz de asignaciones que contiene un elementoname para el grupo, un elementoicon opcional para el grupo y una matriz dechildren. El elementochildren de la matriz debe estar presente en la propiedad de texto preliminarchildren.

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

Para crear una página de guías de producto (por ejemplo, lapá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 alayout: product-guides
  • Incluya las pistas de aprendizaje enlearningTracks. Opcional.
  • Defina los artículos que se van a incluir conincludeGuides. Opcional.

Si usa pistas de aprendizaje, se deben definir endata/learning-tracks/*.yml. Si usaincludeGuides, asegúrese de que cada uno de los artículos de esta lista tienetopics ytype en su sección de texto preliminar.