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".
- Escriba:
Object
. Las claves permitidas se asignan a los nombres de producto y se pueden encontrar en el objetoversions
enlib/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 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 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 elementoh1
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 comoGitHub.com
oGitHub 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
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 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.
- Escriba:
Array
. El valor predeterminado esfalse
. - 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.
- Escriba:
Array
. El valor predeterminado esfalse
. - 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.
- 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 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.
- 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.js
. - Escriba:
Boolean
. El valor predeterminado esfalse
. - 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 GitHubprefix
: 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
,windows
olinux
. - 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.
- 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 archivo LÉAME para más detalles.
includeGuides
- Propósito: representar una lista de artículos, que se pueden filtrar por
type
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
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 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. - 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 effectiveDate
valor de texto preliminar solo lo debe usar el personal 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 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.
Nota: El sitio solo conoce las rutas incluidas en el texto preliminar children
. Si existe un directorio o artículo, pero no se incluye en children
, 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 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.