Tích hợp CSS Framework Material UI vào Docusaurus

Docusaurus - một công cụ tạo trang web tĩnh mã nguồn mở dựa trên React, nổi tiếng với khả năng tạo tài liệu, blog, trang web marketing và ứng dụng web một trang một cách nhanh chóng và dễ dàng. Điểm mạnh của Docusaurus nằm ở giao diện tích hợp sẵn, tài liệu chi tiết, hướng dẫn sử dụng, và cộng đồng người dùng lớn sẵn sàng hỗ trợ.

Kết hợp với Material UI, thư viện giao diện người dùng mã nguồn mở cũng dựa trên React, Docusaurus mang đến giải pháp hoàn hảo cho việc phát triển web hiện đại. Material UI cung cấp bộ sưu tập các thành phần giao diện người dùng đẹp mắt, hiện đại và dễ sử dụng, tuân theo nguyên tắc thiết kế Material của Google, đảm bảo tính nhất quán và trực quan cho giao diện.

Sự kết hợp này giúp bạn tạo ra các trang web và ứng dụng web không chỉ đẹp mắt, hiện đại mà còn dễ sử dụng, mang đến trải nghiệm tuyệt vời cho người dùng.

Hãy cùng tham khảo bài viết dưới đây để tích hợp Material UI vào Docusaurus.

Cài đặt Material UI

Đầu tiên, hãy di chuyển vào thư mục chứa dự án Docusaurus của bạn, sau đó cài đặt Material UI thông qua npm:

npm install @mui/material @emotion/react @emotion/styled

Tạo MUI color theme

Bước đầu tiên để tích hợp MUI vào Docusaurus, hãy sử dụng CSS theme variables. Nó cho phép bạn đồng bộ các biến cấu hình của MUI trong dự án Docusaurus.

Đầu tiên, ta tạo color scheme trong một component (đặt tên là MuiTheme). Ta nên để trong /src/components/MuiTheme/index.jsx. Cũng giống như MUI createTheme, bạn chỉ cần chỉ định các biến bạn muốn thay đổi theo mặc định.

Hãy tham khảo ví dụ dưới đây trong việc tạo theme.

import { experimental_extendTheme as extendTheme } from '@mui/material/styles';

const extTheme = extendTheme({
  colorSchemes: {
    light: {
      palette: {
        info: {
          main: '#cce5ff',
        },
      },
    },
    dark: {
      palette: {
        primary: {
          main: '#8b8bc6',
        },
        background: {
          paper: '#1d2144',
        },
      },
    },
  },
});

export default extTheme;

Áp dụng MUI vào trang web

Chúng ta cần import MUI theme và bọc nó trên toàn bộ trang web. Điều này có thể được thực hiện bằng cách sử dụng swizzing<Root> trong Docusaurus.

Swizzle thủ công bằng cách tạo một file Root.js ở /src/theme/Root.js. Sau đó thêm đoạn code dưới đây.

import React from "react";
import { getInitColorSchemeScript } from "@mui/material/styles";
import { Experimental_CssVarsProvider as CssVarsProvider } from "@mui/material/styles";
import theme from "@site/src/components/MuiTheme";

export default function Root({ children }) {
  return (
    <>
      {getInitColorSchemeScript()}
      <CssVarsProvider theme={theme}>{children}</CssVarsProvider>
    </>
  );
}

Kết hợp Docusaurus và MUI theme

Bây giờ, chúng ta cần xử lý logic đồng bộ hoá chế độ light/dark mode giữa Docusaurus với MUI.

Swizzling ColorModeToggle

Để đảm bảo tính đồng nhất, ColorModeToggle đã được tích hợp vào hệ thống bằng cách sử dụng tính năng swizzling của Docusaurus. Nhờ đó, chúng ta có thể bổ sung thêm các chức năng tùy chỉnh mà vẫn giữ nguyên bản chất của thành phần gốc. Component này được đánh dấu là "safe" để đảm bảo quá trình swizzling diễn ra suôn sẻ. Tham khảo tài liệu Docusaurus Swizzling để tìm hiểu thêm về tính năng này.

Chạy lệnh sau để swizzle component ColorModeToggle:

npm run swizzle @docusaurus/theme-classic ColorModeToggle -- --wrap

Nó sẽ tạo một component ColorModeToggle ở /src/theme/ColorModeToggle/index.js.

Đồng bộ giao diện

Bên trong file index.js (/src/theme/ColorModeToggle/index.js), bạn có thể thêm tính năng chuyển đổi light/dark mode theo code bên dưới:

import React, { useEffect } from "react";
import ColorModeToggle from "@theme-original/ColorModeToggle";
import { useColorScheme } from "@mui/material/styles";

export default function ColorModeToggleWrapper(props) {
  // MUI color mode setting
  const { setMode } = useColorScheme();

  // "value" holds the color theme. Either "light" or "dark"
  const { value } = props;

  // change mode based on "value" prop
  // "dark" or "light" are also used for MUI
  useEffect(() => {
    setMode(value);
  }, [value]);

  return (
    <>
      <ColorModeToggle {...props} />
    </>
  );
}

Sử dụng MUI theme ở khắp mọi nơi

Bây giờ MUI đã được đồng bộ trong dự án Docusaurus. Bạn có thể tạo bất kỳ component nào sử dụng MUI.

import Container from "@mui/system/Container";
import Card from "@mui/material/Card";
import Grid from "@mui/material/Grid";
import Typography from "@mui/material/Typography";
import { Experimental_CssVarsProvider as CssVarsProvider } from "@mui/material/styles";
import theme from "@site/src/components/MuiTheme";

<Grid container justifyContent="center" sx={{ paddingBottom: 4 }}>
  <Grid item xs={12}>
    <Card
      variant="outlined"
      sx={{
        textAlign: "center",
        boxShadow: 3,
      }}
    >
      <Typography variant="h4" sx={{ color: "primary.main" }}>
        This is an example
      </Typography>
    </Card>
  </Grid>
</Grid>;

Demo

Bạn có thể thao khảo repo docusaurus-material-ui-template mà mình đã tạo. Trong dự án này đã tích hợp Material UI vào Docusaurus. Bên cạnh đó, mình đã custom lại giao diện, tạo 1 plugin giúp đem blog hiện thị ở ngoài homepage.

👉 Xem thông tin chi tiết repo ở README.md