手动迁移
¥Manual migration
此手动迁移过程应在 自动化迁移过程 之后运行,以完成缺少的部分,或调试迁移 CLI 输出中的问题。
¥This manual migration process should be run after the automated migration process, to complete the missing parts, or debug issues in the migration CLI output.
项目设置
¥Project setup
package.json
范围包名称
¥Scoped package names
在 Docusaurus 2 中,我们使用范围包名称:
¥In Docusaurus 2, we use scoped package names:
docusaurus
→@docusaurus/core
这清楚地区分了 Docusaurus 的官方软件包和社区维护的软件包。换句话说,所有 Docusaurus 的官方软件包都以 @docusaurus/
命名空间。
¥This provides a clear distinction between Docusaurus' official packages and community maintained packages. In another words, all Docusaurus' official packages are namespaced under @docusaurus/
.
同时,Docusaurus 1 提供的默认文档站点功能现在由 @docusaurus/preset-classic
提供。因此,我们还需要添加这个依赖:
¥Meanwhile, the default doc site functionalities provided by Docusaurus 1 are now provided by @docusaurus/preset-classic
. Therefore, we need to add this dependency as well:
{
dependencies: {
- "docusaurus": "^1.x.x",
+ "@docusaurus/core": "^2.0.0-beta.0",
+ "@docusaurus/preset-classic": "^2.0.0-beta.0",
}
}
CLI 命令
¥CLI commands
同时,CLI 命令被重命名为 docusaurus <command>
(而不是 docusaurus-command
)。
¥Meanwhile, CLI commands are renamed to docusaurus <command>
(instead of docusaurus-command
).
package.json
的 "scripts"
部分应更新如下:
¥The "scripts"
section of your package.json
should be updated as follows:
{
"scripts": {
"start": "docusaurus start",
"build": "docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy"
// ...
}
}
典型的 Docusaurus 2 package.json
可能如下所示:
¥A typical Docusaurus 2 package.json
may look like this:
{
"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"
]
}
}
更新对 build
目录的引用
¥Update references to the build
directory
在 Docusaurus 1 中,所有构建工件都位于 website/build/<PROJECT_NAME>
内。
¥In Docusaurus 1, all the build artifacts are located within website/build/<PROJECT_NAME>
.
在 Docusaurus 2 中,它现在移至 website/build
。确保更新部署配置以从正确的 build
目录读取生成的文件。
¥In Docusaurus 2, it is now moved to just website/build
. Make sure that you update your deployment configuration to read the generated files from the correct build
directory.
如果你要部署到 GitHub 页面,请确保运行 yarn deploy
而不是 yarn publish-gh-pages
脚本。
¥If you are deploying to GitHub pages, make sure to run yarn deploy
instead of yarn publish-gh-pages
script.
.gitignore
website
中的 .gitignore
应包含:
¥The .gitignore
in your website
should contain:
# 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
D1 网站可能有现有的 README 文件。你可以修改它以反映 D2 更改,或复制默认的 Docusaurus v2 自述文件。
¥The D1 website may have an existing README file. You can modify it to reflect the D2 changes, or copy the default Docusaurus v2 README.
站点配置
¥Site configurations
docusaurus.config.js
将 siteConfig.js
重命名为 docusaurus.config.js
。
¥Rename siteConfig.js
to docusaurus.config.js
.
在 Docusaurus 2 中,我们将每个功能(博客、文档、页面)拆分为插件以实现模块化。预设是插件打包包,为了向后兼容,我们构建了 @docusaurus/preset-classic
预设,其中打包了 Docusaurus 1 中存在的大多数基本插件。
¥In Docusaurus 2, we split each functionality (blog, docs, pages) into plugins for modularity. Presets are bundles of plugins and for backward compatibility we built a @docusaurus/preset-classic
preset which bundles most of the essential plugins present in Docusaurus 1.
将以下预设配置添加到你的 docusaurus.config.js
。
¥Add the following preset configuration to your docusaurus.config.js
.
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// Docs folder path relative to website dir.
path: '../docs',
// Sidebars file relative to website dir.
sidebarPath: require.resolve('./sidebars.json'),
},
// ...
},
],
],
};
我们建议将 docs
文件夹移动到 website
文件夹中,这也是 v2 中的默认目录结构。如果 docs
目录位于 website
内,则 Vercel 支持 开箱即用的 Docusaurus 项目部署。通常,文档最好位于网站内,以便文档和网站代码的其余部分位于同一个 website
目录中。
¥We recommend moving the docs
folder into the website
folder and that is also the default directory structure in v2. Vercel supports Docusaurus project deployments out-of-the-box if the docs
directory is within the website
. It is also generally better for the docs to be within the website so that the docs and the rest of the website code are co-located within one website
directory.
如果你正在迁移 Docusaurus v1 网站,并且有待处理的文档拉取请求,你可以暂时将 /docs
文件夹保留到原来的位置,以避免产生冲突。
¥If you are migrating your Docusaurus v1 website, and there are pending documentation pull requests, you can temporarily keep the /docs
folder to its original place, to avoid producing conflicts.
请参阅下面的迁移指南了解 siteConfig.js
中的每个字段。
¥Refer to migration guide below for each field in siteConfig.js
.
更新字段
¥Updated fields
baseUrl
、tagline
、title
、url
、favicon
、organizationName
、projectName
、githubHost
、scripts
、stylesheets
无需执行任何操作,这些配置字段未修改。
¥No actions needed, these configuration fields were not modified.
colors
已弃用。我们为 Docusaurus 2 编写了一个名为 Infima 的自定义 CSS 框架,它使用 CSS 变量进行主题化。该文档尚未准备好,我们将在准备好后在此更新。要覆盖 Infima 的 CSS 变量,请创建你自己的 CSS 文件(例如 ./src/css/custom.css
)并通过将其作为选项传递给 @docusaurus/preset-classic
将其全局导入:
¥Deprecated. We wrote a custom CSS framework for Docusaurus 2 called Infima which uses CSS variables for theming. The docs are not quite ready yet and we will update here when it is. To overwrite Infima's CSS variables, create your own CSS file (e.g. ./src/css/custom.css
) and import it globally by passing it as an option to @docusaurus/preset-classic
:
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
theme: {
customCss: [require.resolve('./src/css/custom.css')],
},
},
],
],
};
Infima 每种颜色使用 7 种色调。
¥Infima uses 7 shades of each color.
/**
* You can override the default Infima variables here.
* Note: this is not a complete list of --ifm- variables.
*/
: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);
}
我们建议使用 ColorBox 来查找适合你选择的原色的不同深浅的颜色。
¥We recommend using ColorBox to find the different shades of colors for your chosen primary color.
或者,使用以下工具为你的网站生成不同的色调并将变量复制到 src/css/custom.css
。
¥Alternatively, use the following tool to generate the different shades for your website and copy the variables into src/css/custom.css
.
Aim for at least WCAG-AA contrast ratio for the primary color to ensure readability. Use the Docusaurus website itself to preview how your color palette would look like. You can use alternative palettes in dark mode because one color doesn't usually work in both light and dark mode.
CSS Variable Name | Hex | Adjustment | Contrast Rating |
---|---|---|---|
--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 🏅 |
Replace the variables in src/css/custom.css
with these new 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
网站元信息(例如资源、SEO、版权信息)现在由主题处理。要自定义它们,请使用 docusaurus.config.js
中的 themeConfig
字段:
¥Site meta info such as assets, SEO, copyright info are now handled by themes. To customize them, use the themeConfig
field in your 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.`, // You can also put own HTML here.
},
image: 'img/docusaurus.png',
// ...
},
};
headerIcon
、headerLinks
在 Docusaurus 1 中,标题图标和标题链接是 siteConfig
中的根字段:
¥In Docusaurus 1, header icon and header links were root fields in siteConfig
:
headerIcon: 'img/docusaurus.svg',
headerLinks: [
{ doc: "doc1", label: "Getting Started" },
{ page: "help", label: "Help" },
{ href: "https://github.com/", label: "GitHub" },
{ blog: true, label: "Blog" },
],
现在,这两个字段都由主题处理:
¥Now, these two fields are both handled by the theme:
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: { //... },
},
// ...
},
};
你的 Algolia DocSearch v1 配置(找到 此处)应更新为 Docusaurus v2 (example)。
¥Your Algolia DocSearch v1 config (found here) should be updated for Docusaurus v2 (example).
你可以联系 DocSearch 团队(@shortcuts、@s-pace)寻求支持。他们可以为你更新并触发对你网站的重新抓取以恢复搜索(否则你将不得不等待 24 小时才能进行下一次计划的抓取)
¥You can contact the DocSearch team (@shortcuts, @s-pace) for support. They can update it for you and trigger a recrawl of your site to restore the search (otherwise you will have to wait up to 24h for the next scheduled crawl)
blogSidebarCount
已弃用。将其作为博客选项传递给 @docusaurus/preset-classic
:
¥Deprecated. Pass it as a blog option to @docusaurus/preset-classic
instead:
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
postsPerPage: 10,
},
// ...
},
],
],
};
cname
已弃用。在 static
文件夹中创建 CNAME
文件,而不是使用自定义域。执行构建命令期间,static
文件夹中的文件将被复制到 build
文件夹的根目录中。
¥Deprecated. Create a CNAME
file in your static
folder instead with your custom domain. Files in the static
folder will be copied into the root of the build
folder during execution of the build command.
customDocsPath
、docsUrl
、editUrl
、enableUpdateBy
、enableUpdateTime
BREAKING:editUrl
应指向(网站)Docusaurus 项目而不是 docs
目录。
¥BREAKING: editUrl
should point to (website) Docusaurus project instead of docs
directory.
已弃用。将其作为选项传递给 @docusaurus/preset-classic
文档:
¥Deprecated. Pass it as an option to @docusaurus/preset-classic
docs instead:
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// Equivalent to `customDocsPath`.
path: 'docs',
// Equivalent to `editUrl` but should point to `website` dir instead of `website/docs`.
editUrl: 'https://github.com/facebook/docusaurus/edit/main/website',
// Equivalent to `docsUrl`.
routeBasePath: 'docs',
// Remark and Rehype plugins passed to MDX. Replaces `markdownOptions` and `markdownPlugins`.
remarkPlugins: [],
rehypePlugins: [],
// Equivalent to `enableUpdateBy`.
showLastUpdateAuthor: true,
// Equivalent to `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',
},
},
],
],
};
删除的字段
¥Removed fields
以下字段均已弃用,你可以从配置文件中删除。
¥The following fields are all deprecated, you may remove from your configuration file.
-
blogSidebarTitle
-
cleanUrl
- 现在默认使用 Clean URL。¥
cleanUrl
- Clean URL is used by default now. -
defaultVersionShown
- 版本控制尚未移植。如果你使用版本控制,你将无法迁移到 Docusaurus 2。敬请关注。¥
defaultVersionShown
- Versioning is not ported yet. You'd be unable to migration to Docusaurus 2 if you are using versioning. Stay tuned. -
disableHeaderTitle
-
disableTitleTagline
-
docsSideNavCollapsible
在docsPluginOptions.sidebarCollapsible
可用,现在默认打开。¥
docsSideNavCollapsible
is available atdocsPluginOptions.sidebarCollapsible
, and this is turned on by default now. -
facebookAppId
-
facebookComments
-
facebookPixelId
-
fonts
-
highlight
- 我们现在使用 Prisma 而不是 highlight.js。¥
highlight
- We now use Prism instead of highlight.js. -
markdownOptions
- 我们在 v2 中使用 MDX 而不是 Remarkable。你的 Markdown 选项必须转换为 Remark/Rehype 插件。¥
markdownOptions
- We use MDX in v2 instead of Remarkable. Your Markdown options have to be converted to Remark/Rehype plugins. -
markdownPlugins
- 我们在 v2 中使用 MDX 而不是 Remarkable。你的 Markdown 插件必须转换为 Remark/Rehype 插件。¥
markdownPlugins
- We use MDX in v2 instead of Remarkable. Your Markdown plugins have to be converted to Remark/Rehype plugins. -
manifest
-
onPageNav
- 现在默认打开此功能。¥
onPageNav
- This is turned on by default now. -
separateCss
- 可以按照上面提到的custom.css
同样的方式导入。¥
separateCss
- It can imported in the same manner ascustom.css
mentioned above. -
scrollToTop
-
scrollToTopOptions
-
translationRecruitingLink
-
twitter
-
twitterUsername
-
useEnglishUrl
-
users
-
usePrism
- 我们现在使用 Prisma 而不是 highlight.js¥
usePrism
- We now use Prism instead of highlight.js -
wrapPagesHTML
我们打算将来将许多已弃用的配置字段实现为插件。帮助将不胜感激!
¥We intend to implement many of the deprecated config fields as plugins in future. Help will be appreciated!
网址
¥Urls
在 v1 中,所有页面都可以使用或不使用 .html
扩展名。
¥In v1, all pages were available with or without the .html
extension.
例如,存在以下 2 个页面:
¥For example, these 2 pages exist:
如果 cleanUrl
是:
¥If cleanUrl
was:
-
true
:链接将定位到/installation
¥
true
: links would target/installation
-
false
:链接将定位到/installation.html
¥
false
: links would target/installation.html
在 v2 中,默认情况下,规范页面是 /installation
,而不是 /installation.html
。
¥In v2, by default, the canonical page is /installation
, and not /installation.html
.
如果你在 v1 中有 cleanUrl: false
,那么人们可能会发布到 /installation.html
的链接。
¥If you had cleanUrl: false
in v1, it's possible that people published links to /installation.html
.
出于 SEO 原因并避免破坏链接,你应该在托管提供商上配置服务器端重定向规则。
¥For SEO reasons, and avoiding breaking links, you should configure server-side redirect rules on your hosting provider.
作为应急方案,你可以使用 @docusaurus/plugin-client-redirects 创建从 /installation.html
到 /installation
的客户端重定向。
¥As an escape hatch, you could use @docusaurus/plugin-client-redirects to create client-side redirects from /installation.html
to /installation
.
module.exports = {
plugins: [
[
'@docusaurus/plugin-client-redirects',
{
fromExtensions: ['html'],
},
],
],
};
如果你想保留 .html
扩展名作为页面的规范 URL,文档可以声明 slug: installation.html
front Matter。
¥If you want to keep the .html
extension as the canonical URL of a page, docs can declare a slug: installation.html
front matter.
组件
¥Components
侧边栏
¥Sidebar
在之前的版本中,不允许嵌套侧边栏类别,并且侧边栏类别只能包含文档 ID。然而,v2 允许无限嵌套侧边栏,并且除了文档之外,我们还有许多类型的 侧边栏项目。
¥In previous version, nested sidebar category is not allowed and sidebar category can only contain doc ID. However, v2 allows infinite nested sidebar and we have many types of Sidebar Item other than document.
如果侧边栏包含类别类型,则必须迁移它。将 subcategory
重命名为 category
,将 ids
重命名为 items
。
¥You'll have to migrate your sidebar if it contains category type. Rename subcategory
to category
and ids
to items
.
{
- type: 'subcategory',
+ type: 'category',
label: 'My Example Subcategory',
+ items: ['doc1'],
- ids: ['doc1']
},
页脚
¥Footer
不再需要 website/core/Footer.js
。如果你想修改 Docusaurus 提供的默认页脚,swizzle:
¥website/core/Footer.js
is no longer needed. If you want to modify the default footer provided by Docusaurus, swizzle it:
- npm
- Yarn
- pnpm
npm run swizzle @docusaurus/theme-classic Footer
yarn swizzle @docusaurus/theme-classic Footer
pnpm run swizzle @docusaurus/theme-classic Footer
这会将主题当前使用的 <Footer />
组件复制到站点根目录下的 src/theme/Footer
目录中,然后你可以编辑此组件进行自定义。
¥This will copy the current <Footer />
component used by the theme to a src/theme/Footer
directory under the root of your site, you may then edit this component for customization.
不要仅仅为了在左侧添加徽标而调整页脚。该徽标在 v2 中被有意删除并移至底部。只需将 docusaurus.config.js
中的页脚配置为 themeConfig.footer
即可:
¥Do not swizzle the Footer just to add the logo on the left. The logo is intentionally removed in v2 and moved to the bottom. Just configure the footer in docusaurus.config.js
with themeConfig.footer
:
module.exports = {
themeConfig: {
footer: {
logo: {
alt: 'Meta Open Source Logo',
src: '/img/meta_oss_logo.png',
href: 'https://opensource.facebook.com',
},
},
},
};
页面
¥Pages
请参阅 创建页面 了解 Docusaurus 2 页面的工作原理。读完后,请注意你必须将 v1 中的 pages/en
文件移动到 src/pages
。
¥Please refer to creating pages to learn how Docusaurus 2 pages work. After reading that, notice that you have to move pages/en
files in v1 to src/pages
instead.
在 Docusaurus v1 中,页面接收 siteConfig
对象作为 props。
¥In Docusaurus v1, pages received the siteConfig
object as props.
在 Docusaurus v2 中,改为从 useDocusaurusContext
获取 siteConfig
对象。
¥In Docusaurus v2, get the siteConfig
object from useDocusaurusContext
instead.
在 v2 中,你必须在每个页面周围应用主题布局。布局组件采用元数据属性。
¥In v2, you have to apply the theme layout around each page. The Layout component takes metadata props.
CompLibrary
在 v2 中已被弃用,因此你必须编写自己的 React 组件或使用 Infima 样式(文档即将推出,对此感到抱歉!同时,请检查 V2 网站或查看 https://infima.dev/ 以查看可用的样式)。
¥CompLibrary
is deprecated in v2, so you have to write your own React component or use Infima styles (Docs will be available soon, sorry about that! In the meanwhile, inspect the V2 website or view https://infima.dev/ to see what styles are available).
你可以将 CommonJS 迁移到 ES6 导入/导出。
¥You can migrate CommonJS to ES6 imports/exports.
这是一个典型的 Docusaurus v2 页面:
¥Here's a typical Docusaurus v2 page:
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;
以下代码可能有助于各个页面的迁移:
¥The following code could be helpful for migration of various pages:
-
索引页 - Flux(推荐)、Docusaurus 2、Hermes
¥Index page - Flux (recommended), Docusaurus 2, Hermes
-
帮助/支持页面 - Docusaurus 2、Flux
¥Help/Support page - Docusaurus 2, Flux
内容
¥Content
替换 AUTOGENERATED_TABLE_OF_CONTENTS
¥Replace AUTOGENERATED_TABLE_OF_CONTENTS
该功能已被 内联目录 取代
¥This feature is replaced by inline table of content
更新 Markdown 语法以兼容 MDX
¥Update Markdown syntax to be MDX-compatible
在 Docusaurus 2 中,Markdown 语法已更改为 MDX。因此,现有文档中可能存在一些损坏的语法,你必须更新。一个常见的例子是像 <img>
和 <br>
这样在 HTML 中有效的自关闭标签现在必须显式关闭(<img/>
和 <br/>
)。MDX 文档中的所有标签都必须是有效的 JSX。
¥In Docusaurus 2, the Markdown syntax has been changed to MDX. Hence there might be some broken syntax in the existing docs which you would have to update. A common example is self-closing tags like <img>
and <br>
which are valid in HTML would have to be explicitly closed now ( <img/>
and <br/>
). All tags in MDX documents have to be valid JSX.
前面的内容由 gray-matter 解析。如果你的前文使用特殊字符(如 :
),你现在需要引用它:title: Part 1: my part1 title
→ title: "Part 1: my part1 title"
。
¥Front matter is parsed by gray-matter. If your front matter use special characters like :
, you now need to quote it: title: Part 1: my part1 title
→ title: "Part 1: my part1 title"
.
提示:你可能需要使用一些在线工具(例如 HTML 到 JSX)来使迁移更容易。
¥Tips: You might want to use some online tools like HTML to JSX to make the migration easier.
特定于语言的代码选项卡
¥Language-specific code tabs
请参阅 多语言支持代码块 部分。
¥Refer to the multi-language support code blocks section.
前言
¥Front matter
博客的 Docusaurus Front Matter 字段已从 CamelCase 更改为 Snake_Case,以与文档保持一致。
¥The Docusaurus front matter fields for the blog have been changed from camelCase to snake_case to be consistent with the docs.
字段 authorFBID
和 authorTwitter
已被弃用。它们仅用于生成作者的个人资料图片,这可以通过 authors
字段完成。
¥The fields authorFBID
and authorTwitter
have been deprecated. They are only used for generating the profile image of the author which can be done via the authors
field.
部署
¥Deployment
GitHub Pages 使用的 CNAME
文件不再生成,因此如果你使用自定义域,请确保你已在 /static/CNAME
中创建它。
¥The CNAME
file used by GitHub Pages is not generated anymore, so be sure you have created it in /static/CNAME
if you use a custom domain.
博客 RSS 源现在托管在 /blog/rss.xml
而不是 /blog/feed.xml
。你可能需要配置服务器端重定向,以便用户的订阅继续有效。
¥The blog RSS feed is now hosted at /blog/rss.xml
instead of /blog/feed.xml
. You may want to configure server-side redirects so that users' subscriptions keep working.
测试你的网站
¥Test your site
迁移后,你的文件夹结构应如下所示:
¥After migration, your folder structure should look like this:
my-project
├── docs
└── website
├── blog
├── src
│ ├── css
│ │ └── custom.css
│ └── pages
│ └── index.js
├── package.json
├── sidebars.json
├── .gitignore
├── docusaurus.config.js
└── static
启动开发服务器并修复所有错误:
¥Start the development server and fix any errors:
- npm
- Yarn
- pnpm
cd website
npm start
cd website
yarn start
cd website
pnpm start
你还可以尝试构建用于生产的站点:
¥You can also try to build the site for production:
- npm
- Yarn
- pnpm
npm run build
yarn build
pnpm run build