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é.
For example, both Apache and Nginx serve content from
/var/www/html
by default. 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 detext/css
. In the case of Nginx, this would mean settinginclude /etc/nginx/mime.types;
in yournginx.conf
file. See le problème pour plus d'informations.
Hébergement dans un service:
Using ZEIT Now
Deploying your Docusaurus project to ZEIT Now 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 seconds:
- First, install their command-line interface:
npm i -g now
- Run a single command inside the root directory of your project:
now
That's all. Your docs will automatically be deployed.
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
- Docusaurus supports deploying as project pages or user/organization pages, your code repository does not even need to be public.
Even if your repository is private, anything published to a
gh-pages
branch will be 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).
- You will need to modify the file
website/siteConfig.js
and add the required parameters.
Name | Description |
---|---|
organizationName | The GitHub user or organization that owns the repository. If you are the owner, then it is your GitHub username. In the case of Docusaurus, that would be the "facebook" GitHub organization. |
projectName | The name of the GitHub repository for your project. 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". |
url | Your website's URL. For projects hosted on GitHub pages, this will be "https://username.github.io" |
baseUrl | Base 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
andorganizationName
insiteConfig.js
, you can also use environment variablesORGANIZATION_NAME
andPROJECT_NAME
.
- Now you have to specify the git user as an environment variable, and run the script
publish-gh-pages
Name | Description |
---|---|
GIT_USER | The username for a GitHub account that has commit access to this repo. 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 :
Name | Description |
---|---|
USE_SSH | Si 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_BRANCH | La 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.
- 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érifiantParamètres | Collaborateurs & équipes
dans le référentiel. - Connectez-vous à GitHub sous
GIT_USER
. - 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 therepository
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. - 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.
- 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 fichierconfig.yml
dans ce répertoire. - 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
. We already configured that as an environment variable back in Step 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
.Unlike when you run the
publish-gh-pages
script manually when the script runs within the Circle environment, the value ofCURRENT_BRANCH
is already defined as an environment variable within CircleCI and will be picked up by the script automatically.
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
.
If you would rather use a deploy key instead of a personal access token, you can by starting with the CircleCI instructions for adding a read/write deploy key.
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 thepublish-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`
- Alternatively, you can work around this by creating a basic CircleCI config with the following contents:
# 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
- Go to https://github.com/settings/tokens and generate a new personal access token
- Using your GitHub account, add the Travis CI app to the repository you want to activate.
- 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. - Create a new environment variable named
GH_TOKEN
with your newly generated token as its value, thenGH_EMAIL
(your email address) andGH_NAME
(your GitHub username). - 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.
Hosting on ZEIT Now
With ZEIT Now, you can deploy your site easily and connect it to GitHub or GitLab to automatically receive a new deployment every time you push a commit.
Hosting on Netlify
Steps to configure your Docusaurus-powered site on Netlify.
Select New site from Git
Connect to your preferred Git provider.
Select the branch to deploy. Default is
master
Configure your build steps:
- For your build command enter:
cd website; npm install; npm run build;
- For publish directory:
website/build/<projectName>
(use theprojectName
from yoursiteConfig
)
- For your build command enter:
Click Deploy site
You can also configure Netlify to rebuild on every commit to your repository, or only master
branch commits.
Hosting on Render
Render offers free static site hosting with fully managed SSL, custom domains, a global CDN and continuous auto deploys from your Git repo. Deploy your app in just a few minutes by following these steps.
Create a new Web Service on Render, and give Render's GitHub app permission to access your Docusaurus repo.
Select the branch to deploy. The default is
master
.Enter the following values during creation.
Field Value Environment Static Site
Build Command cd website; yarn install; yarn build
Publish Directory website/build/<projectName>
projectName
is the value you defined in yoursiteConfig.js
.const siteConfig = { // ... projectName: 'your-project-name', // ...
That's it! Your app will be live on your Render URL as soon as the build finishes.
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.
Name | Description |
---|---|
GITHUB_HOST | The hostname for the GitHub enterprise server. |
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.