Cấu hình

Cấu hình Thông tin Kiểm tra tài liệu tham khảo API docusaurus.config.js để biết danh sách đầy đủ các tùy chọn.

Docusaurus có một cách độc đáo về cấu hình. Chúng tôi khuyến khích bạn tập hợp thông tin về trang web của mình vào một nơi. Chúng tôi bảo vệ các trường của tệp này và tạo điều kiện cho đối tượng dữ liệu này có thể truy cập được trên trang web của bạn.

Giữ một sự bảo trì tốt giúp bạn, cộng tác viên của bạn và những người đóng góp nguồn mở của bạn có thể tập trung vào tài liệu trong khi vẫn có thể tùy chỉnh trang web.docusaurus.config.js

Cú pháp để khai báo docusaurus.config.js Tệp được chạy trong Node.js và nên xuất:docusaurus.config.js

một đối tượng cấu hình một hàm tạo đối tượng config Thông tin Tệp hỗ trợ:docusaurus.config.js

Mô-đun ES CommonJS Tập lệnh đánh máy Ràng buộc:

Bắt buộc: sử dụng (hoặc ) để xuất cấu hình Docusaurus của bạnexport default /* your config*/module.exports Tùy chọn: sử dụng (hoặc) để nhập gói Node.jsimport Lib from 'lib'require('lib') Docusaurus cung cấp cho chúng ta khả năng khai báo cấu hình của nó theo nhiều cách tương đương khác nhau và tất cả các ví dụ cấu hình sau đây đều dẫn đến kết quả giống hệt nhau:

docusaurus.config.js

export default {
  title: 'Docusaurus',
  url: 'https://docusaurus.io',
  // your site config ...
};

docusaurus.config.js

module.exports = {
  title: 'Docusaurus',
  url: 'https://docusaurus.io',
  // your site config ...
};

docusaurus.config.ts

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

export default {
  title: 'Docusaurus',
  url: 'https://docusaurus.io',
  // your site config ...
} satisfies Config;

docusaurus.config.js

const config = {
  title: 'Docusaurus',
  url: 'https://docusaurus.io',
  // your site config ...
};

export default config;

docusaurus.config.js

export default function configCreator() {
  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.io',
    // your site config ...
  };
}

docusaurus.config.js

export default async function createConfigAsync() {
  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.io',
    // your site config ...
  };
}

Sử dụng các gói chỉ dành cho ESM Sử dụng trình tạo cấu hình không đồng bộ có thể hữu ích để nhập các mô-đun chỉ dành cho ESM (đáng chú ý là hầu hết các plugin Remark). Có thể nhập các mô-đun như vậy nhờ nhập động:

docusaurus.config.js

export default async function createConfigAsync() {
  // Use a dynamic import instead of require('esm-lib')
  const lib = await import('lib');

  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.io',
    // rest of your site config...
  };
}

Những gì đi vào ? docusaurus.config.js Bạn không cần phải viết từ đầu ngay cả khi bạn đang phát triển trang web của mình. Tất cả các mẫu đều đi kèm với một bao gồm mặc định cho các tùy chọn phổ biến.docusaurus.config.jsdocusaurus.config.js

Tuy nhiên, nó có thể hữu ích nếu bạn có hiểu biết cấp cao về cách các cấu hình được thiết kế và triển khai.

Tổng quan cấp cao về cấu hình Docusaurus có thể được phân loại thành:

Siêu dữ liệu trang web Cấu hình triển khai Chủ đề, plugin và cấu hình đặt trước Cấu hình tùy chỉnh Siêu dữ liệu trang web Siêu dữ liệu trang web chứa siêu dữ liệu toàn cầu thiết yếu như , , và .titleurlbaseUrlfavicon

Chúng được sử dụng ở một số nơi như tiêu đề và tiêu đề trang web của bạn, biểu tượng tab trình duyệt, thông tin chia sẻ xã hội (Facebook, X) hoặc thậm chí để tạo đường dẫn chính xác để phục vụ các tệp tĩnh của bạn.

Cấu hình triển khai Các cấu hình triển khai như , và tùy chọn được sử dụng khi bạn triển khai trang web của mình bằng lệnh.projectNameorganizationNamedeploymentBranchdeploy

Bạn nên kiểm tra tài liệu triển khai để biết thêm thông tin.

Chủ đề, plugin và cấu hình đặt trước Liệt kê các chủ đề, plugin và cài đặt trước cho trang web của bạn trong các trường , , và tương ứng. Đây thường là các gói npm:themespluginspresets

docusaurus.config.js

export default {
  // ...
  plugins: [
    '@docusaurus/plugin-content-blog',
    '@docusaurus/plugin-content-pages',
  ],
  themes: ['@docusaurus/theme-classic'],
};

mẹo Docusaurus hỗ trợ viết tắt mô-đun, cho phép bạn đơn giản hóa cấu hình trên như sau:

docusaurus.config.js

export default {
  // ...
  plugins: ['content-blog', 'content-pages'],
  themes: ['classic'],
};

Chúng cũng có thể được tải từ các thư mục cục bộ:

docusaurus.config.js

import path from 'path';

export default {
  // ...
  themes: [path.resolve(__dirname, '/path/to/docusaurus-local-theme')],
};

Để chỉ định các tùy chọn cho plugin hoặc theme, hãy thay thế tên của plugin hoặc theme trong tệp cấu hình bằng một mảng chứa tên và đối tượng options:

docusaurus.config.js

export default {
  // ...
  plugins: [
    [
      'content-blog',
      {
        path: 'blog',
        routeBasePath: 'blog',
        include: ['*.md', '*.mdx'],
        // ...
      },
    ],
    'content-pages',
  ],
};

Để chỉ định các tùy chọn cho plugin hoặc chủ đề được đóng gói trong cài đặt trước, hãy chuyển các tùy chọn qua trường. Trong ví dụ này, đề cập đến và đề cập đến .presetsdocs@docusaurus/plugin-content-docstheme@docusaurus/theme-classic

docusaurus.config.js
export default {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: './sidebars.js',
        },
        theme: {
          customCss: ['./src/css/custom.css'],
        },
      },
    ],
  ],
};

mẹo Viết tắt cũng hoạt động

.presets: [['classic', {...}]]

Để được trợ giúp thêm về việc định cấu hình chủ đề, plugin và cài đặt trước, hãy xem Sử dụng Plugin.

Cấu hình tùy chỉnh Docusaurus bảo vệ từ những cánh đồng không xác định. Để thêm các trường tùy chỉnh, hãy xác định chúng trong .docusaurus.config.jscustomFields

Ví dụ:

docusaurus.config.js
export default {
  // ...
  customFields: {
    image: '',
    keywords: [],
  },
  // ...
};

Truy cập cấu hình từ các thành phần Đối tượng cấu hình của bạn sẽ được cung cấp cho tất cả các thành phần của trang web của bạn. Và bạn có thể truy cập chúng thông qua ngữ cảnh React dưới dạng .siteConfig

Ví dụ cơ bản:

import React from 'react';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';

const Hello = () => {
  const {siteConfig} = useDocusaurusContext();
  const {title, tagline} = siteConfig;

  return <div>{`${title} · ${tagline}`}</div>;
};

mẹo Nếu bạn chỉ muốn sử dụng các trường đó ở phía máy khách, bạn có thể tạo các tệp JS của riêng mình và nhập chúng dưới dạng mô-đun ES6, không cần phải đặt chúng vào .docusaurus.config.js

Tùy chỉnh cấu hình Babel Docusaurus chuyển mã nguồn trang web của bạn bằng cách sử dụng Babel theo mặc định. Nếu bạn muốn tùy chỉnh cấu hình Babel, bạn có thể làm như vậy bằng cách tạo một tệp trong gốc dự án của bạn.babel.config.js

Để sử dụng cài đặt trước tích hợp làm cấu hình cơ sở, hãy cài đặt gói sau và sử dụng nó

npm Yarn pnpm

npm install --save @docusaurus/babel

Sau đó, sử dụng cài đặt trước trong tệp của bạn:babel.config.js

babel.config.js

export default {
  presets: ['@docusaurus/babel/preset'],
};

Hầu hết thời gian, cấu hình đặt trước mặc định sẽ hoạt động tốt. Nếu bạn muốn tùy chỉnh cấu hình Babel của mình (ví dụ: để thêm hỗ trợ cho Flow), bạn có thể chỉnh sửa trực tiếp tệp này. Để các thay đổi của bạn có hiệu lực, bạn cần khởi động lại máy chủ phát triển Docusaurus.