next

Translate

Publishing your site

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 diffuse 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 inclure /etc/nginx/mime.types; dans votre fichier nginx.conf . Consulter ce problème pour plus d'informations.

Hébergement dans un service :

Using Vercel

Deploying your Docusaurus project to Vercel will provide you with various benefits in the areas of performance and ease of use.

Most importantly, however, deploying a Docusaurus project only takes a couple of seconds:

  1. First, install their command-line interface:
npm i -g vercel
  1. Exécutez une seule commande dans le répertoire racine de votre projet :
vercel

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

Notez que la prise en charge de la structure de répertoire de Now est légèrement différente de la structure de répertoire par défaut d'un projet Docusaurus - Le répertoire docs doit être dans le répertoire website, suivant idéalement la structure des répertoires dans cet exemple. Vous devrez également spécifier une valeur customDocsPath dans siteConfig.js. Take a look at the now-examples repository for a Docusaurus project.

Utilisation de Github Pages

Docusaurus was designed to work well with one of the most popular hosting solutions for open source projects: GitHub Pages.

Déploiement sur les pages GitHub

  1. 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é).

  1. Vous devrez modifier le fichier website/siteConfig.js et ajouter les paramètres requis.
NomDescription
organizationNameL'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".
projectNameLe nom du dépôt GitHub pour votre projet. For example, the source code for Docusaurus is hosted at https://github.com/facebook/docusaurus, so our project name, in this case, would be "docusaurus".
urlL'URL de votre site web. Pour les projets hébergés sur des pages GitHub, ce sera "https://username.github.io"
baseUrlL'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.

  1. Maintenant vous devez spécifier l'utilisateur git comme variable d'environnement, et exécuter le script publish-gh-pages
NomDescription
GIT_USERThe username for a GitHub account that has to commit access to this repo. For your repositories, this will usually be your own GitHub username. 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.

Bash

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

Windows

cmd /C "set "GIT_USER=<GIT_USER>"&& set CURRENT_BRANCH=master && set USE_SSH=true && yarn run publish-gh-pages"

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

NomDescription
USE_SSHSi 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_BRANCHLa 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. All you need to do to automate the deployment of your website is to invoke the publish-gh-pages script whenever your docs get updated. 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.

  1. 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.
  2. Connectez-vous à GitHub sous GIT_USER.
  3. 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.
  4. 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.
  5. Créez une nouvelle variable d'environnement nommée GITHUB_TOKEN, en utilisant votre jeton d'accès nouvellement généré comme valeur.
  6. Créez un répertoire .circleci et créez un fichier config.yml dans ce répertoire.
  7. Copiez le texte ci-dessous dans .circleci/config.yml.
# If you only want the circle to run on direct commits to master, you can uncomment this out
# and uncomment the filters: *filter-only-master down below too
#
# aliases:
#  - &filter-only-master
#    branches:
#      only:
#        - master

version: 2
jobs:
  deploy-website:
    docker:
      # specify the version you desire here

      - 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 5.

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

  1. Allez sur https://github.com/settings/tokens et générez un nouveau jeton d'accès personnel
  2. En utilisant votre compte GitHub, ajoutez l'application Travis CI au dépôt que vous souhaitez activer.
  3. 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.
  4. 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).
  5. 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 .

Using Azure Pipelines

  1. Sign Up at Azure Pipelines if you haven't already.
  2. Create an organization and within the organization create a project and connect your repository from GitHub.
  3. Go to https://github.com/settings/tokens and generate a new personal access token with repository scope.
  4. In the project page (which looks like https://dev.azure.com/ORG_NAME/REPO_NAME/_build) create a new pipeline with the following text. Also, click on edit and add a new environment variable named GH_TOKEN with your newly generated token as its value, then GH_EMAIL (your email address) and GH_NAME (your GitHub username). Make sure to mark them as secret. Alternatively, you can also add a file named azure-pipelines.yml at yout repository root.
# azure-pipelines.yml
trigger:
  - master

pool:
  vmImage: 'ubuntu-latest'

steps:

  - checkout: self
    persistCredentials: true

  - task: NodeTool@0
    inputs:
      versionSpec: '10.x'
    displayName: 'Install Node.js'

  - script: |
      git config --global user.name "${GH_NAME}"
      git config --global user.email "${GH_EMAIL}"
      git checkout -b master
      echo "machine github.com login ${GH_NAME} password ${GH_TOKEN}" > ~/.netrc
      cd website
      yarn install
      GIT_USER="${GH_NAME}" CURRENT_BRANCH=master yarn run publish-gh-pages
    env:
      GH_NAME: $(GH_NAME)
      GH_EMAIL: $(GH_EMAIL)
      GH_TOKEN: $(GH_TOKEN)
    displayName: 'yarn install and build'

Using Drone

  1. Create a new ssh key that will be the deploy key for your project.
  2. Name your private and public keys to be specific and so that it does not overwrite your other ssh keys.
  3. Go to https://github.com/USERNAME/REPO/settings/keys and add a new deploy key by pasting in our public key you just generated.
  4. Open your Drone.io dashboard and login. The URL looks like https://cloud.drone.io/USERNAME/REPO.
  5. Click on the repository, click on activate repository, and add a secret called git_deploy_private_key with your private key value that you just generated.
  6. Create a .drone.yml on the root of your repository with below text.
# .drone.yml
kind: pipeline
type: docker
trigger:
  event:
    - tag
- name: Website
  image: node
  commands:
    - mkdir -p $HOME/.ssh
    - ssh-keyscan -t rsa github.com >> $HOME/.ssh/known_hosts
    - echo "$GITHUB_PRIVATE_KEY > $HOME/.ssh/id_rsa"
    - chmod 0600 $HOME/.ssh/id_rsa
    - cd website
    - npm i
    - npm run publish-gh-pages
  environment:
    USE_SSH: true
    GIT_USER: $DRONE_COMMIT_AUTHOR
    GITHUB_PRIVATE_KEY: git_deploy_private_key

Now, whenever you push a new tag to github, this trigger will start the drone ci job to publish your website.

Hosting on Vercel

Deploying your Docusaurus project to Vercel will provide you with various benefits in the areas of performance and ease of use.

To deploy your Docusaurus project with a Vercel for Git Integration, make sure it has been pushed to a Git repository.

Import the project into Vercel using the Import Flow. During the import, you will find all relevant options preconfigured for you; however, you can choose to change any of these options, a list of which can be found here.

After your project has been imported, all subsequent pushes to branches will generate Preview Deployments, and all changes made to the Production Branch (commonly "main") will result in a Production Deployment.

Hébergement sur Netlify

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

  1. Sélectionnez Nouveau site depuis Git

  2. Connectez-vous à votre fournisseur Git préféré.

  3. Sélectionnez la branche à déployer. La valeur par défaut est master

  4. 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)

  5. 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.

Hébergement sur Render

Render offers free static site hosting with fully managed SSL, custom domains, a global CDN and continuous auto deploy from your Git repo. Déployez votre application en quelques minutes en suivant ces étapes.

  1. Créez un nouveau Service Web sur Render, et donnez la permission à l'application GitHub de Render d'accéder à votre dépôt Docusaurus.

  2. Sélectionnez la branche à déployer. La valeur par défaut est master.

  3. Entrez les valeurs suivantes pendant la création.

ChampValeur
EnvironmentSite statique
Build Commandcd website; yarn install; yarn build
Publish Directorywebsite/build/<projectName>

projectName est la valeur que vous avez définie dans votre siteConfig.js.

javascript{7}
   const siteConfig = {
     // ...
     projectName: 'votre-nom-projet',
     // ...

C'est tout ! Votre application sera directement sur votre URL Render dès que la version sera terminée.

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.

NomDescription
GITHUB_HOSTLe 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.

← Creating your siteDocker →