next

Translate

Publication de votre 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 diffusé 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 des autres pages incluses dans pages.

Hébergement de pages HTML statiques

À ce point, vous pouvez prendre tout 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 en-têtes HTTP appropriés. Les fichiers CSS peuvent être servi avec type de contenu de l'en-tête de text/css. Dans le cas de Nginx, cela signifierait le paramètre inclure /etc/nginx/mime.types; dans votre fichier nginx.conf . Voir ce problème pour plus d'informations.

Hébergement dans un service:

Utiliser 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 :

  1. Tout d'abord, installez leur interface de ligne de commande:
npm i -g now
  1. 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 was designed to work really well with one of the most popular hosting solutions for open source projects: GitHub Pages.

Deploying to GitHub Pages

  1. Docusaurus supports deploying as project pages or user/organization pages, your code repository does not even need to be public.

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

Note: When you deploy as user/organization page, the publish script will deploy these sites to the root of the master branch of the username.github.io repo. In this case, note that you will want to have the Docusaurus infra, your docs, etc. either in another branch of the username.github.io repo (e.g., maybe call it source), or in another, separate repo (e.g. in the same as the documented source code).

  1. You will need to modify the file website/siteConfig.js and add the required parameters.
NomDescription
organizationNameL'utilisateur ou l'organisation GitHub qui possède le dépôt. If you are the owner, then it is your GitHub username. In the case of Docusaurus, that would be the "facebook" GitHub organization.
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".
urlYour website's URL. For projects hosted on GitHub pages, this will be "https://username.github.io"
baseUrlBase URL for your project. For projects hosted on GitHub pages, it follows the format "/projectName/". For https://github.com/facebook/docusaurus, baseUrl is /docusaurus/.
 
const siteConfig = {
  ...
  url: 'https://__userName__.github.io', // Your website URL
  baseUrl: '/testProject/',
  projectName: 'testProject',
  organizationName: 'userName'
  ...
}

In case you want to deploy as a user or organization site, specify the project name as <username>.github.io or <orgname>.github.io. E.g. If your GitHub username is "user42" then user42.github.io, or in the case of an organization name of "org123", it will be org123.github.io.

Note: Not setting the url and baseUrl of your project might result in incorrect file paths generated which can cause broken links to assets paths like stylesheets and images.

While we recommend setting the projectName and organizationName in siteConfig.js, you can also use environment variables ORGANIZATION_NAME and PROJECT_NAME.

  1. Now you have to specify the git user as an environment variable, and run the script publish-gh-pages
NomDescription
GIT_USERLe 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 référentiel spécifié dans la combinaison de organisation 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 # or `npm 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 repo 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 elle pourrait être une 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. For example, Docusaurus' own GitHub Pages URL is https://facebook.github.io/Docusaurus because it is served from the gh-pages branch of the https://github.com/facebook/docusaurus GitHub repository. However, it can also be accessed via https://docusaurus.io/, via a generated CNAME file which can be configured via the cname siteConfig option.

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éployements en utilisant l'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. In the following section, we'll be covering how to do just that using CircleCI, a popular continuous integration service provider.

Using 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 le cadre 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 référentiel qui contient la documentation, en vérifiant Paramètres | Collaborateurs & équipes dans le référentiel.
  2. Connectez-vous à GitHub sous GIT_USER.
  3. Go to https://github.com/settings/tokens for the GIT_USER and generate a new personal access token, granting it full control of private repositories through the repository access scope. 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. Open your CircleCI dashboard, and navigate to the Settings page for your repository, then select "Environment variables". 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 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 la commande: avec des valeurs appropriées. Pour <GIT_USER>, c'est un compte GitHub qui a accès à la documentation pour push dans votre dépôt GitHub. De nombreuses fois <GIT_USER> et <GITHUB_USERNAME> seront les mêmes.

DO NOT place 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.

Tips & Tricks

When initially deploying to a gh-pages branch using CircleCI, you may notice that some jobs triggered by commits to the gh-pages branch fail to run successfully due to a lack of tests (This can also result in chat/slack build failure notifications).

Vous pouvez contourner cela facilement:

  • Setting the environment variable CUSTOM_COMMIT_MESSAGE flag to the publish-gh-pages command with the contents of [skip ci]. e.g.
CUSTOM_COMMIT_MESSAGE="[skip ci]" \
  yarn run publish-gh-pages # or `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 Config File
# This config file will prevent tests from being run on the gh-pages branch.
version: 2
jobs:
  build:
    machine: true
    branches:
      ignore: gh-pages
    steps:
      - run: echo "Skipping tests on gh-pages branch"

Save this file as config.yml and place it in a .circleci directory inside your website/static directory.

Using Travis CI

  1. Go to https://github.com/settings/tokens and generate a new personal access token
  2. Using your GitHub account, add the Travis CI app to the repository you want to activate.
  3. Open your Travis CI dashboard. The URL looks like https://travis-ci.com/USERNAME/REPO, and navigate to the More options > Setting > Environment Variables section of your repository.
  4. Create 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).
  5. Create a .travis.yml on the root of your repository with below text.
# .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

Now, whenever a new commit lands in master, Travis CI will run your suite of tests and, if everything passes, your website will be deployed via the publish-gh-pages script.

Hébergement sur ZEIT now

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

Hosting on Netlify

Steps to configure your Docusaurus-powered site on Netlify.

  1. Select New site from Git

  2. Connect to your preferred Git provider.

  3. Select the branch to deploy. Default is master

  4. Configure your build steps:

    • For your build command enter: cd website; npm install; npm run build;
    • For publish directory: website/build/<projectName> (use the projectName from your siteConfig)

  5. Click Deploy site

You can also configure Netlify to rebuild on every commit to your repository, or only master branch commits.

Hébergement sur Render

Render offre gratuitement l'hebergement d'un site statique avec SSL entièrement géré, domaines personnalisés, un CDN global et des déploiements continus automatiques de votre dépôt Git. 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. Select the branch to deploy. 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.

    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.

Publishing to GitHub Enterprise

GitHub enterprise installations should work in the same manner as github.com; you only need to identify the organization's GitHub Enterprise host.

NomDescription
GITHUB_HOSTLe nom d'hôte du serveur d'entreprise GitHub.

Alter your siteConfig.js to add a property 'githubHost' which represents the GitHub Enterprise hostname. Alternatively, set an environment variable GITHUB_HOST when executing the publish command.

← Création de votre siteDocker →