Publishing your site · Docusaurus

Vous devez avoir maintenant un site fonctionnant localement. Une fois que vous l'avez personnalisé à votre gout, c'est le temps de le publier. Docusaurus génère un site web HTML statique qui est prêt à être servi par votre serveur web préféré ou une solution d'hébergement en ligne.

Création des pages HTML statiques

Pour créer une version statique de votre site web, exécutez le script suivant dans le dossier website:

yarn run build # ou `npm run build`

Cela va générer un dossier build dans le dossier website contenant les fichiers .html de toute votre documentation et d'autres pages incluses dans pages.

Hébergement de pages HTML statiques

À ce point, vous pouvez prendre tous les fichiers dans le dossier website/build et les copier dans votre dossier html de votre serveur web préféré.

Par exemple, Apache et Nginx serve le contenu à partir de /var/www/html par défaut. Cela dit, choisir un serveur web ou un hébergeur est à l'extérieur du cadre de Docusaurus.

Lorsque vous diffusez le site à partir de votre propre serveur web, assurez-vous que le serveur web fournit bien les fichiers de composants avec les entêtes HTTP appropriés. Les fichiers CSS doivent être servis avec l'entête content-type de text/css. Dans le cas de Nginx, cela signifierait le paramètre include /etc/nginx/mime.types; dans votre fichier nginx.conf. Consulter ce problème pour plus d'informations.

Utilisation de ZEIT Now

Déployer votre projet Docusaurus sur ZEIT Now vous fournira différents avantages dans les domaines de la performance et de la facilité d'utilisation.

Mais surtout, le déploiement d'un projet Docusaurus ne prend que quelques secondes :

Tout d'abord, installez leur interface de ligne de commande:

npm i -g now

Exécutez une seule commande dans le répertoire racine de votre projet :

now

C'est tout. Vos docs seront automatiquement déployées.

Utilisation de Github Pages

Docusaurus a été conçu pour bien fonctionner avec l'une des solutions d'hébergement les plus populaires pour les projets open source : Pages GitHub.

Déploiement sur les pages GitHub

Docusaurus prend en charge le déploiement en tant que pages de projet ou pages d'utilisateur/organisation, votre dépôt de code n'a même pas besoin d'être public.

Même si votre dépôt est privé, tout ce qui est publié dans une branche gh-pages sera public.

Remarque : Lorsque vous déployez en tant qu'utilisateur/organisation des pages, le script de publication va déployer ces sites à la racine de la branche master du dépôt username.github.io. Dans ce cas, notez que vous aurez l'infra de Docusaurus, vos docs, etc. soit dans une autre branche de username.github.io repo (par exemple, appelée source), ou dans un autre dépôt séparé (par exemple dans le même que le code source documenté).

Vous devrez modifier le fichier website/siteConfig.js et ajouter les paramètres requis.

Nom	Description
`organizationName`	L'utilisateur ou l'organisation GitHub qui possède le dépôt. Si vous en êtes le propriétaire, c'est votre nom d'utilisateur GitHub. Dans le cas de Docusaurus, ce serait l'organisation GitHub "facebook".
`projectName`	Le nom du dépôt GitHub pour votre projet. Par exemple, le code source de Docusaurus est hébergé sur https://github.com/facebook/docusaurus, donc le nom de notre projet dans ce cas serait "docusaurus".
`url`	L'URL de votre site web. Pour les projets hébergés sur des pages GitHub, ce sera "https://username.github.io"
`baseUrl`	L'URL de base pour votre projet. Pour les projets hébergés sur des pages GitHub, il suit le format "/projectName/". Pour https://github.com/facebook/docusaurus, `baseUrl` est `/docusaurus/`.

const siteConfig = {
  ...
  url: 'https://__userName__.github.io', // L'URL de votre site web
  baseUrl: '/testProject/',
  projectName: 'testProject',
  organizationName: 'userName'
  ...
}

Dans le cas où vous souhaitez déployer le site en tant qu'utilisateur ou organisation, spécifiez le nom du projet comme <username>.github.io ou <orgname>.github.io. Par exemple, si votre nom d'utilisateur GitHub est "user42", alors cela sera user42.github.io, ou dans le cas d'un nom d'organisation de "org123", cela sera org123.github.io.

Remarque : Ne pas définir url et baseUrl de votre projet peuvent entraîner la création de chemins de fichiers incorrects qui peuvent casser des liens vers des chemins de ressources tels que les feuilles de style et les images.

Bien que nous recommandions de définir les projectName et organizationName dans siteConfig.js, vous pouvez également utiliser les variables d'environnement ORGANIZATION_NAME et PROJECT_NAME.

Maintenant vous devez spécifier l'utilisateur git comme variable d'environnement, et exécuter le script publish-gh-pages

Nom	Description
`GIT_USER`	Le nom d'utilisateur d'un compte GitHub qui a un accès à ce dépôt. Pour vos propres dépôts, ce sera habituellement votre propre nom d'utilisateur GitHub. Le `GIT_USER` spécifié doit avoir accès au dépôt spécifié dans la combinaison de `organisationName` et `projectName`.

Pour exécuter le script directement à partir de la ligne de commande, vous pouvez utiliser le suivant, en remplissant les valeurs de paramètre comme il se doit.

GIT_USER=<GIT_USER> \
  CURRENT_BRANCH=master \
  USE_SSH=true \
  yarn run publish-gh-pages # ou `npm run publish-gh-pages`

Il y a également deux paramètres optionnels définis comme variables d'environnement :

Nom	Description
`USE_SSH`	Si cela est défini à `true`, alors SSH est utilisé au lieu de HTTPS pour la connexion au dépôt GitHub. HTTPS est la valeur par défaut si cette variable n'est pas définie.
`CURRENT_BRANCH`	La branche qui contient les dernières modifications docs qui seront déployées. Habituellement, la branche sera `master`, mais peut être n'importe quelle branche (par défaut ou autrement) sauf pour `gh-pages`. Si rien n'est défini pour cette variable, la branche actuelle sera utilisée.

Si vous rencontrez des problèmes liés aux clés SSH, visitez la documentation d'authentification GitHub.

Vous devriez maintenant pouvoir charger votre site en visitant son URL GitHub Pages, ce qui pourrait être quelque chose en suivant les lignes de https://nom d'utilisateur.github.io/projectName, ou un domaine personnalisé si vous avez configuré cette page. Par exemple, l'URL GitHub de Docusaurus est https://facebook.github.io/Docusaurus car elle est desservie par la branche gh-pages du dépôt GitHub https://github.com/facebook/docurus. Cependant, il est également accessible via https://docusaurus.io/, via un fichier CNAME généré qui peut être configuré via cname de l'option siteConfig.

Nous encourageons vivement la lecture à travers la documentation GitHub Pages pour en savoir plus sur le fonctionnement de cette solution d'hébergement.

Vous pouvez exécuter la commande au-dessus de chaque fois que vous mettez à jour les documents et que vous souhaitez déployer les modifications de votre site. L'exécution manuelle du script peut être excellente pour les sites où la documentation change rarement et il n'est pas trop gênant de se souvenir de déployer manuellement des modifications.

Cependant, vous pouvez automatiser le processus de publication avec une intégration continue (CI).

Automatisation des déploiements en utilisant une intégration continue

Les services d'intégration continue (CI) sont généralement utilisés pour effectuer des tâches de routine lorsque de nouveaux commits sont vérifiés pour contrôler la source. Ces tâches peuvent être une combinaison de tests unitaires et de tests d'intégration, d'automatisation des builds, de publication des paquets vers NPM, et oui, de déploiement de modifications sur votre site Web. Tout ce que vous devez faire pour automatiser le déploiement de votre site est d'invoquer le script publish-gh-pages chaque fois que vos docs sont mis à jour. Dans la section suivante, nous allons couvrir la façon de faire juste cela en utilisant CircleCI, un fournisseur de service d'intégration continue populaire.

Utilisation de CircleCI 2.0

Si vous ne l'avez pas déjà fait, vous pouvez configurer CircleCI pour votre projet open source. Ensuite, afin d'activer le déploiement automatique de votre site et de la documentation via CircleCI, il suffit de configurer Circle pour exécuter le script publish-gh-pages dans la partie de l'étape de déploiement. Vous pouvez suivre les étapes ci-dessous pour obtenir cette configuration.

Assurez-vous que le compte GitHub qui sera défini comme GIT_USER a l'accès d'écriture au dépôt qui contient la documentation, en vérifiant Paramètres | Collaborateurs & équipes dans le dépôt.
Connectez-vous à GitHub sous GIT_USER.
Allez sur https://github.com/settings/tokens pour le GIT_USER et générez un nouveau jeton d'accès personnel, lui accordant le contrôle total des dépôts privés via le champ d'application repository. Stockez ce jeton dans un endroit sûr, assurez-vous de ne pas le partager avec n'importe qui. Ce jeton peut être utilisé pour authentifier les actions GitHub en votre nom à la place de votre mot de passe GitHub.
Ouvrez votre tableau de bord CircleCI et naviguez sur la page Paramètres de votre dépôt, puis sélectionnez "variables d'environnement". L'URL ressemble à https://circleci.com/gh/ORG/REPO/edit#env-vars, où "ORG/REPO" devrait être remplacé par votre propre organisation/référentiel GitHub.
Créez une nouvelle variable d'environnement nommée GITHUB_TOKEN, en utilisant votre jeton d'accès nouvellement généré comme valeur.
Créez un répertoire .circleci et créez un fichier config.yml dans ce répertoire.
Copiez le texte ci-dessous dans .circleci/config.yml.

# Si vous voulez seulement que le circle s'exécute sur des commits directs sur master, vous pouvez décommenter ceci
# et décommenter les filtres : *filter-only-master aussi ci-dessous
#
# aliases:
#  - &filter-only-master
#    branches:
#      only:
#        - master

version: 2
jobs:
  deploy-website:
    docker:
      # indiquez ici la version que vous désirez

      - image: circleci/node:8.11.1

    steps:

      - checkout
      - run:
          name: Deploying to GitHub Pages
          command: |
            git config --global user.email "<GITHUB_USERNAME>@users.noreply.github.com"
            git config --global user.name "<YOUR_NAME>"
            echo "machine github.com login <GITHUB_USERNAME> password $GITHUB_TOKEN" > ~/.netrc
            cd website && yarn install && GIT_USER=<GIT_USER> yarn run publish-gh-pages

workflows:
  version: 2
  build_and_deploy:
    jobs:

      - deploy-website:
#         filters: *filter-only-master

Assurez-vous de remplacer tous les <....> dans command: avec des valeurs appropriées. Pour <GIT_USER>, c'est un compte GitHub qui a accès à la documentation pour pousser dans votre dépôt GitHub. De nombreuses fois <GIT_USER> et <GITHUB_USERNAME> seront les mêmes.

NE PAS placer la valeur réelle de $GITHUB_TOKEN dans circle.yml. Nous avons déjà configuré cela en tant que variable d'environnement à l'étape 3.

Si vous voulez utiliser SSH pour votre connexion de dépôt GitHub, vous pouvez définir USE_SSH=true. La commande ci-dessus ressemblerait donc à : cd website && npm install && GIT_USER=<GIT_USER> USE_SSH=true npm run publish-gh-pages.

Contrairement au script publish-gh-pages lancé manuellement, lorsque le script s'exécute dans l'environnement Circle, la valeur de CURRENT_BRANCH est déjà définie comme une variable d'environnement dans CircleCI et sera récupérée automatiquement par le script.

Maintenant, chaque fois qu'un nouveau commit se trouve dans master, CircleCI exécutera votre suite de tests et, si tout passe, votre site sera déployé via le script publish-gh-pages .

Si vous préférez utiliser une clé de déploiement au lieu d'un jeton d'accès personnel, vous pouvez en commençant par les instructions de CircleCI pour ajouter une clé de déploiement en lecture/écriture.

Conseils & astuces

Lorsque vous déployez pour la première fois la branche gh-pages en utilisant CircleCI, vous pouvez remarquer que certains jobs déclenchés par des commits sur la branche gh-pages ne parviennent pas s'exécuter correctement à cause du manque de tests (cela peut également envoyer des notifications de builds échoués sur chat/slack).

Vous pouvez contourner cela :

Définition de la variable d'environnement CUSTOM_COMMIT_MESSAGE dans la commande publish-gh-pages avec le contenu de [skip ci]. Par exemple :

CUSTOM_COMMIT_MESSAGE="[skip ci]" \
  yarn run publish-gh-pages # ou `npm run publish-gh-pages`

Vous pouvez également travailler autour de cela en créant une configuration CircleCI basique avec le contenu suivant :

# CircleCI 2.0 Fichier de configuration
# Ce fichier de configuration empêchera l'exécution de tests sur la branche gh-pages.
version: 2
jobs:
  build:
    machine: true
    branches:
      ignore: gh-pages
    steps:
      - run: echo "Ignore les tests sur la branche gh-pages"

Enregistrez ce fichier sous le nom config.yml et placez-le dans un répertoire .circleci dans votre répertoire website/static.

Utilisation de Travis CI

Allez sur https://github.com/settings/tokens et générez un nouveau jeton d'accès personnel
En utilisant votre compte GitHub, ajoutez l'application Travis CI au dépôt que vous souhaitez activer.
Ouvrez votre tableau de bord Travis CI. L'URL ressemble à https://travis-ci.com/USERNAME/REPO, et accédez à la section Plus d'options > Paramètres > Variables d'environnement de votre dépôt.
Créez une nouvelle variable d'environnement nommée GH_TOKEN avec votre jeton nouvellement généré, puis GH_EMAIL (votre adresse e-mail) et GH_NAME (votre nom d'utilisateur GitHub).
Créez un .travis.yml à la racine de votre dépôt avec le texte ci-dessous.

# .travis.yml
language: node_js
node_js:
  - '8'
branches:
  only:
    - master
cache:
  yarn: true
script:
  - git config --global user.name "${GH_NAME}"
  - git config --global user.email "${GH_EMAIL}"
  - echo "machine github.com login ${GH_NAME} password ${GH_TOKEN}" > ~/.netrc
  - cd website && yarn install && GIT_USER="${GH_NAME}" yarn run publish-gh-pages

Maintenant, chaque fois qu'un nouveau commit se trouve dans master, Travis CI exécutera votre suite de tests et, si tout passe, votre site sera déployé via le script publish-gh-pages .

Hébergement sur ZEIT now

Avec ZEIT Now, vous pouvez déployer votre site et le connecter à GitHub ou GitLab pour recevoir automatiquement un nouveau déploiement à chaque fois que vous pousser un commit.

Hébergement sur Netlify

Étapes pour configurer votre site alimenté par Docusaurus sur Netlify.

Sélectionnez Nouveau site depuis Git
Connectez-vous à votre fournisseur Git préféré.
Sélectionnez la branche à déployer. La valeur par défaut est master
Configurez vos étapes de construction :

Pour votre commande de build, saisissez : cd website; npm install; npm run build;
Pour publier le répertoire : website/build/<projectName> (utilisez le projectName de votre siteConfig)

Cliquez sur Déployer site

Vous pouvez également configurer Netlify pour qu'il reconstruise sur chaque commit de votre dépôt, ou seulement sur les commits de la branche master.

Publication sur GitHub Enterprise

Les installations de GitHub entreprise devraient fonctionner de la même manière que github.com; vous n'avez qu'à identifier l'hôte GitHub Enterprise de l'organisation.

Nom	Description
`GITHUB_HOST`	Le nom d'hôte du serveur d'entreprise GitHub.

Modifiez votre siteConfig.js pour ajouter une propriété 'githubHost' qui représente le nom d'hôte GitHub Entreprise. Autrement, définissez une variable d'environnement GITHUB_HOST lors de l'exécution de la commande publication.