Installation
Docusaurus is essentially a set of npm packages.
Use the Fast Track to understand Docusaurus in 5 minutes ⏱!
Use docusaurus.new to test Docusaurus immediately in your browser!
Requirements
- Node.js version 16.14 or above (which can be checked by running
node -v
). You can use nvm for managing multiple Node versions on a single machine installed.- Lors de l'installation de Node.js, il est recommandé de cocher toutes les cases liées aux dépendances.
Scaffold project website
La façon la plus simple d'installer Docusaurus est d'utiliser l'outil en ligne de commande qui vous aide à créer un squelette de site web Docusaurus. Vous pouvez exécuter cette commande n'importe où dans un nouveau dépôt vide ou dans un dépôt existant, elle créera un nouveau répertoire contenant les fichiers de structure.
npx [email protected] my-website classic
We recommend the classic
template so that you can get started quickly, and it contains features found in Docusaurus 1. The classic
template contains @docusaurus/preset-classic
which includes standard documentation, a blog, custom pages, and a CSS framework (with dark mode support). Vous pouvez être opérationnel très rapidement avec le template classic et personnaliser les choses plus tard, lorsque vous serez plus familier avec Docusaurus.
You can also use the template's TypeScript variant by passing the --typescript
flag. See TypeScript support for more information.
npx [email protected] my-website classic --typescript
If you are setting up a new Docusaurus website for a Facebook open source project, use the facebook
template instead, which comes with some useful Facebook-specific defaults:
npx [email protected] my-website facebook
Alternative installation commands
Vous pouvez également initialiser un nouveau projet en utilisant votre gestionnaire de projet préféré :
- npm
- Yarn
- pnpm
npm init docusaurus
yarn create docusaurus
pnpm create docusaurus
Run npx [email protected] --help
, or check out its API docs for more information about all available flags.
Project structure
Assuming you chose the classic template and named your site my-website
, you will see the following files generated under a new directory my-website/
:
my-website
├── blog
│ ├── 2019-05-28-hola.md
│ ├── 2019-05-29-hello-world.md
│ └── 2020-05-30-welcome.md
├── docs
│ ├── doc1.md
│ ├── doc2.md
│ ├── doc3.md
│ └── mdx.md
├── src
│ ├── css
│ │ └── custom.css
│ └── pages
│ ├── styles.module.css
│ └── index.js
├── static
│ └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock
Project structure rundown
/blog/
- Contains the blog Markdown files. You can delete the directory if you've disabled the blog plugin, or you can change its name after setting thepath
option. More details can be found in the blog guide/docs/
- Contains the Markdown files for the docs. Customize the order of the docs sidebar insidebars.js
. You can delete the directory if you've disabled the docs plugin, or you can change its name after setting thepath
option. More details can be found in the docs guide/src/
- Non-documentation files like pages or custom React components. Vous n'êtes pas obligé de placer vos fichiers de non-documentation ici, mais les placer dans un répertoire centralisé permet de les spécifier plus facilement au cas où vous auriez besoin de faire une sorte de vérification/traitement/src/pages
- Any JSX/TSX/MDX file within this directory will be converted into a website page. More details can be found in the pages guide
/static/
- Static directory. Any contents inside here will be copied into the root of the finalbuild
directory/docusaurus.config.js
- A config file containing the site configuration. This is the equivalent ofsiteConfig.js
in Docusaurus v1/package.json
- A Docusaurus website is a React app. Vous pouvez y installer et utiliser tous les paquets npm que vous souhaitez/sidebars.js
- Used by the documentation to specify the order of documents in the sidebar
Monorepos
Si vous utilisez Docusaurus pour la documentation d'un projet existant, un monorepo peut être la solution pour vous. Les monorepos vous permet de partager des dépendances entre des projets similaires. Par exemple, votre site Web peut utiliser vos paquets locaux pour mettre en valeur les dernières fonctionnalités au lieu de dépendre d'une version publiée ; vos contributeurs peuvent également mettre à jour facilement les documentations au fur et à mesure qu'elles implémentent des fonctionnalités. Un exemple de structure de dossier monorepo est ci-dessous :
my-monorepo
├── package-a # Un autre paquet, votre projet actuel
│ ├── src
│ └── package.json # Les dépendances du paquet A
├── website # racine de Docusaurus
│ ├── docs
│ ├── src
│ └── package.json # Les dépendances de Docusaurus
├── package.json # dépendances partagées du monorepo
In this case, you should run npx create-docusaurus
within the ./my-monorepo
folder.
If you're using a hosting provider such as Netlify or Vercel, you will need to change the Base directory
of the site to where your Docusaurus root is. In this case, that would be ./website
. Read more about configuring ignore commands in the deployment docs.
Read more about monorepos in the Yarn documentation (Yarn is not the only way to set up a monorepo, but it's a common solution), or checkout Docusaurus and Jest for some real-world examples.
Running the development server
Pour prévisualiser vos modifications au fur et à mesure que vous modifiez les fichiers, vous pouvez lancer un serveur de développement local qui servira votre site Web et reflétera les dernières modifications.
- npm
- Yarn
- pnpm
cd my-website
npm run start
cd my-website
yarn run start
cd my-website
pnpm run start
By default, a browser window will open at http://localhost:3000.
Félicitations ! Vous venez de créer votre premier site Docusaurus ! Naviguez sur le site pour voir ce qui est disponible.
Build
Docusaurus est un générateur de site web statique moderne donc nous avons besoin de construire le site web dans un répertoire de contenu statique et de le mettre sur un serveur web pour qu'il puisse être consulté. Pour construire le site web :
- npm
- Yarn
- pnpm
npm run build
yarn build
pnpm run build
and contents will be generated within the /build
directory, which can be copied to any static file hosting service like GitHub pages, Vercel or Netlify. Check out the docs on deployment for more details.
Updating your Docusaurus version
Il y a de nombreuses façons de mettre à jour votre version de Docusaurus. One guaranteed way is to manually change the version number in package.json
to the desired version. Note that all @docusaurus/
-namespaced packages should be using the same version.
{
"dependencies": {
"@docusaurus/core": "2.4.0",
"@docusaurus/preset-classic": "2.4.0",
// ...
}
}
Then, in the directory containing package.json
, run your package manager's install command:
- npm
- Yarn
- pnpm
npm install
yarn install
pnpm install
Pour vérifier que la mise à jour a été effectuée avec succès, exécutez :
npx docusaurus --version
Vous devriez voir la version correcte en résultat.
Alternativement, si vous utilisez Yarn, vous pouvez faire :
yarn upgrade @docusaurus/[email protected] @docusaurus/[email protected]
Use new unreleased features of Docusaurus with the @canary
npm dist tag
Des problèmes ?
Ask for help on Stack Overflow, on our GitHub repository, our Discord server, or Twitter.