Création d’un environnement local

À propos de la structure du site GitHub Docs

Le site GitHub Docs était à l’origine une application web Ruby on Rails. Quelque temps plus tard, il a été converti en un site statique basé sur Jekyll. Quelques années après cela, il a été migré vers Nanoc, qui est un autre générateur de site statique Ruby.

Aujourd’hui, c’est un serveur web Node.js dynamique basé sur Express, qui utilise un intergiciel pour prendre en charge les redirections HTTP appropriées, et la détection d’en-tête de langue et la génération de contenu dynamique pour prendre en charge les différentes versions de la documentation produit de GitHub, comme GitHub.com et GitHub Enterprise Server.

Les outils de ce site ont changé au fil des ans, mais bon nombre des conventions de création éprouvées du site Jekyll d’origine ont été conservées.

Le contenu est écrit dans des fichiers Markdown, qui se trouvent dans le répertoire content.
Les fichiers du répertoire data sont disponibles pour les modèles via l’étiquette {% data %}.
Les fichiers Markdown peuvent contenir un bloc Front Matter.
Le comportement du plug-in Jekyll redirect_from est pris en charge.

Configuration de votre environnement local

Vous pouvez cloner le dépôt GitHub Docs et exécuter l’application localement sur votre ordinateur, après une installation initiale.

Installation de Node.js

Le site GitHub Docs est basé sur Node.js. Il s’exécute sur les environnements macOS, Windows et Linux.

Pour exécuter le site, vous avez besoin de Node.js. Pour installer Node.js, téléchargez le programme d’installation « LTS » à partir de nodejs.org. Pour vérifier la version de Node dont vous avez besoin, vous pouvez regarder le fichier package.json dans le dépôt GitHub Docs. La version de Node figure dans le champ engine, comme dans l’exemple suivant, qui indique que vous pouvez utiliser la version majeure 16 ou 18 de Node.

"engines": {
    "node": "^16 || ^18"
}

Si vous utilisez nodenv, consultez la documentation de nodenv pour obtenir des instructions sur le passage à d’autres versions de Node.js.

Démarrage d’un serveur GitHub Docs local

Une fois que vous avez installé Node.js (qui inclut le gestionnaire de package npm bien connu), ouvrez votre terminal et exécutez les commandes suivantes.

git clone https://github.com/github/docs
cd docs
npm ci
npm start

Vous devriez maintenant disposer d’un serveur en cours d’exécution. Pour accéder à votre environnement d’aperçu local, accédez à localhost:4000 dans votre navigateur.

Quand vous êtes prêt à arrêter votre serveur local, tapez Ctrl+C dans la fenêtre de votre terminal.

Remarque : En général, vous devez exécuter npm ci et npm run build seulement chaque fois que vous extrayez la dernière version d’une branche.

npm ci effectue une installation propre des dépendances, sans mettre à jour le fichier package-lock.json.
npm run build crée les ressources statiques, comme des fichiers JavaScript et CSS.

Si vous voulez en savoir plus sur le débogage et la résolution des problèmes de l’application GitHub Docs, consultez « Résolution des problèmes de votre environnement » dans le référentiel github/docs.

Utilisation des raccourcis de navigateur

Le répertoire src/bookmarklets du dépôt GitHub Docs contient des raccourcis de navigateur qui peuvent vous aider à consulter la documentation GitHub. Pour plus d’informations, consultez le contenu de README du répertoire.

Activation d’autres langues

Par défaut, le serveur local ne s’exécute pas avec toutes les langues prises en charge activées. Si vous devez exécuter un serveur local avec une langue particulière, vous pouvez modifier temporairement le script start dans package.json et mettre à jour la variable ENABLED_LANGUAGES.

Par exemple, pour activer le japonais et le portugais en plus de l’anglais, vous pouvez modifier package.json et définir ENABLED_LANGUAGES='en,ja,pt' dans le script start. Redémarrez ensuite le serveur pour que la modification prenne effet.

Remarque : Avant de commiter vos modifications, vous devez rétablir le fichier package.json à son état d’origine.

Les codes de langue pris en charge sont définis dans src/languages/lib/languages.js.

Utilisation de GitHub Codespaces

Au lieu d’exécuter GitHub Docs localement, vous pouvez aussi utiliser GitHub Codespaces. GitHub Codespaces vous permet de modifier, prévisualiser et tester vos modifications directement depuis votre navigateur.

Pour plus d’informations sur l’utilisation d’un codespace pour travailler sur la documentation GitHub, consultez « Travailler sur GitHub Docs dans un codespace ».