Usar front matter YAML - GitHub Enterprise Server 3.19 Docs

Sobre o front matter YAML

O front matter YAML é uma convenção de criação popularizada pelo Jekyll que fornece uma forma de adicionar metadados a páginas. Ele é um bloco de conteúdo chave-valor que se encontra no início de cada arquivo Markdown em GitHub Docs. Para obter mais informações, consulte a documentação do front matter YAML.

Valores do front matter YAML

Os valores front matter a seguir têm significados e requisitos especiais para GitHub Docs. Há também um esquema usado pelo conjunto de testes para validar o frontmatter de cada página. Para obter mais informações, consulte 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`

Finalidade: indicar as versões às quais uma página se aplica. Para obter mais informações sobre os diferentes tipos de controle de versão, consulte Documentação de controle de versão.
Digite: Object. As chaves permitidas são mapeadas para nomes de produtos e podem ser encontradas no objeto versions em lib/frontmatter.ts.
Atualmente, esse valor de frontmatter é obrigatório para todas as páginas.
O * é usado para indicar todas as versões da versão.
Deve estar presente para todos os arquivos index.md, mas o valor real é calculado em runtime com base nos filhos.

Esse valor de front matter é usado pelo site de documentos para gerar "links permanentes" para cada versão de um artigo. Para obter mais informações, confira Links permanentes.

Exemplo que se aplica às versões Free, Pro, & Team e GitHub Enterprise Server 3.11 e posteriores:

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

Exemplo que se aplica apenas ao GitHub Enterprise Server:

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

Você também pode controlar uma versão de uma página para um intervalo de versões. Isso criaria uma versão da página somente para as versões Free, Pro, & Team e GitHub Enterprise Server 3.1 e 3.2:

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

`redirect_from`

Finalidade: listar as URLs que devem ser redirecionadas para esta página.
Digite: Array
Opcional

Exemplo:

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 saber mais, confira Configurar os redirecionamentos.

`title`

Finalidade: definir um título amigável para uso na marca da <title> da página renderizada e um elemento h1 na parte superior da página.
Digite: String
```
          **Obrigatório**.
```

`shortTitle`

Finalidade: uma variante abreviada do título da página para uso em barras de trilha e elementos de navegação.
Digite: String
Opcional. Se omitido, title será usado.

Tipo de artigo	Comprimento máximo de caracteres
artigos	31
Categorias	27
tópicos do mapa	30

Exemplo:

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

`intro`

Finalidade: definir a introdução na página. Essa cadeia de caracteres será renderizada após a title.
Digite: String
Opcional.

`permissions`

Finalidade: definir a declaração de permissão no artigo. Essa cadeia de caracteres será renderizada após a intro.
Digite: String
Opcional.

`product`

Finalidade: definir o texto explicativo do produto no artigo. Essa cadeia de caracteres será renderizada após as instruções intro e permissions.
Digite: String
Opcional.

`layout`

Finalidade: renderizar o layout da página adequado.
Tipo: String que corresponde ao nome do layout. Para um layout chamado components/landing, o valor será product-landing.
Opcional. Se omitido, DefaultLayout será usado.

`children`

Finalidade: listar os links relativos que pertencem ao tópico de produto/categoria/mapa. Confira as páginas de índice para obter mais informações.
Digite: Array. O padrão é false.
Obrigatório em páginas index.md.

`childGroups`

Finalidade: renderizar os filhos em grupos na home page. Para obter mais informações, confira a página inicial.
Digite: Array. O padrão é false.
Exigir na home page index.md.

`featuredLinks`

Finalidade: renderizar os títulos e as introduções dos artigos vinculados nas páginas de aterrissagem do produto e na home page.
Digite: Object.
Opcional.

A lista de links populares são os links exibidos na página de aterrissagem sob o título "Populares". Como alternativa, você pode personalizar o título "Populares" definindo a propriedade featuredLinks.popularHeading como uma nova cadeia de caracteres.

Exemplo:

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

`showMiniToc`

Finalidade: indicar se um artigo deve mostrar um pequeno sumário acima do restante do conteúdo. Para obter mais informações, confira “Pequenos sumários gerados automaticamente”.
Digite: Boolean. O padrão é true em artigos e false em tópicos de mapa e páginas index.md.
Opcional.

`allowTitleToDifferFromFilename`

Finalidade: indicar se uma página tem permissão para ter um título diferente do nome de arquivo. Por exemplo, content/rest/reference/orgs.md tem o título Organizations em vez de Orgs. As páginas com esse frontmatter definido como true não serão sinalizadas em testes nem atualizadas por src/content-render/scripts/reconcile-filenames-with-ids.ts.
Digite: Boolean. O padrão é false.
Opcional.

`changelog`

Finalidade: renderizar uma lista de itens extraídos do Log de mudanças do GitHub nas páginas de aterrissagem do produto (components/landing). A única exceção é Educação, que é extraída de https://github.blog/category/community/education.

Tipo: Object, propriedades:

          `label` -- precisa estar presente e corresponde aos rótulos usados no [Log de Alterações do GitHub](https://github.blog/changelog/)

          `prefix` -- cadeia de caracteres opcional que inicia cada título do log de alterações que deve ser omitido no feed da documentação. Por exemplo, com o prefixo `GitHub Actions: ` especificado, os títulos do log de mudanças, como `GitHub Actions: Some Title Here`, serão renderizados como `Some Title Here` no feed da documentação.

Opcional.

`defaultPlatform`

Finalidade: substituir a seleção inicial de plataforma em uma página. Se esse frontmatter for omitido, o conteúdo específico da plataforma correspondente ao sistema operacional do leitor será mostrado por padrão. Esse comportamento pode ser alterado em páginas individuais, para as quais uma seleção manual é mais razoável. Por exemplo, a maioria dos executores de GitHub Actions usa o Linux, e o sistema operacional deles é independente do sistema operacional do leitor.
Tipo: String, um destes: mac, windows ou linux.
Opcional.

Exemplo:

defaultPlatform: linux

`defaultTool`

Finalidade: substituir a seleção de ferramentas inicial em uma página, em que a ferramenta se refere ao aplicativo que o leitor está usando para trabalhar com o GitHub (como a interface do usuário da Web do GitHub.com, a CLI do GitHub ou o GitHub Desktop) ou as APIs do GitHub. Para saber mais sobre o seletor da ferramenta, consulte Como usar Markdown e Liquid no GitHub Docs. Se esse front matter for omitido, o conteúdo específico da ferramenta correspondente à interface do usuário da Web do GitHub será mostrada por padrão. Se um usuário tiver indicado uma preferência de ferramenta (clicando em uma guia de ferramenta), a preferência do usuário será aplicada, em vez do valor padrão.
Tipo: String, um destes: webui, cli, desktop, curl, codespaces, vscode, importer_cli, graphql, powershell, bash, javascript.
Opcional.

defaultTool: cli

`learningTracks`

Finalidade: renderizar uma lista de faixas de aprendizagem na página de subaterrissagem de um produto.
Digite: String. Isso referenciará os nomes das faixas de aprendizagem definidos em data/learning-tracks/*.yml.
Opcional

Observação

A faixa em destaque é definida por uma propriedade específica no YAML das faixas de aprendizagem. Confira o LEIAME para obter detalhes.

`includeGuides`

Finalidade: renderizar uma lista de artigos, que pode ser filtrada por type e topics. Aplicável somente quando usado com layout: product-guides.
Digite: Array
Opcional.

Exemplo:

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`

Objetivo: definir jornadas para páginas de destino de jornadas.
Tipo: Array de objetos com as seguintes propriedades: * id (obrigatório): identificador exclusivo para o percurso. A ID só precisa ser exclusiva para jornadas dentro de uma mesma página de destino de jornada. * title (obrigatório): exibir o título do percurso (dá suporte a variáveis Liquid) * description (opcional): descrição do percurso (dá suporte a variáveis Liquid)
- ```
          `guides` (obrigatório): matriz de caminhos de artigo que compõem essa jornada
```
Aplicável somente quando usado com layout: journey-landing.
Opcional.

Exemplo:

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`

Finalidade: indicar o tipo de artigo.
Tipo: String. Um destes: overview, quick_start, tutorial, how_to, reference, rai.
Opcional.

`topics`

Finalidade: indicar os tópicos abordados pelo artigo. Veja os modelos de conteúdo para obter mais detalhes sobre como adicionar tópicos. Uma lista completa dos tópicos existentes está localizada no arquivo de tópicos permitidos. Se os tópicos no frontmatter de artigos e a lista de tópicos de permissão ficarem fora de sincronia, o teste de CI de tópicos falhará.
Tipo: Matriz de Strings
Opcional: os tópicos são preferenciais para cada artigo, mas, pode haver casos em que os artigos existentes ainda não tenham tópicos ou uma adição de um tópico a um novo artigo pode não agregar valor.

`communityRedirect`

Finalidade: definir um link personalizado e um nome de link para o link Ask the GitHub community no rodapé.
Digite: Object. As propriedades são name e href.
Opcional.

`effectiveDate`

Finalidade: defina uma data de início de vigência para os artigos dos Termos de Serviço para que as equipes de engenharia possam solicitar novamente, de modo automático, aos usuários que confirmem os termos
Tipo: string YEAR-MONTH-DAY, por exemplo, 2021-10-04, é 4 de outubro de 2021
Opcional.

Observação

O valor do front matter effectiveDate é destinado a uso apenas pela equipe do GitHub.

Como fazer escape de aspas simples

Se você vir duas aspas simples em uma linha ('') no front matter YAML em que você espera ver uma ('), esta será a maneira preferencial do YAML de fazer o escape das aspas simples.

Como alternativa, você pode alterar as aspas simples ao redor do campo do frontmatter para aspas duplas e manter as aspas simples internas sem escape.

Mini TOCs gerados automaticamente

Cada artigo exibe um pequeno sumário, que é uma seção "Neste artigo" gerada automaticamente que inclui links para todos os H2s no artigo. Somente cabeçalhos H2 são incluídos nos pequenos sumários. Se um artigo usar cabeçalhos H3 ou H4 para dividir informações de forma que apenas determinadas seções sejam relevantes para uma tarefa específica, você poderá ajudar as pessoas a navegar até o conteúdo mais relevante para elas usando um sumário por seções.

Você pode usar o valor de frontmatter showMiniToc, definido como false, para impedir que o pequeno sumário apareça em um artigo.

Os mini TOCs não são exibidos em páginas de aterrissagem do produto, em páginas de aterrissagem da categoria ou em páginas de tópico de mapa.

Não adicione seções codificadas "Neste artigo" na origem Markdown, caso contrário, a página exibirá pequenos sumários duplicados.

Nomes de arquivos

Ao adicionar um novo artigo, verifique se o nome do arquivo é uma versão com Kebab case do título usado no frontmatter title do artigo. Isso pode ficar complicado quando um título tem sinais de pontuação (como "Planos de Cobrança do GitHub"). Um teste sinalizará as discrepâncias entre o título e o nome de arquivo. Para substituir esse requisito em um artigo específico, adicione o frontmatter allowTitleToDifferFromFilename.

Páginas de índice

As páginas de índice são os arquivos de sumário do site de documentação. Cada subdiretório de produto, categoria e tópico de mapas tem um arquivo index.md que fornece uma visão geral do conteúdo e links para cada artigo secundário. Cada index.md precisa conter uma propriedade de frontmatter children com uma lista de links relativos para as páginas filho do produto, da categoria ou do tópico de mapa. As páginas de índice requerem uma propriedade de frontmattter versions e o valor real será calculado em um runtime com base nas versões dos artigos secundários.

Observação

O site só conhece os caminhos incluídos no frontmatter children. Se um diretório ou um artigo existir, mas não estiver incluído em children, o caminho retornará um 404.

Homepage

A home page é o arquivo principal do Sumário do site da documentação. Ela precisa ter uma lista completa de children, como todas as páginas de índice, mas também precisa especificar a propriedade do frontmatter childGroups que será realçada na área de conteúdo principal.

          `childGroups` é uma matriz de mapeamentos que contém um `name` para o grupo, um `icon` opcional para o grupo e uma matriz de `children`. Os `children` na matriz precisam estar presentes na propriedade do frontmatter `children`.

Como criar páginas de guias de produto

Para criar uma página de guias de produtos (por exemplo, página do Guia do GitHub Actions), crie ou modifique um arquivo Markdown existente com estes valores de front matter específicos:

Use o modelo de página de guias de produtos usando layout: product-guides como referência.
Inclua as faixas de aprendizagem em learningTracks. Opcional.
Defina os artigos a serem incluídos com includeGuides. Opcional.

Se você estiver usando faixas de aprendizagem, elas precisarão ser definidas em data/learning-tracks/*.yml. Se estiver usando includeGuides, verifique se cada um dos artigos desta lista tem topics e type no frontmatter.