Initial vault setup
This commit is contained in:
@@ -0,0 +1,137 @@
|
||||
---
|
||||
title: Docusaurus
|
||||
created: 2026-06-07
|
||||
updated: 2026-06-07
|
||||
type: app
|
||||
tags: [catalogue, wiki, documentation, static-site, markdown, react, nodejs, meta]
|
||||
confidence: high
|
||||
contested: false
|
||||
sources: [https://selfh.st/apps/?tag=wiki]
|
||||
---
|
||||
|
||||
# 📘 Docusaurus
|
||||
|
||||
> Générateur de site statique spécialisé documentation, créé par Meta (Facebook), basé sur React et MDX. Idéal pour publier une documentation technique soignée, versionnée, multilingue et recherchable.
|
||||
|
||||
| Métadonnée | Valeur |
|
||||
| :--- | :--- |
|
||||
| **Site web** | [docusaurus.io](https://docusaurus.io/) |
|
||||
| **GitHub** | [facebook/docusaurus](https://github.com/facebook/docusaurus) |
|
||||
| **License** | MIT |
|
||||
| **Langage** | TypeScript / Node.js |
|
||||
| **Étoiles** | ⭐ 9924 |
|
||||
| **Dernière MAJ** | 2026-06-04 |
|
||||
| **Catégorie** | [[cat-wiki]] |
|
||||
|
||||
## Description
|
||||
|
||||
Docusaurus est un générateur de site statique spécialisé dans la **documentation technique** et les **sites vitrines de projet open source**. Développé et maintenu par Meta (Facebook) depuis 2017, il s'appuie sur React, MDX et un système de plugins extensible. Le contenu se rédige principalement en **Markdown / MDX**, ce qui le rend accessible aux rédacteurs techniques tout en offrant la puissance des composants React pour les pages plus riches.
|
||||
|
||||
L'écosystème est mature : thèmes Material UI, Infima, système de blog intégré, recherche locale (Algolia DocSearch), i18n natif pour le multilinguisme, versioning de la documentation, dark mode, et une marketplace de plugins très active. Docusaurus est utilisé par de nombreux projets de grande ampleur (React Native, Jest, Babel, Tauri, Supabase) pour leur documentation publique.
|
||||
|
||||
C'est l'outil de choix pour qui veut **publier** de la documentation (et non la gérer en interne comme un wiki). Pour un usage interne d'équipe, on préférera des solutions de type [[app-wiki-js]] ou [[app-docmost]]. Pour un site purement statique sans besoin collaboratif d'édition, [[app-mkdocs]] (Python) reste une alternative très populaire.
|
||||
|
||||
## Installation
|
||||
|
||||
### Option 1 : Docker (site statique buildé)
|
||||
|
||||
Docusaurus n'a pas d'image officielle « serveur » car c'est un **générateur statique** : on builde le site, puis on le sert avec Nginx/Caddy. L'astuce Docker classique consiste à builder dans un conteneur Node puis à servir le dossier `build/` avec un conteneur Nginx.
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
services:
|
||||
docusaurus:
|
||||
image: node:20-alpine
|
||||
container_name: docusaurus
|
||||
working_dir: /srv
|
||||
volumes:
|
||||
- ./site:/srv
|
||||
command: >
|
||||
sh -c "npm install &&
|
||||
npm run build"
|
||||
profiles: ["build"]
|
||||
|
||||
nginx:
|
||||
image: nginx:1.27-alpine
|
||||
container_name: docusaurus-web
|
||||
depends_on:
|
||||
- docusaurus
|
||||
volumes:
|
||||
- ./site/build:/usr/share/nginx/html:ro
|
||||
- ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
|
||||
ports:
|
||||
- "8080:80"
|
||||
restart: unless-stopped
|
||||
```
|
||||
|
||||
Workflow : `docker compose run --rm docusaurus` pour builder, puis `docker compose up -d nginx` pour servir.
|
||||
|
||||
### Option 2 : Installation manuelle (développement)
|
||||
|
||||
```bash
|
||||
npx create-docusaurus@latest mon-site classic --typescript
|
||||
cd mon-site
|
||||
npm install
|
||||
npm run start # dev server avec HMR sur :3000
|
||||
npm run build # build statique vers build/
|
||||
npm run serve # prévisualisation locale du build
|
||||
```
|
||||
|
||||
Prérequis : **Node.js 18+**, npm ou pnpm. Pour la production, on déploie le contenu de `build/` derrière n'importe quel serveur HTTP (Nginx, Caddy, Cloudflare Pages, Netlify, S3+CloudFront).
|
||||
|
||||
## Configuration
|
||||
|
||||
Le fichier central est `docusaurus.config.ts` (TypeScript) ou `docusaurus.config.js`. Il déclare le site, l'URL canonique, l'organisation (GitHub), les thèmes, le i18n, les plugins et la navbar/footer.
|
||||
|
||||
Points clés à configurer :
|
||||
|
||||
- **i18n** : `i18n.defaultLocale`, `i18n.locales: ['fr', 'en']` pour le multilinguisme ; on traduit avec `npm run write-translations -- --locale fr`.
|
||||
- **Thème** : `themes: [@docusaurus/theme-live-codeblock, @docusaurus/theme-mermaid]` pour étendre le thème par défaut.
|
||||
- **Recherche** : `@docusaurus/preset-classic` inclut la recherche locale (lunr) ; pour Algolia DocSearch, fournir `appId`, `apiKey`, `indexName`.
|
||||
- **Versioning** : `npm run docusaurus docs:version 2.0` pour figer une version de docs.
|
||||
- **Blog** : activable via le preset classic (`blog: {showReadingTime: true, blogSidebarTitle: 'Articles'}`).
|
||||
- **Déploiement** : variables `organizationName`, `projectName`, `deploymentBranch` (par défaut `gh-pages`) pour GitHub Pages ; pour ailleurs, on uploade le dossier `build/` où on veut.
|
||||
|
||||
## Alternatives
|
||||
|
||||
### Open Source
|
||||
|
||||
- [[app-mkdocs]] — Équivalent Python pur, plus minimaliste, parfait pour de la doc « classique » non marketing.
|
||||
- [[app-wiki-js]] — Wiki éditable en ligne, davantage tourné vers l'usage interne d'équipe.
|
||||
- [[app-docmost]] — Wiki/docs collaboratif plus moderne, avec édition temps réel.
|
||||
- **VitePress** — Construit sur Vue, plus léger, même philosophie.
|
||||
- **Astro** (starlight) — Plus polyvalent (marketing + docs), excellentes performances.
|
||||
- **Hugo** — Statique généraliste, courbé pour la doc mais pas spécialisé.
|
||||
- **Sphinx** — Le standard Python historique, notamment pour ReadTheDocs.
|
||||
|
||||
### Propriétaires (ce que Docusaurus remplace)
|
||||
|
||||
- **Gitbook** (cloud) — Documentation commerciale, Docusaurus fait très bien le même job.
|
||||
- **ReadTheDocs** (cloud) — Plateforme d'hébergement de doc open source.
|
||||
- **Notion** (en export) — Quand on veut un site public plutôt qu'un wiki interne.
|
||||
- **Confluence + thème public** — Quand on veut industrialiser la publication de docs.
|
||||
|
||||
## Sécurité
|
||||
|
||||
- ✅ **Statique** : surface d'attaque nulle côté serveur, pas de base de données, pas d'auth à gérer.
|
||||
- ✅ Code auditable (Meta, très utilisé, milliards de pages servies).
|
||||
- ⚠️ Attention aux **plugins tiers** non maintenus : limiter aux plugins officiels `@docusaurus/*` ou aux plus étoilés.
|
||||
- ⚠️ Le contenu est généralement versionné dans Git, donc **penser aux secrets** (clés API Algolia, etc.) : ne jamais les committer, utiliser CI/CD avec variables d'environnement.
|
||||
- ⚠️ Activer **HTTPS** sur le serveur final (Caddy/LetsEncrypt, Cloudflare, etc.) et une **CSP** si on charge des scripts externes.
|
||||
- ✅ Héberger derrière un CDN pour la performance et la protection DDoS (Cloudflare, Fastly, Netlify).
|
||||
|
||||
## Ressources
|
||||
|
||||
- [Site officiel Docusaurus](https://docusaurus.io/)
|
||||
- [Documentation](https://docusaurus.io/docs)
|
||||
- [Dépôt GitHub facebook/docusaurus](https://github.com/facebook/docusaurus)
|
||||
- [Awesome Docusaurus](https://github.com/facebook/docusaurus/discussions/7826)
|
||||
- [Algolia DocSearch](https://docsearch.algolia.com/)
|
||||
|
||||
## Pages Liées
|
||||
|
||||
- [[cat-wiki]] — Vue d'ensemble de la catégorie Wiki
|
||||
- [[app-mkdocs]] — Concurrent principal côté Python
|
||||
- [[app-wiki-js]] — Wiki éditable plutôt que publication
|
||||
- [[app-docmost]] — Wiki collaboratif moderne
|
||||
- [[recettes-docker-compose]] — Templates Docker partagés
|
||||
Reference in New Issue
Block a user