Skip to main content

インストール

Docusaurus consists of 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!

要件​

  • Node.js version 20.0 or above (which can be checked by running node -v). You can use nvm to manage multiple Node.js versions on a single machine.
    • When installing Node.js, it is recommended to check all checkboxes related to dependencies.

プロジェクトの足場作り​

Docusaurusをインストールする最も簡単な方法は、create-docusaurusコマンドラインツールを使用することです。このツールを使えば、Docusaurusウェブサイトの基本構造が自動的に生成され、すぐに開発を始められる状態になります。 このコマンドは、新しい空のリポジトリ内でも、既存のリポジトリ内でも、どこでも実行でき、雛形ファイルを含む新しいディレクトリが作成されます。

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). 標準的（classic）なテンプレートを使えばすぐに使い始めて、Docusaurusに慣れてきた頃にはカスタマイズをすることができます。

You can also use the template's TypeScript variant by passing the --typescript flag. See TypeScript support for more information.

npx create-docusaurus@latest my-website classic --typescript
Meta-Only

Metaオープンソースプロジェクトのために新しいDocusaurusウェブサイトをセットアップする場合、以下のコマンドを内部リポジトリ内で実行すると、Meta固有の便利な初期設定がいくつか付属してきます。

scarf static-docs-bootstrap
Alternative installation commands

また、お好みのプロジェクトマネージャを使用して新しいプロジェクトを初期化することもできます。

npm init docusaurus

Run npx create-docusaurus@latest --help, or check out its API docs for more information about all available flags.

プロジェクト構造​

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

プロジェクト構造の概要​

  • /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. ドキュメント以外のファイルを厳密にここに置く必要はありませんが、一元化されたディレクトリの下に置くことで、何らかのリントまたは処理を行う必要がある場合に指定しやすくなります。
    • /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 it.
  • /sidebars.js - Used by the documentation to specify the order of documents in the sidebar

単一リポジトリ（Monorepo・モノレポ）​

既存のプロジェクトのドキュメント作成にDocusaurusを使用している場合、モノレポが解決策になるかもしれません。 モノレポは、類似のプロジェクト間で依存関係を共有することを可能にします。 例えば、ウェブサイトでは、リリースされたバージョンに依存する代わりに、ローカルパッケージを使用して最新の機能を紹介することができます。 そうすれば、コントリビューターは機能を実装するたびにドキュメントを更新することができます。 モノレポのフォルダー構造の例を以下に示します。

my-monorepo
├── package-a # 別パッケージ（本体プロジェクト）
│   ├── src
│   └── package.json # パッケージAの依存関係
├── website   # Docusaurusのルート
│   ├── docs
│   ├── src
│   └── package.json # Docusaurusの依存関係
├── package.json # モノレポ内で共有された依存関係

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 check out Docusaurus and Jest for some real-world examples.

開発サーバーの実行​

ファイルを編集しながら変更点を確認するには、Webサイトを配信し、最新の変更点を反映させるローカル開発サーバーを実行するとよいでしょう。

cd my-website
npm run start

By default, a browser window will open at http://localhost:3000.

おめでとうございます！ 最初のDocusaurusサイトを作成できました！ サイト内を閲覧して何があるかを確認しましょう。

ビルド​

Docusaurus is a modern static website generator, so we need to build the website into a directory of static contents and put it on a web server so that it can be viewed. ウェブサイトをビルドするには以下のコマンドを実行します。

npm 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.

Docusaurusバージョンの更新​

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.

情報

未リリースバージョンのドキュメントを参照しています。未リリースの機能を使用したい場合は、 @canary リリース を使用できます。

package.json
{
  "dependencies": {
    "@docusaurus/core": "current",
    "@docusaurus/preset-classic": "current",
    // ...
  }
}

Then, in the directory containing package.json, run your package manager's install command:

npm install
ヒント

npm install may report several vulnerabilities and recommend running npm audit to address them. 通常の場合、報告された脆弱性、例えば正規表現DoS脆弱性（訳注：ReDosとも）のようなものは無害であり、安全に無視することができます。 Also read this article, which reflects our thinking: npm audit: Broken by Design.

アップデートが正常に行われたことを確認するために、以下のコマンドを実行します。

npx docusaurus --version

出力として正しいバージョンが表示されるはずです。

また、Yarnを使っている場合は、以下のようにすることもできます。

yarn add @docusaurus/core @docusaurus/preset-classic
ヒント

Use new unreleased features of Docusaurus with the @canary npm dist tag

お困りですか？ ​

Ask for help on Stack Overflow, on our GitHub repository, our Discord server, or X.