Sobre GitHub Docs a estrutura do site
O GitHub Docs site era originalmente um aplicativo Web Ruby on Rails. Algum tempo depois, ele foi convertido em um site estático impulsionado por Jekyll. Alguns anos depois disso, ele foi migrado para o Nanoc, outro gerador de site estático do Ruby.
Atualmente, é um servidor web Node.js dinâmico baseado em Express, usando middleware para oferecer suporte a redirecionamentos HTTP adequados, detecção do cabeçalho de idioma e geração dinâmica de conteúdo para dar suporte às várias versões da documentação de produtos do GitHub, como Free, Pro e Team, e 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 no diretório
dataestão disponíveis para os templates por meio da tag{% data %}. - Os arquivos Markdown podem conter uma matéria frontal.
- O comportamento do plug-in
redirect_fromdo Jekyll é suportado.
Configurando o ambiente local
Você pode clonar o GitHub Docs repositório e executar o aplicativo localmente em seu computador, após alguma configuração inicial.
Como instalar o Node.js
O GitHub Docs site é alimentado por 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" em nodejs.org. Para verificar qual versão do Node.js você precisa, consulte 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 nodenv documentação do para obter instruções sobre como alternar entre versões do Node.js.
Iniciando um servidor local 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 local, acesse localhost:4000 no navegador.
Quando estiver pronto para interromper o servidor local, digite CTRL+C na janela do terminal.
Observação
Normalmente, você só deve executar npm ci e npm run build cada vez que realiza um pull da última versão de uma ramificação.
- 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.
Se você quiser ler mais sobre depuração e solução de problemas do GitHub Docs aplicativo, consulte Solução de problemas no seu ambiente no repositório github/docs.
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.
Observação
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.ts.
Usando GitHub Codespaces
Como alternativa à execução GitHub Docs local, você pode usar GitHub Codespaces. GitHub Codespaces permite que você edite, visualize e teste suas alterações diretamente do navegador.
Para obter mais informações sobre como usar um codespace para trabalhar na GitHub documentação, consulte Como trabalhar no GitHub Docs em um codespace.