[Note] Docusaurus

本專案使用 v3.4.0 版本

Docusaurus 是一個靜態網站生成器 (static-site-generator)。由 Facebook 開發，基於 React 和 Markdown，專為建立技術文件、開發者部落格而生。

基於 Next.js 和 React，可自製 React component 和 layout
支援 Markdown
支援插件：支援搜尋（Algolia）、分析（Google Analytics）等功能
支援多語系 (i18n)

Installation

CLI | Docusaurus

建立專案 檢查 Node 版本：使用 Node.js 18 或以上

$ node -v

建立專案：

$ npx create-docusaurus@latest my-website classic --typescript -p pnpm
$ cd my-website
$ npx docusaurus -V    # 查看版本
$ pnpm run start       # 啟動專案

這裡安裝的是 v3.4.0 的

classic範本
-t, --typescript：搭配 Typescript
-p, --package-manager: 使用 pnpm（可以是 npm, yarn, pnpm 或 bun）

Folder Structure

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/：存放 blog 文章
/docs/：存放 doc 文件
/src/：存放非文件的相關資產，像是 /pages/ 資料夾用來存放 homepage、about 等頁面，/components/資料夾用來存放共用的元件
/static/：存放靜態資料，像是圖片
/docusaurus.config.js：網站的設定檔
package.json： Docusaurus 是一個 React app，可以安裝任何需要的 npm package
sidebars.js：用於 doc 的側邊欄，可以自行建立新的側邊欄，也可以使用自動生成(autogenerated) 的側邊欄

Docusaurus Configurations

docusaurus.config.js

docusaurus.config.ts
import type { Config } from '@docusaurus/types';

export default {
    title: 'Docusaurus',
    tagline: 'Dinosaurs are cool',
    favicon: 'img/favicon.ico',
    // Set the production url of your site here
    url: 'https://your-docusaurus-site.example.com',
    // Set the /<baseUrl>/ pathname under which your site is served
    // For GitHub pages deployment, it is often '/<projectName>/'
    baseUrl: '/',

    // GitHub repo 相關設定，沒有要使用 `docusaurus deploy` 可以不用設定
    organizationName: 'facebook', // GitHub repo 的 user 或 organization 名稱
    projectName: 'docusaurus', // GitHub repo 的名稱

    // your site config ...
} satisfies Config;

Docusaurus 的配置檔包含：

網站 metadata：像是 title、tagline、url、baseUrl、favicon...等
部署相關設定 (Deployment configurations)：像是 organizationName、projectName、deploymentBranch⋯⋯等（詳見 Deployment）
各種 Theme, plugin⋯⋯等配置設定

Docs 文件

建立新文件

在 /docs 資料夾建立一個新的 markdown 文件（.md 或 .mdx）。

website # root directory of your site
├── docs
│   ├── my-first-doc.md # 直接在 docs 底下新增 .md 文件
│   └── categoryName # 在 docs 底下建立子分類資料夾
│       ├── page1.md # 在子分類下新增子文件
│       └── page2.md
├── src
│   └── pages
├── docusaurus.config.js
├── ...

Sidebar

在文件 metadata 中設定 sidebar 的 label 與 position：

docs/my-first-doc.md
---
sidebar_label: 'My First Doc' # 文件在 sidebar 的名稱
sidebar_position: 1 # 文件在 sidebar 的位置
---

Docusaurus 會根據 docs 資料夾結構自動產生 sidebar：

sidebar.ts
export default {
    tutorialSidebar: [
        {
            type: 'autogenerated',
            dirName: '.', // 從 docs 資料夾自動產生 sidebar
        },
    ],
};

也可以手動設定 sidebar 的結構：

sidebar.ts
export default {
    tutorialSidebar: [
        'intro',
        'hello',
        {
            type: 'category',
            label: 'Tutorial',
            items: ['tutorial-basics/create-a-document'],
        },
    ],
};

[!NOTE]

更複雜的 Sidebar 設置可以參考 Docusaurus 自家網站的配置：https://docusaurus.io/docs/sidebar#complex-sidebars-example

https://docusaurus.io/docs/sidebar/items

Sidebar item 的 type 可以分成這幾種：

doc：連到 doc 頁面
link：連到內部或外部的頁面
category：可展開的階層式 dropdown
autogenerated：自動建立 sidebar items
html：渲染 pure HTML
ref：連到 doc

`DocCardList`

docs/dievar/index.md
import DocCardList from '@theme/DocCardList';

<DocCardList />

![image-20240909170856963](/Users/yachu_hsieh/Library/Application Support/typora-user-images/image-20240909170856963.png)

Category item metadata

在 category 資料夾內建立 _category_.json 或 _category_.yml 設定檔，來設定 sidebar 分類的名稱、描述。

_category_.json
{
  "label": "分類 A",
  "position": 2,
  "collapsible": true,
  "collapsed": false,
  "className": "red",
  "link": {
    "type": "generated-index",
    "title": "分類連結的名稱"
    "description": "分類的描述"
  },
  "customProps": {
    description: "This description can be used in the swizzled DocCard"
  }
}

label：分類在 sidebar 的名稱
position：分類在 sidebar 的位置
link：為分類建立一個單獨的連結

Markdown Features

Markdown Features

MDX

MDX (Markdown + JSX) 是一種結合了 Markdown 與 JSX 的標記式語言，讓使用者能夠在 Markdown 文件內容中使用 React 元件。Docusaurus 內建的 MDX compiler 會將 Markdown 文件轉換成 React components，因此我們可以在 Markdown 中撰寫 JSX（使用 JavaScript 邏輯與變數、插入 React 元件、將元件和內容模組化⋯⋯等）。

MDX compiler 支援 .md 與 .mdx 格式。為了一致性，Docusaurus v3 預設將所有檔案（不管事 .md 還是 .mdx 檔案）視為 MDX 格式處理。這樣做的好處是可以：

向後相容：即使過去使用了 .md 檔案，Docusaurus 也會將其視為 MDX 檔案來處理，以確保使用者可以隨時插入 React 元件。
簡化使用者體驗：使用者不必特別區分文件格式，預設會使用 MDX 處理所有 .md 和 .mdx 檔案。

MDX & React Components

在 Markdown 中使用 React components：

export const Highlight = ({children, color}) => (
<span
style={{
      backgroundColor: color,
      borderRadius: '20px',
      color: '#fff',
      padding: '10px',
      cursor: 'pointer',
    }}
onClick={() => {
alert(`You clicked the color ${color} with label ${children}`)
}}>
{children}
</span>
);

This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !

This is <Highlight color="#1877F2">Facebook blue</Highlight> !

Front Matter

Markdown 文件最上方是 Front Matter，以 YAML 格式撰寫、包覆在 --- 中。用來為 Markdown 文章加上 metadata，來設定文件的標題、標籤(tags)、位置等。

my-first-doc.md
---
title: 'my-first-doc' # 文件標題
description: 'This is my first doc' # 文件描述
tags: [npm, docusaurus] # 標籤
slug: /my-first-doc # 用來修改文件的 slug url，不寫的話默認為文件名
---

Standard Features

Links

使用 url path：

Let's see how to [Create a page](/create-a-page).

或是 relative path：

Let's see how to [Create a page](./create-a-page.md).

Images

使用絕對路徑：

![Docusaurus logo](/img/docusaurus.png)

Code Blocks

Title

```js title="src/檔案位置/這邊可以放標題"
// your code...
function HelloDocusaurus() {
  return <h1>Hello, Docusaurus!</h1>;
}
```

src/檔案位置/這邊可以放標題
// your code...
function HelloDocusaurus() {
    return <h1>Hello, Docusaurus!</h1>;
}

Line Highlighting

透過註解加上標記 (Highlighting with comments)

在 code block 中透過「註解」的方式來替特定行數畫記重點，這些註解並不會在最後顯示在程式碼區塊中：

使用 // highlight-next-line 標記下一行
使用 // highlight-start 與 // highlight-end 標記範圍之內的程式碼

```js
function HighlightNextLine(highlight) {
    if (highlight) {
        // highlight-next-line
        return 'This line is highlighted!';
    }

    return 'Nothing highlighted';
}

function HighlightMultipleLines(highlight) {
    // highlight-start
    if (highlight) {
        return 'This range is highlighted!';
    }
    // highlight-end

    return 'Nothing highlighted';
}
```

function HighlightNextLine(highlight) {
    if (highlight) {
        return 'This line is highlighted!';
    }

    return 'Nothing highlighted';
}

function HighlightMultipleLines(highlight) {
    if (highlight) {
        return 'This range is highlighted!';
    }

    return 'Nothing highlighted';
}

透過 metadata 加上標記 (Highlighting with metadata string)

在 code block 的語言後加入 metadata string 指定要 highlight 的行數：/```<語言> <metadata string>

單行（例如 3）
多行：用逗號 , 分隔行號（例如 1, 3, 5）
範圍：用範圍語法 - （例如 2-4）

Docusaurus 使用了 parse-number-range 這個 library 來解析 metadata string 中的行數語法。

```jsx {1,4-6,11}
import React from 'react';

function MyComponent(props) {
  if (props.isBar) {
    return <div>Bar</div>;
  }

  return <div>Foo</div>;
}

export default MyComponent;

```jsx {1,4-6,11}
import React from 'react';

function MyComponent(props) {
if (props.isBar) {
return <div>Bar</div>;
}

return <div>Foo</div>;
}

export default MyComponent;

警告／提示區塊 Admonitions

:::tip[My tip]

Use this awesome feature option

:::

:::danger[Take care]

This action is dangerous

:::

My tip

Use this awesome feature option

Take care

This action is dangerous

Docs-only mode

https://docusaurus.io/docs/docs-introduction#docs-only-mode

到 docusaurus.config.js 設定檔 -> presets -> docs 加上 routeBasePath: '/' 設定為網站的 root。

docusaurus.config.js
export default {
    // ...
    presets: [
        [
            '@docusaurus/preset-classic',
            {
                docs: {
                    routeBasePath: '/', // Serve the docs at the site's root
                    /* other docs plugin options */
                },
                blog: false, // Optional: disable the blog plugin
                // ...
            },
        ],
    ],
};

Installation​

Folder Structure​

Docusaurus Configurations​

Docs 文件​

建立新文件​

Sidebar​

Sidebar items​

DocCardList​

Category item metadata​

Markdown Features​

MDX​

MDX & React Components​

Front Matter​

Standard Features​

Links​

Images​

Code Blocks​

Title​

Line Highlighting​

透過註解加上標記 (Highlighting with comments)​

透過 metadata 加上標記 (Highlighting with metadata string)​

警告／提示區塊 Admonitions​

Docs-only mode​

Installation

Folder Structure

Docusaurus Configurations

Docs 文件

建立新文件

Sidebar

Sidebar items

`DocCardList`

Category item metadata

Markdown Features

MDX

MDX & React Components

Front Matter

Standard Features

Links

Images

Code Blocks

Title

Line Highlighting

透過註解加上標記 (Highlighting with comments)

透過 metadata 加上標記 (Highlighting with metadata string)

警告／提示區塊 Admonitions

Docs-only mode