Skip to main content

Docusaurus

Project structure​

.
├── blog
├── docs
├── docusaurus.config.js
├── node_modules
├── package.json
├── README.md
├── sidebars.js
├── src
│  ├── components
│  │  └── HomepageFeatures
│  ├── css
│  │  └── custom.css
│  └── pages
├── static
│  └── img
├── tsconfig.json
└── yarn.lock

Blog​

.
├── blog
│  ├── 2019-05-28-first-blog-post.md
│  ├── 2019-05-29-long-blog-post.md
│  ├── 2021-08-01-mdx-blog-post.mdx
│  ├── 2021-08-26-welcome
│  │  ├── docusaurus-plushie-banner.jpeg
│  │  └── index.md
│  └── authors.yml
  • authors.yml
    • 著者の情報を保存してブログページにいい感じに表示してくれる
    • Blog 本文の frontMatter に直接書いてもOK
endi:
  name: Endilie Yacop Sucipto
  title: Maintainer of Docusaurus
  url: https://github.com/endiliey
  image_url: https://github.com/endiliey.png

yangshun:
  name: Yangshun Tay
  title: Front End Engineer @ Facebook
  url: https://github.com/yangshun
  image_url: https://github.com/yangshun.png

slorber:
  name: Sébastien Lorber
  title: Docusaurus maintainer
  url: https://sebastienlorber.com
  image_url: https://github.com/slorber.png
  • ブログ本文
    • first-blog.md でも first-blog/index.md でもOK
    • frontMatter
      • slug: URL に表示される path の名前
      • date: 日付を書けば反映される。ファイル名を 2023-08-01-first-blog.md のようにすればなくても平気
      • title, authors, tags: そのまま。
      • category はないみたい。
---
slug: welcome
title: Welcome
authors: [slorber, yangshun]
tags: [facebook, hello, docusaurus]
---

contents
  • https://example.com/blog にアクセスするとブログのリストが出てくるが、ブログが長すぎたときに <!-- truncate --> 以下を表示しないようにできる。
  • Markdown 内で React の機能を使うことができる(?) MDX という拡張形式を使うことができる。

Document​

├── docs
│  ├── intro.md
│  ├── tutorial-basics
│  │  ├── _category_.json
│  │  ├── congratulations.md
│  │  ├── create-a-blog-post.md
│  │  ├── create-a-document.md
│  │  ├── create-a-page.md
│  │  ├── deploy-your-site.md
│  │  └── markdown-features.mdx
│  └── tutorial-extras
│     ├── _category_.json
│     ├── img
│     ├── manage-docs-versions.md
│     └── translate-your-site.md
  • docs/ 直下に intro.md のように直接ファイルを置いてもいいし、ディレクトリを挟んでもいい
  • docs/title.md, docs/title/index.md のどちらでもいい
  • _category_.json でサイドバーの設定ができる
    • label: 表示名
    • position: 順番
    • link: generated-index にすると小ページのリンクがパネル形式で表示される
{
  "label": "Tutorial - Basics",
  "position": 2,
  "link": {
    "type": "generated-index",
    "description": "5 minutes to learn the most important Docusaurus concepts."
  }
}
  • ドキュメントの frontmatter
    • sidebar_position: label 内での表示順序を指定
    • slug: URL の path 指定
    • title: sidebar, パンくずリストに表示されるタイトル。指定しない場合は md 内の # title が入る。
    • sidebar_label: docs 直下に作成した場合にlabel を指定する
---
sidebar_position: 2
slug: hello
title: short title
---

# Very looooooooooooooooooooooooooooong title

Page​

├── src
│  ├── components
│  │  └── HomepageFeatures
│  ├── css
│  │  └── custom.css
│  └── pages
│     ├── index.module.css
│     ├── index.tsx
│     ├── markdown-page.md
│     └── my-react-page.js
  • docs, blog 以外に独立してページを作成する場合に使用する
  • src/pages/index.* -> /, src/pages/foo.md -> /foo のように対応する

Markdown features​

Admonitions​

:::tip[My tip]
Use this awesome feature option
:::

:::info
info
:::

:::caution
caution
:::

:::danger[Take care]
This action is dangerous
:::

Code block​

  • ファイル名の表示
```jsx title="src/components/HelloDocusaurus.js"
function HelloDocusaurus() {
    return (
        <h1>Hello, Docusaurus!</h1>
    )
}
```
  • ハイライト
```js title="sidebars.js"
module.exports = {
  tutorialSidebar: [
    'intro',
    // highlight-next-line
    'hello',
    {
      type: 'category',
      label: 'Tutorial',
      items: ['tutorial-basics/create-a-document'],
    },
  ],
};
```
```text title="my-doc.md"
// highlight-start
---
id: my-doc-id
title: My document title
description: My document description
slug: /my-custom-url
---
// highlight-end

## Markdown heading

Markdown text with [links](./hello.md)
```

i18n​

  • 各言語に対応した docs のファイルは i18n/locale/docusaurus-plugin-content-docs/current に保存する。
  • blog, pages は current なし。
.
├── babel.config.js
├── blog
│  ├── 2019-05-28-first-blog-post.md
│  ├── 2019-05-29-long-blog-post.md
│  ├── 2021-08-01-mdx-blog-post.mdx
│  ├── 2021-08-26-welcome
│  └── authors.yml
├── docs
│  ├── intro.md
│  ├── tutorial-basics
│  └── tutorial-extras
├── docusaurus.config.js
├── i18n
│  └── en
│     ├── docusaurus-plugin-content-docs  <-- english version of docs
│     │  └── current
│     │     ├── intro.md
│     │     ├── tutorial-basics
│     │     └── tutorial-extras
│     ├── docusaurus-plugin-content-blog  <-- english version of blog
│     │  ├── 2019-05-28-first-blog-post.md
│     │  ├── 2019-05-29-long-blog-post.md
│     │  ├── 2021-08-01-mdx-blog-post.mdx
│     │  ├── 2021-08-26-welcome
│     │  └── authors.yml
│     └── socusaurus-plugin-content-pages <-- english version of pages
│        ├── index.module.css
│        ├── index.tsx
│        ├── markdown-page.md
│        └── my-react-page.js
├── package.json
├── README.md
├── sidebars.js
├── src
│  ├── components
│  │  └── HomepageFeatures
│  ├── css
│  │  └── custom.css
│  └── pages
│     ├── index.module.css
│     ├── index.tsx
│     ├── markdown-page.md
│     └── my-react-page.js

  • 検索機能はいくつか方法がある（Search）

    • Local search の場合は下記リンクのプラグインを使える
    • Local Search

  • docusaurus-lunr-search を使う場合は下記を実行

yarn add docusaurus-lunr-search
  • docusaurus.config.js にプラグインを追加する。
module.exports = {
  // ...
  plugins: [require.resolve('docusaurus-lunr-search')],
}