2.Getting Started

套用主题

欢迎来到我的网站

Installation

Docusaurus consists of a set of npm packages.

Use the Fast Track to understand Docusaurus in 5 minutes ⏱!

Requirements

Node.js version 18.0 or above (which can be checked by running node -v). You can use nvm for managing multiple Node versions on a single machine installed.
- When installing Node.js, you are recommended to check all checkboxes related to dependencies.

Scaffold project website 构建website项目

create a new directory containing the scaffolded files.

npx create-docusaurus@latest 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). You can get up and running extremely quickly with the classic template and customize things later on when you have gained more familiarity with Docusaurus.

备选安装方案: npm init docusaurus

Project structure

the following files generated under a new directory my-website/(安装时选择JS 或 TS,下面文件后缀名会有不同):

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

/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 the path 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 in sidebars.js. You can delete the directory if you’ve disabled the docs plugin, or you can change its name after setting the path option. More details can be found in the docs guide
/src/ - Non-documentation files like pages or custom React components. You don’t have to strictly put your non-documentation files here, but putting them under a centralized directory(集中式目录) makes it easier to specify in case you need to do some sort of linting/processing
- /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 final build directory
/docusaurus.config.js - A config file containing the site configuration. This is the equivalent of siteConfig.js in Docusaurus v1
/package.json - A Docusaurus website is a React app. You can install and use any npm packages you like in them
/sidebars.js - Used by the documentation to specify the order of documents in the sidebar

Running the development server

cd my-website
npm run start

open at http://localhost:3000.

Build

创建生产环境的文件 : npm run build

contents will be generated within the /build directory

Updating your Docusaurus version

推荐方法: 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": "3.2.1",
    "@docusaurus/preset-classic": "3.2.1",
    // ...
  }
}

然后, in the directory containing package.json, run your package manager’s install command:

npm install

最后,To check that the update occurred successfully, run: npx docusaurus --version

Configuration

The docusaurus.config.js file is run in Node.js and should export either:

a config object
a function that creates the config object

`docusaurus.config.js`里有哪些?

Site metadata

包含必要的全局元数据，如标题、url、baseUrl和favicon 等.
Deployment configurations(服务部署配置)

It is recommended to check the deployment docs for more information.
Theme, plugin, and preset configurations

有关配置主题、插件和预设的进一步帮助，请参见使用插件。
Custom configurations

为保护Docusaurus .config.js不受未知字段的影响。要添加自定义字段，请在customFields中定义它们。
docusaurus.config.js
```
export default {
  // ...
  customFields: {
    image: '',
    keywords: [],
  },
  // ...
};
```

Playground

Playgrounds allow you to run Docusaurus in your browser, without installing anything!

Use docusaurus.new as an easy-to-remember shortcut.

TypeScript Support

Docusaurus is written in TypeScript and provides first-class TypeScript support.

如果直接想通过TypeScript构成网站 : npx create-docusaurus@latest my-website classic --typescript