Sobre a estrutura do site do GitHub Docs
Originalmente, o site do GitHub Docs era um aplicativo Web do Ruby on Rails. Algum tempo depois, ele foi convertido em um site estático do Jekyll. Alguns anos depois disso, ele foi migrado para o Nanoc, outro gerador de site estático do Ruby.
Hoje ele é um servidor Web Node.js dinâmico do Express, usando um middleware para dar suporte a redirecionamentos HTTP adequados, detecção de cabeçalho de linguagem e geração dinâmica de conteúdo a fim de dar suporte às diversas variantes de documentação do produto do GitHub, como o Free, Pro e Team e o GitHub Enterprise Server.
As ferramentas deste site mudaram ao longo dos anos, porém, muitas das convenções de criação testadas e aprovadas do site original em Jekyll foram preservadas.
- O conteúdo é escrito em arquivos Markdown, que se encontram no diretório
content.
- Os arquivos do diretório
dataestão disponíveis para os modelos por meio da tag{% data %}. - Os arquivos Markdown podem conter uma matéria frontal.
- Há suporte para o comportamento do plug-in
redirect_fromdo Jekyll.
Configurando o ambiente local
Você pode clonar o repositório GitHub Docs e executar o aplicativo localmente no computador, após uma configuração inicial.
Como instalar o Node.js
O site do GitHub Docs foi criado com a plataforma Node.js. Ele é executado em ambientes macOS, Windows e Linux.
Para executar o site, você precisará ter o Node.js. Para instalar o Node.js, baixe o instalador "LTS" de nodejs.org. Para verificar a versão do Node de que você precisa, confira o arquivo package.json no repositório GitHub Docs. A versão do Node está listada no campo engine, semelhante ao exemplo a seguir, que indica que você pode usar a versão principal do Node 16 ou a versão principal do Node 18.
"engines": {
"node": "^16 || ^18"
}
Se estiver usando o nodenv, confira a documentação do nodenv para obter instruções sobre como alternar entre versões do Node.js.
Como iniciar um servidor local do GitHub Docs
Depois de instalar o Node.js (que inclui o popular gerenciador de pacotes npm), abra o terminal e execute os comandos a seguir.
git clone https://github.com/github/docs
cd docs
npm ci
npm start
Você já deverá ter um servidor em execução. Para acessar o ambiente de visualização local, acesse localhost:4000 no navegador.
Quando estiver pronto para interromper o servidor local, digite CTRL+C na janela do terminal.
Note
Normalmente, você só deve executar npm ci e npm run build cada vez que efetua pull da última versão de um branch.
- O
npm cifaz uma instalação limpa de dependências, sem atualizar o arquivopackage-lock.json. - O
npm run buildcria ativos estáticos, como arquivos JavaScript e CSS.
Caso deseje ler mais sobre depuração e solução de problemas do aplicativo GitHub Docs, confira Solução de problemas no seu ambiente no repositório github/docs.
Como usar atalhos do navegador
O diretório src/bookmarklets no repositório GitHub Docs contém atalhos de navegador que podem ajudar na revisão da documentação do GitHub. Para obter mais informações, confira o README do diretório.
Como habilitar idiomas diferentes
Por padrão, o servidor local não é executado com todos os idiomas com suporte habilitados. Caso você precise executar um servidor local com um idioma específico, edite temporariamente o script start em package.json e atualize a variável ENABLED_LANGUAGES.
Por exemplo, para habilitar o japonês e o português além do inglês, edite package.json e defina ENABLED_LANGUAGES='en,ja,pt' no script start. Em seguida, reinicie o servidor para que a alteração entre em vigor.
Note
Antes de fazer commit das alterações, você deve reverter o arquivo package.json para o estado original.
Os códigos de idioma com suporte são definidos em src/languages/lib/languages.js.
Como usar o GitHub Codespaces
Como alternativa à execução do GitHub Docs localmente, você pode usar o GitHub Codespaces. O GitHub Codespaces permite que você edite, visualize e teste suas alterações diretamente no navegador.
Para obter mais informações sobre como usar um codespace para trabalhar na documentação do GitHub, confira Como trabalhar no GitHub Docs em um codespace.