Migration manuelle
Ce processus de migration manuelle doit ĂȘtre exĂ©cutĂ© aprĂšs le processus de migration automatisĂ©e, pour complĂ©ter les piĂšces manquantes, ou les problĂšmes de dĂ©bogage en sortie du CLI de migration.
Configuration du projetâ
package.json
â
Noms de paquets Ă©tendusâ
Dans Docusaurus 2, nous utilisons des noms de paquets Ă©tendus :
docusaurus
â@docusaurus/core
Ceci fournit une distinction claire entre les paquets officiels de Docusaurus et les paquets gérés par la communauté. En d'autres termes, tous les paquets officiels de Docusaurus sont nommés sous @docusaurus/
.
Par ailleurs, les fonctionnalités du site de doc par défaut fournies par Docusaurus 1 sont désormais assurées par @docusaurus/preset-classic
. Par conséquent, nous devons également ajouter cette dépendance :
{
dependencies: {
- "docusaurus": "^1.x.x",
+ "@docusaurus/core": "^2.0.0-beta.0",
+ "@docusaurus/preset-classic": "^2.0.0-beta.0",
}
}
Veuillez utiliser la version la plus récente de Docusaurus 2, que vous pouvez consulter ici (en utilisant la balise latest
).
Commandes du CLIâ
Par ailleurs, les commandes CLI sont renommées en docusaurus <command>
(au lieu de docusaurus-command
).
La section "scripts"
de votre package.json
doit ĂȘtre mise Ă jour comme suit :
{
"scripts": {
"start": "docusaurus start",
"build": "docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy"
// ...
}
}
Un package.json
typique de Docusaurus 2 peut ressembler Ă ceci :
{
"scripts": {
"docusaurus": "docusaurus",
"start": "docusaurus start",
"build": "docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy",
"serve": "docusaurus serve",
"clear": "docusaurus clear"
},
"dependencies": {
"@docusaurus/core": "^2.0.0-beta.0",
"@docusaurus/preset-classic": "^2.0.0-beta.0",
"clsx": "^1.1.1",
"react": "^17.0.2",
"react-dom": "^17.0.2"
},
"browserslist": {
"production": [">0.5%", "not dead", "not op_mini all"],
"development": [
"last 1 chrome version",
"last 1 firefox version",
"last 1 safari version"
]
}
}
Mettez à jour les références vers le répertoire build
â
Dans Docusaurus 1, tous les artefacts de construction se trouvent dans website/build/<PROJECT_NAME>
.
Dans Docusaurus 2, il est désormais transféré dans website/build
. Assurez-vous de mettre à jour votre configuration de déploiement pour lire les fichiers générés à partir du répertoire build
.
Si vous déployez sur des pages GitHub, assurez-vous d'exécuter yarn deploy
au lieu du script yarn publish-gh-pages
.
.gitignore
â
Le .gitignore
de votre website devrait contenir :
# dependencies
/node_modules
# production
/build
# generated files
.docusaurus
.cache-loader
# misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local
npm-debug.log*
yarn-debug.log*
yarn-error.log*
README
â
Le site web D1 peut avoir un fichier README existant. Vous pouvez le modifier pour refléter les modifications D2, ou copier le Docusaurus v2 README par défaut.
Configurations du siteâ
docusaurus.config.js
â
Renommez siteConfig.js
en docusaurus.config.js
.
Dans Docusaurus 2, nous découpons chaque fonctionnalité (blog, docs, pages) en plugins pour la modularité. Les presets sont des bundles de plugins et pour une compatibilité ascendante nous avons construit un @docusaurus/preset-classic
, preset qui regroupe la plupart des plugins essentiels présents dans Docusaurus 1.
Ajoutez la section preset suivante Ă votre docusaurus.config.js
.
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// Chemin du dossier Docs relatif au répertoire du site web.
path: '../docs',
// Fichier des barres latérales relatif au répertoire du site web.
sidebarPath: require.resolve('./sidebars.json'),
},
// ...
},
],
],
};
Nous recommandons de déplacer le dossier docs
dans le dossier website
et c'est aussi la structure de rĂ©pertoire par dĂ©faut dans la v2. Vercel prend en charge les dĂ©ploiements de projets Docusaurus prĂȘts Ă l'emploi si le rĂ©pertoire docs
se trouve à l'intérieur du website
. Il est également généralement préférable que la documentation soit dans le site web afin que la documentation et le reste du code du site soient colocalisés dans un répertoire website
.
Si vous migrez votre site web Docusaurus v1 et qu'il y a des pull requests de documentation en attente, vous pouvez temporairement garder le dossier /docs
Ă sa place d'origine, pour Ă©viter de produire des conflits.
Reportez-vous au guide de migration ci-dessous pour chaque champ dans siteConfig.js
.
Champs mis Ă jourâ
baseUrl
, tagline
, title
, url
, favicon
, organizationName
, projectName
, githubHost
, scripts
, stylesheets
â
Aucune action requise, ces champs de configuration n'ont pas été modifiés.
colors
â
DĂ©prĂ©ciĂ©. Nous avons Ă©crit un framework CSS personnalisĂ© pour Docusaurus 2 appelĂ© Infima qui utilise des variables CSS pour le thĂšme. Les docs ne sont pas encore tout Ă fait prĂȘtes et nous les mettrons Ă jour ici quand elles le seront. Pour Ă©craser les variables CSS d'Infima, crĂ©ez votre propre fichier CSS (par exemple ./src/css/custom.css
) et importez-le globalement en le passant en option Ă @docusaurus/preset-classic
:
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
theme: {
customCss: [require.resolve('./src/css/custom.css')],
},
},
],
],
};
Infima utilise 7 nuances de chaque couleur.
/**
* Vous pouvez surcharger les variables par défaut d'Infima ici.
* Remarque : il ne s'agit pas d'une liste exhaustive des variables --ifm-.
*/
:root {
--ifm-color-primary: #25c2a0;
--ifm-color-primary-dark: rgb(33, 175, 144);
--ifm-color-primary-darker: rgb(31, 165, 136);
--ifm-color-primary-darkest: rgb(26, 136, 112);
--ifm-color-primary-light: rgb(70, 203, 174);
--ifm-color-primary-lighter: rgb(102, 212, 189);
--ifm-color-primary-lightest: rgb(146, 224, 208);
}
Nous vous recommandons d'utiliser ColorBox pour trouver les différentes nuances de couleurs pour la couleur principale que vous avez choisie.
Sinon, utilisez l'outil suivant pour générer les différentes nuances pour votre site web et copiez les variables dans src/css/custom.css
.
Visez au moins Taux de contraste WCAG-AA pour la couleur principale afin de garantir la lisibilitĂ©. Utilisez le site Web du Docusaurus lui-mĂȘme pour avoir un aperçu de votre palette de couleurs. Vous pouvez utiliser d'autres palettes en mode sombre, car une couleur ne fonctionne gĂ©nĂ©ralement pas en mode clair et en mode sombre.
Nom de la variable CSS | Hex | Ajustement | Taux de contraste |
---|---|---|---|
--ifm-color-primary-lightest | #3cad6e | Fail đŽ | |
--ifm-color-primary-lighter | #359962 | Fail đŽ | |
--ifm-color-primary-light | #33925d | Fail đŽ | |
--ifm-color-primary | #2e8555 | 0 | AA đ |
--ifm-color-primary-dark | #29784c | AA đ | |
--ifm-color-primary-darker | #277148 | AA đ | |
--ifm-color-primary-darkest | #205d3b | AAA đ |
Remplacez les variables dans src/css/custom.css
par ces nouvelles variables.
:root {
--ifm-color-primary: #2e8555;
--ifm-color-primary-dark: #29784c;
--ifm-color-primary-darker: #277148;
--ifm-color-primary-darkest: #205d3b;
--ifm-color-primary-light: #33925d;
--ifm-color-primary-lighter: #359962;
--ifm-color-primary-lightest: #3cad6e;
}
footerIcon
, copyright
, ogImage
, twitterImage
, docsSideNavCollapsible
â
Les métadonnées du site telles que les ressources, le référencement, les informations sur les droits d'auteur sont maintenant gérées par thÚmes. Pour les personnaliser, utilisez le champ themeConfig
dans votre docusaurus.config.js
:
module.exports = {
// ...
themeConfig: {
footer: {
logo: {
alt: 'Meta Open Source Logo',
src: '/img/meta_oss_logo.png',
href: 'https://opensource.facebook.com/',
},
copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`, // Vous pouvez également y insérer votre propre code HTML.
},
image: 'img/docusaurus.png',
// ...
},
};
headerIcon
, headerLinks
â
Dans Docusaurus 1, l'icĂŽne d'entĂȘte et les liens d'entĂȘte Ă©taient des champs racine dans siteConfig
:
headerIcon: 'img/docusaurus.svg',
headerLinks: [
{ doc: "doc1", label: "Pour commencer" },
{ page: "help", label: "Aide" },
{ href: "https://github.com/", label: "GitHub" },
{ blog: true, label: "Blog" },
],
Maintenant, ces deux champs sont tous deux traités par le thÚme :
module.exports = {
// ...
themeConfig: {
navbar: {
title: 'Docusaurus',
logo: {
alt: 'Docusaurus Logo',
src: 'img/docusaurus.svg',
},
items: [
{to: 'docs/doc1', label: 'Getting Started', position: 'left'},
{to: 'help', label: 'Help', position: 'left'},
{
href: 'https://github.com/',
label: 'GitHub',
position: 'right',
},
{to: 'blog', label: 'Blog', position: 'left'},
],
},
// ...
},
};
algolia
â
module.exports = {
// ...
themeConfig: {
algolia: {
apiKey: '47ecd3b21be71c5822571b9f59e52544',
indexName: 'docusaurus-2',
algoliaOptions: { //... },
},
// ...
},
};
Votre configuration Algolia DocSearch v1 (trouvĂ©e ici) doit ĂȘtre mise Ă jour pour Docusaurus v2 (exemple).
Vous pouvez contacter l'équipe DocSearch (@shortcuts, @s-pace) pour obtenir de l'aide. Ils peuvent le mettre à jour pour vous et déclencher une réindexation de votre site pour rétablir la recherche (sinon, vous devrez attendre jusqu'à 24 heures pour la prochaine réindexation programmée)
blogSidebarCount
â
Déprécié. Transmettez-le à la place comme option du blog à @docusaurus/preset-classic
:
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
postsPerPage: 10,
},
// ...
},
],
],
};
cname
â
Déprécié. Créez un fichier CNAME
dans votre dossier static
à la place avec votre domaine personnalisé. Les fichiers dans le dossier static
seront copiés à la racine du dossier build
lors de l'exécution de la commande build.
customDocsPath
, docsUrl
, editUrl
, enableUpdateBy
, enableUpdateTime
â
RUPTURE : editUrl
devrait pointer vers le projet (website) Docusaurus au lieu du répertoire docs
.
Déprécié. Transmettez-le à la place comme une option à @docusaurus/preset-classic
:
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// Ăquivalent Ă `customDocsPath`.
path: 'docs',
// Equivalent à `editUrl` mais doit pointer vers le répertoire `website` au lieu de `website/docs`.
editUrl: 'https://github.com/facebook/docusaurus/edit/main/website',
// Ăquivalent Ă `docsUrl`.
routeBasePath: 'docs',
// Les plugins Remark et Rehype sont passés au MDX. Remplace `markdownOptions` et `markdownPlugins`.
remarkPlugins: [],
rehypePlugins: [],
// Ăquivalent Ă `enableUpdateBy`.
showLastUpdateAuthor: true,
// Ăquivalent Ă `enableUpdateTime`.
showLastUpdateTime: true,
},
// ...
},
],
],
};
gaTrackingId
â
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
// ...
googleAnalytics: {
trackingID: 'UA-141789564-1',
},
},
],
],
};
gaGtag
â
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
// ...
gtag: {
trackingID: 'UA-141789564-1',
},
},
],
],
};
Champs supprimĂ©sâ
Les champs suivants sont tous obsolĂštes, vous pouvez les supprimer de votre fichier de configuration.
blogSidebarTitle
cleanUrl
- L'URL propre est maintenant utilisée par défaut.defaultVersionShown
- La gestion de version n'est pas encore portée. Vous ne serez pas en mesure de migrer vers Docusaurus 2 si vous utilisez les versions. Restez à l'écoute.disableHeaderTitle
disableTitleTagline
docsSideNavCollapsible
est disponible avecdocsPluginOptions.sidebarCollapsible
, et cela est activé par défaut maintenant.facebookAppId
facebookComments
facebookPixelId
fonts
highlight
- Nous utilisons maintenant Prism au lieu de highlight.js.markdownOptions
- Nous utilisons MDX dans la v2 au lieu de Remarkable. Vos options de Markdown doivent ĂȘtre converties en plugins Remark/Rehype.markdownPlugins
- Nous utilisons MDX dans la v2 au lieu de Remarkable. Vos plugins Markdown doivent ĂȘtre convertis en plugins Remark/Rehype.manifest
onPageNav
- Ceci est activé par défaut maintenant.separateCss
- Il peut ĂȘtre importer de la mĂȘme maniĂšre que custom.css mentionnĂ©e ci-dessus.scrollToTop
scrollToTopOptions
translationRecruitingLink
twitter
twitterUsername
useEnglishUrl
users
usePrism
- Nous utilisons maintenant Prism au lieu de highlight.jswrapPagesHTML
Nous avons l'intention d'implémenter de nombreux champs de configuration obsolÚtes en tant que plugins à l'avenir. Toute aide sera appréciée !
URLâ
Dans la v1, toutes les pages Ă©taient disponibles avec ou sans l'extension .html
.
Par exemple, ces 2 pages existent :
Si cleanUrl
Ă©tait :
true
: les liens ciblaient/installation
false
: les liens ciblaient/installation.html
Dans la v2, par défaut, la page canonique est /installation
, et non /installation.html
.
Si vous aviez cleanUrl: false
dans la v1, il est possible que les gens aient publié des liens vers /installation.html
.
Pour des raisons de référencement et en évitant de rompre les liens, vous devez configurer les rÚgles de redirection cÎté serveur sur votre hébergeur.
En tant que hatch d'échappement, vous pouvez utiliser @docusaurus/plugin-client-redirects pour créer des redirections cÎté client de /installation.html
vers /installation
.
module.exports = {
plugins: [
[
'@docusaurus/plugin-client-redirects',
{
fromExtensions: ['html'],
},
],
],
};
Si vous voulez garder l'extension .html
comme l'URL canonique d'une page, docs peut déclarer un slug: installation.html
dans le front matter.
Composantsâ
Barre latĂ©raleâ
Dans la version précédente, les catégories imbriquées dans la barre latérale ne sont pas autorisées et la catégorie de la barre latérale ne peut contenir que l'ID du doc. Cependant, la v2 permet une barre latérale imbriquée infinie et nous avons de nombreux types d'élément de barre latérale autre que le document.
Vous devrez migrer votre barre latérale si elle contient le type de catégorie. Renommer subcategory
en category
et ids
en items
.
{
- type: 'subcategory',
+ type: 'category',
label: 'My Example Subcategory',
+ items: ['doc1'],
- ids: ['doc1']
},
Footerâ
website/core/Footer.js
n'est plus nécessaire. Si vous voulez modifier le pied de page par défaut fourni par Docusaurus, swizzler le :
- npm
- Yarn
- pnpm
npm run swizzle @docusaurus/theme-classic Footer
yarn swizzle @docusaurus/theme-classic Footer
pnpm run swizzle @docusaurus/theme-classic Footer
Cela copiera le composant <Footer />
actuel utilisé par le thÚme dans un répertoire src/theme/Footer
sous la racine de votre site, vous pouvez ensuite modifier ce composant pour la personnalisation.
Ne swizzlez pas le pied de page juste pour ajouter le logo sur la gauche. Le logo est délibérément enlevé en v2 et déplacé vers le bas. Il suffit de configurer le pied de page dans docusaurus.config.js
avec themeConfig.footer
:
module.exports = {
themeConfig: {
footer: {
logo: {
alt: 'Meta Open Source Logo',
src: '/img/meta_oss_logo.png',
href: 'https://opensource.facebook.com',
},
},
},
};
Pagesâ
Veuillez vous référer à la |création de pages](guides/creating-pages.mdx) pour apprendre comment fonctionnent les pages Docusaurus 2. AprÚs avoir lu cela, notez que vous devez déplacer les fichiers pages/en
de la v1 vers src/pages
Ă la place.
Dans Docusaurus v1, les pages ont reçu l'objet siteConfig
comme props.
Dans Docusaurus v2, récupérer l'objet siteConfig
depuis useDocusaurusContext
Ă la place.
En v2, vous devez appliquer la mise en page du thÚme autour de chaque page. Le composant de mise en page prend des props de métadonnées.
CompLibrary
est obsolÚte dans la v2, donc vous devez écrire votre propre composant React ou utiliser les styles Infima (Les docs seront bientÎt disponibles, désolé ! Pendant ce temps, inspectez le site Web V2 ou consultez https://infima.dev/ pour voir quels styles sont disponibles).
Vous pouvez migrer CommonJS vers les imports/exportations ES6.
Voici une page typique de Docusaurus v2 :
import React from 'react';
import Link from '@docusaurus/Link';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
import Layout from '@theme/Layout';
const MyPage = () => {
const {siteConfig} = useDocusaurusContext();
return (
<Layout title={siteConfig.title} description={siteConfig.tagline}>
<div className="hero text--center">
<div className="container ">
<div className="padding-vert--md">
<h1 className="hero__title">{siteConfig.title}</h1>
<p className="hero__subtitle">{siteConfig.tagline}</p>
</div>
<div>
<Link
to="/docs/get-started"
className="button button--lg button--outline button--primary">
Get started
</Link>
</div>
</div>
</div>
</Layout>
);
};
export default MyPage;
Le code suivant pourrait ĂȘtre utile pour la migration de diffĂ©rentes pages :
- Page d'index - Flux (recommandé), Docusaurus 2, Hermes
- Page d'aide/support - Docusaurus 2, Flux
Contenuâ
Remplacez AUTOGENERATED_TABLE_OF_CONTENTSâ
Cette fonctionnalité est remplacée par la table des matiÚres en ligne
Mettez Ă jour la syntaxe Markdown pour ĂȘtre compatible avec MDXâ
Dans Docusaurus 2, la syntaxe Markdown a été changée en MDX. Il se peut donc que les documents existants contiennent des erreurs de syntaxe que vous devrez mettre à jour. Un exemple courant est celui des balises auto-fermantes comme <img>
et <br>
qui sont valides en HTML, mais doivent maintenant ĂȘtre explicitement fermĂ©es (<img/>
et <br/>
). Toutes les balises des documents MDX doivent ĂȘtre des JSX valides.
La partie haute (front matter) est analysée par gray-matter. Si votre front matter utilise des caractÚres spéciaux comme :
, vous devez maintenant le mettre entre quote : title: Partie 1: mon titre de la partie1
â title: "Partie 1: mon titre de la partie1"
.
Astuces : Vous pouvez utiliser des outils en ligne comme HTML vers JSX pour faciliter la migration.
Onglets de code spĂ©cifiques au langageâ
Reportez-vous Ă la section blocs de code multi-langage.
Front matterâ
Les champs du frontmatter de Docusaurus pour le blog ont Ă©tĂ© changĂ©s de camelCase Ă snake_case pour ĂȘtre cohĂ©rents avec la documentation.
Les champs authorFBID
et authorTwitter
ont Ă©tĂ© dĂ©prĂ©ciĂ©s. Ils ne sont utilisĂ©s que pour gĂ©nĂ©rer l'image de profil de l'auteur qui peut ĂȘtre faite via le champ authors
.
DĂ©ploiementâ
Le fichier CNAME
utilisé par GitHub Pages n'est plus généré, donc assurez-vous de l'avoir créé dans /static/CNAME
si vous utilisez un domaine personnalisé.
Le flux RSS du blog est maintenant hébergé dans /blog/rss.xml
au lieu de /blog/feed.xml
. Vous pouvez configurer les redirections cÎté serveur pour que les abonnements des utilisateurs continuent à fonctionner.
Testez votre siteâ
AprĂšs la migration, la structure de votre dossier devrait ressembler Ă ceci :
my-project
âââ docs
âââ website
âââ blog
âââ src
â âââ css
â â âââ custom.css
â âââ pages
â âââ index.js
âââ package.json
âââ sidebars.json
âââ .gitignore
âââ docusaurus.config.js
âââ static
Démarrez le serveur de développement et corrigez les erreurs :
- npm
- Yarn
- pnpm
cd website
npm start
cd website
yarn start
cd website
pnpm start
Vous pouvez Ă©galement essayer de construire le site pour la production :
- npm
- Yarn
- pnpm
npm run build
yarn build
pnpm run build