À 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 Free, Pro & Team 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 fichierpackage-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 ».