4 posts tagged with "guide"

Docusaurus has React Router v5 built-in, but it doesn't support dynamic routes. This guide will show you how to add dynamic routes to Docusaurus.

What is a dynamic route? The most common example is a blog. You have a list of blogs and you want to render a page for each blog. You can't do this with static routes. Then you can construct a dynamic route like /blog/:blogId and render a page, with blogId as a parameter.

Getting Started​

There are several steps to add dynamic routes to Docusaurus:

• Create a Docusaurus plugin to add your dynamic routes.
• A React component to render the page.

With these steps, we will build a dynamic route to view books. The route will be /books/:bookId. Our final result will look like this:

Install react-router-dom​

By default, Docusaurus exports only useHistory, useLocation, Redirect, and matchPath from react-router-dom. To use Route and Switch, you need to install react-router-dom manually:

pnpm add react-router-dom@5.3.4

Create a Docusaurus Plugin​

Docusaurus has an action addRoute from contentLoaded plugin method to add your route to the website. But instead of using this action to add a single route, we can create our custom plugin to add multiple routes:

module.exports = function dynamicRoutePlugin(context, options) {
  return {
    name: 'plugin-dynamic-route',
    contentLoaded({ actions }) {
      const { routes } = options;
      const { addRoute } = actions;

      routes.forEach((route) => addRoute(route));
    },
  };
};

Then we can add this plugin to docusaurus.config.js:

const config = {
  plugins: [
    [
      './src/plugins/plugin-dynamic-route/index.js',
      {
        routes: [
          {
            // using Route schema from react-router
            path: '/books',
            exact: false, // this is needed for sub-routes to match!
            component: '@site/src/components/layouts/BookLayout/index',
          },
        ],
      },
    ],
  ],
};

We will create the BookLayout component in the next step.

Render Book page​

First, we will create an index page to list all books:

import React from 'react';

const BookPage = () => {
  return (
    <div>
      <h1>Books</h1>
      <ul>
        <li>
          <a href="/books/1">Book 1</a>
        </li>
        <li>
          <a href="/books/2">Book 2</a>
        </li>
      </ul>
    </div>
  );
};

export { BookPage };

Then create a page for the individual book:

import React from 'react';
import { useRouteMatch } from 'react-router-dom';

const BookDetail = () => {
  const match = useRouteMatch();
  const { bookId } = match.params;
  return <div>This is book {bookId}</div>;
};

export { BookDetail };

Finally, create a layout component to handle the routing for book pages:

• Wrap the content with the Layout component from Docusaurus.
• Use Switch and Route from react-router-dom to render the correct page based on the route.
• Use the NotFound component from Docusaurus to render a 404 page if the route is not found.

import Layout from '@theme/Layout';
import NotFound from '@theme/NotFound';
import React from 'react';
import { Route, Switch, useRouteMatch } from 'react-router-dom';
import { BookDetail } from '@site/src/pages/_books/[bookId]';
import { BookPage } from '@site/src/pages/_books/index';

function BookLayout() {
  const match = useRouteMatch();

  return (
    <Switch>
      <Route exact path={`${match.path}/:bookId`}>
        <Layout title="Book detail">
          <BookDetail />
        </Layout>
      </Route>

      <Route exact path={match.path}>
        <Layout title="Book list">
          <BookPage />
        </Layout>
      </Route>

      <Route>
        <NotFound />
      </Route>
    </Switch>
  );
}

export default BookLayout;

Result​

• /books: Render a list of books

  

• /books/1: Render book detail

  

Related Articles​

• How to integrate dynamic routes in Docusaurus with react-router.
• Docusaurus: Creating pages.
• Docusaurus: addRoute.
• Docusaurus: Creating plugins.

Docusaurus allows you to add many types of navbar items to the navbar. But if you want to add a custom navbar item, you have to register a new type for your component. This guide will show you how to create a custom navbar item for Docusaurus.

Getting Started​

We will create a dropdown navbar item that contains a list of colors. When we select a color, the background color of the website will change to the selected one.

There are two types of navbar items we have to register:

• custom-colorPickerDropdown: This is the dropdown navbar item that contains a list of colors.
• custom-colorPicker: This is the navbar item that contains the color that we selected.

These types will be registered by extending the Docusaurus default NavbarItem/ComponentTypes exported object.

Our final result will look like this:

Types​

Create a types.ts file to store the types of our custom navbar items:

• type and label are the required properties of a navbar item.
• color is the color that we selected.

export type ColorConfig = {
  type?: string;
  label?: string;
  color?: 'red' | 'blue' | 'green' | 'default';
};

If an item is not provided with a label property, it will render an empty <div> element, which kind of looks weird.

Create a provider to share the color state​

When we shrink down the screen size to mobile size, the navbar will only hided with display: none. So the dropdown navbar item still exists and a new navbar is created as a sidebar. This means that the color state won't be synced between the two navbar items. To solve this problem, we have to create a provider to share the color state between the navbar and the sidebar (mobile).

• Create a context:

  src/components/elements/BgColorPicker/colorContext.tsx

  import { createContext } from 'react';
  import { ColorConfig } from './types';
  
  type ColorContextType = {
    color: Omit<ColorConfig, 'type'>;
    setColor: React.Dispatch<React.SetStateAction<Omit<ColorConfig, 'type'>>>;
  };
  
  export const ColorContext = createContext<ColorContextType>(null);
  

  Hm, why do we use Omit<ColorConfig, 'type'> instead of ColorConfig? Because the ColorPickerNavbarItem component wasn't provided with a type property, only label and color are provided. So we have to omit the type property to keep the type consistent.

• Then create a provider:

  src/components/elements/BgColorPicker/ColorPickerProvider.tsx

  import type { ThemeConfig } from '@docusaurus/preset-classic';
  import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
  import React, { useEffect, useState } from 'react';
  import { ColorContext } from '@site/src/components/elements/BgColorPicker/colorContext';
  import type { ColorConfig } from '@site/src/components/elements/BgColorPicker/types';
  
  const ColorPickerProvider = ({
    children,
  }: {
    children?: React.ReactNode;
  }) => {
    const { siteConfig } = useDocusaurusContext();
  
    const navbarItems = (siteConfig.themeConfig as ThemeConfig).navbar.items;
  
    const defaultColor: ColorConfig = navbarItems.find((item) => {
      return item.type === 'custom-colorPickerDropdown';
    }).items[0];
  
    const [color, setColor] = useState<Omit<ColorConfig, 'type'>>({
      label: defaultColor.label,
      color: defaultColor.color,
    });
  
    // eslint-disable-next-line consistent-return
    useEffect(() => {
      if (color?.color && color.color !== 'default') {
        document.documentElement.style.setProperty(
          '--ifm-background-color',
          color.color,
        );
      }
  
      return () => {
        document.documentElement.style.setProperty(
          '--ifm-background-color',
          '#0000',
        );
      };
    }, [color]);
  
    return (
      <ColorContext.Provider
        value={{
          color,
          setColor,
        }}
      >
        {children}
      </ColorContext.Provider>
    );
  };
  
  export { ColorPickerProvider };
  

  • We use the useDocusaurusContext hook to get the siteConfig object that has the navbar items we defined in docusaurus.config.js.

  • Extract the first entry of the items property of the custom-colorPickerDropdown navbar item. This is the default color that we will use when the user visits the website for the first time.

    tip

    It's recommended that you set default as the first color in the items property. So it won't affect the background color of the website when the user visits the website for the first time.

  • We use the useEffect hook to set the --ifm-background-color CSS variable to the selected color. We also set the --ifm-background-color CSS variable to #0000 (default value from Docusaurus) when the component is unmounted.

  • Finally, we pass the color and setColor to the ColorContext so that the ColorPickerNavbarItem can access it.

• Finally, wrap the Root theme component with the provider:

  src/theme/Root.tsx

  import React from 'react';
  import { ColorPickerProvider } from '@site/src/context/ColorPickerProvider';
  
  // Default implementation, that you can customize
  export default function Root({ children }: { children?: React.ReactNode }) {
    return <ColorPickerProvider>{children}</ColorPickerProvider>;
  }
  
  caution

  You should aware that the Root component is not mentioned whether it is Safe or Unsafe by running the command pnpm swizzle.

Create a dropdown navbar item component​

Create a wrapper component for the default DropdownNavbarItem component:

import { Icon } from '@iconify/react';
import type { Props } from '@theme/NavbarItem/DropdownNavbarItem';
import DropdownNavbarItem from '@theme/NavbarItem/DropdownNavbarItem';
import React, { useContext } from 'react';
import { ColorContext } from './colorContext';
import type { ColorConfig } from './types';

const ColorPickerDropdownNavbarItem = ({
  mobile = false,
  ...props
}: {
  items: ColorConfig[];
} & Props) => {
  const context = useContext(ColorContext);

  // Ref: https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-theme-classic/src/theme/NavbarItem/LocaleDropdownNavbarItem/styles.module.css
  const navbarLabel = (
    <>
      <Icon
        className="mr-5px align-text-bottom"
        icon="ic:outline-palette"
        width={24}
      />
      {mobile ? props.label : context?.color?.label}
    </>
  );

  return <DropdownNavbarItem mobile={mobile} {...props} label={navbarLabel} />;
};

export { ColorPickerDropdownNavbarItem };

• First, we have to intersect the Props type of the default DropdownNavbarItem with of our custom items property. This is because the default DropdownNavbarItem items property is of type LinkLikeNavbarItemProps[]. The items prop has value of the items property of the custom-colorPickerDropdown navbar item, defined in the docusaurus.config.js file.

• We can create a custom label with icon, like the LocaleDropdownNavbarItem component. We use the context to get the selected color label. On the desktop, it displays the selected color label. On mobile, it displays the label prop of the custom-colorPickerDropdown navbar item.

Create a navbar item component​

Create the ColorPickerNavbarItem component:

import type { Props } from '@theme/NavbarItem/DefaultNavbarItem';
import clsx from 'clsx';
import React, { ComponentProps, useContext } from 'react';
import { ColorContext } from './colorContext';
import type { ColorConfig } from './types';

type ColorPickerNavbarItemProps = Omit<Props, keyof ComponentProps<'a'>> &
  ComponentProps<'div'>;

const DefaultColorPickerNavbarItem = ({
  label,
  className,
  isDropdownItem = false,
  activeClassName,
  isLinkActive,
  mobile,
  ...props
}: {
  isLinkActive: boolean;
} & ColorPickerNavbarItemProps) => {
  const element = (
    <div
      className={clsx(
        isDropdownItem && (mobile ? 'menu__link' : 'dropdown__link'),
        className,
        isLinkActive && activeClassName,
      )}
      {...props}
    >
      {label}
    </div>
  );

  if (isDropdownItem) {
    return <li className={clsx(mobile && 'menu__list-item')}>{element}</li>;
  }

  return element;
};

const ColorPickerNavbarItem = ({
  label,
  color,
  mobile,
  ...props
}: Omit<ColorConfig, 'type'> & ColorPickerNavbarItemProps) => {
  const context = useContext(ColorContext);

  const handleClick = () => {
    context?.setColor({ label, color });
  };

  return (
    <DefaultColorPickerNavbarItem
      {...props}
      activeClassName={
        props.activeClassName ??
        (mobile ? 'menu__link--active' : 'dropdown__link--active')
      }
      isLinkActive={context?.color?.color === color}
      label={label}
      mobile={mobile}
      onClick={handleClick}
    />
  );
};

export { ColorPickerNavbarItem };

• First, because we render a <div> element instead of an <a> element, we have to omit the Props type of the default DefaultNavbarItem that contains the a element props.

  note

  Although the type ColorPickerNavbarItemProps still has the RRNavLinkProps, which is react-router-dom's props and others, that are not used in the component, we don't care much about it.

• This component is rewritten from the default DefaultNavbarItem component, which merge both DefaultNavbarItemDesktop and DefaultNavbarItemMobile into a single component.

Export navbar item components​

Export the ColorPickerDropdownNavbarItem and ColorPickerNavbarItem components:

export * from './DropdownNavbarItem';
export * from './NavbarItem';

Register custom navbar items​

We will register the custom navbar items in the NavbarItem/ComponentTypes file:

import ComponentTypes from '@theme-original/NavbarItem/ComponentTypes';
import {
  ColorPickerDropdownNavbarItem,
  ColorPickerNavbarItem,
} from '@site/src/components/elements/BgColorPicker';

export default {
  ...ComponentTypes,
  'custom-colorPickerDropdown': ColorPickerDropdownNavbarItem,
  'custom-colorPicker': ColorPickerNavbarItem,
};

Add navbar item to navbar​

Add the custom navbar items to the navbar in the file dousaurus.config.js:

const config = {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'custom-colorPickerDropdown',
          position: 'right',
          label: 'Color',
          items: [
            {
              type: 'custom-colorPicker',
              label: 'default',
              color: 'default',
            },
            {
              type: 'custom-colorPicker',
              label: 'red',
              color: 'red',
            },
            {
              type: 'custom-colorPicker',
              label: 'blue',
              color: 'blue',
            },
            {
              type: 'custom-colorPicker',
              label: 'green',
              color: 'green',
            },
          ],
        },
      ],
    },
  },
};

And voila! We have a working color picker in the navbar.

Related Articles​

• Workaround for custom navbar items.
• Docusaurus: Navbar items configuration.

Docusaurus is an excellent tool for building documentation websites. However, it does not support WindiCSS out of the box. Mantine is a React UI library that provides a lot of UI components and hooks, so you can use them to build your components.

This guide will show you how to integrate WindiCSS and Mantine with Docusaurus.

Getting Started​

We will go through setting up these features:

• ✅ WindiCSS
  • ✅ Dark mode
  • ✅ Typography
  • ✅ Animations (from @windicss/plugin-animations)
  • ✅ Attributify mode
  • ✅ Colors
  • ❌ Design in DevTools mode
• ✅ Mantine
  • ✅ Dark mode
  • ✅ Typography
  • ✅ Colors

Currently, there are some bugs with WindiCSS Devtool in windicss-webpack-plugin package, which are reported in #118 and #115.

Setup Docusaurus​

First, we need to set up a Docusaurus project. You can follow the official guide from Docusaurus website:

pnpm create docusaurus demo-docs classic

Then, we have this project structure:

.
├── babel.config.js
├── blog
├── docs
├── docusaurus.config.js
├── node_modules
├── package.json
├── pnpm-lock.yaml
├── README.md
├── sidebars.js
├── src
│   ├── components
│   ├── css
│   └── pages
└── static
    └── img

Setup WindiCSS​

Install dependencies​

We will have to install windicss and windicss-webpack-plugin package:

pnpm add -D windicss windicss-webpack-plugin

Configure Webpack​

Following the official guide from WindiCSS, we have to configure Webpack to use the windicss-webpack-plugin.

Because the file webpack.config.ts somehow is not loaded by Docusaurus, we have to configure Webpack manually in the file docusaurus.config.js by creating a custom Docusaurus plugin:

const WindiCSSWebpackPlugin = require('windicss-webpack-plugin');

/** @type {import('@docusaurus/types').Config} */
const config = {
  plugins: [
    function windicssPlugin() {
      return {
        name: 'windicss-plugin',
        configureWebpack() {
          return {
            plugins: [new WindiCSSWebpackPlugin()],
          };
        },
      };
    },
  ],
};

module.exports = config;

Include the virtual module​

It's recommended to include the WindiCSS virtual module within an entry point file or something only loaded once.

However, Docusaurus does not have an entry file like index.js or index.ts, so we have to "swizzle" the Root component by creating a wrapper around it to import the module.

The <Root> component is rendered at the very top of the React tree, above the theme <Layout>, and never unmounts. It is the perfect place to add stateful logic that should not be re-initialized across navigations (user authentication status, shopping card state...).

Import all three layers:

import React from 'react';
import 'windi.css';

// Default implementation, that you can customize
export default function Root({ children }: { children?: React.ReactNode }) {
  return <>{children}</>;
}

Because the file windi-base.css overrides the default styles of Docusaurus, so I recommend not importing it:

import React from 'react';
-import 'windi.css';
+import 'windi-components.css';
+import 'windi-utilities.css';

// Default implementation, that you can customize
export default function Root({ children }: { children?: React.ReactNode }) {
  return <>{children}</>;
}

Test Locally​

Now, we can test the result by writing some classes in HomepageHeader the component in the file src/pages/index.tsx:

// ...
function HomepageHeader() {
  const { siteConfig } = useDocusaurusContext();
  return (
    <header className="bg-blue-500">
      <div className="container mx-auto text-center py-24">
        <h1 className="text-4xl font-bold text-white">{siteConfig.title}</h1>
        <p className="text-xl py-6 text-white">{siteConfig.tagline}</p>

        <div className="py-10">
          <Link
            className="bg-white rounded-md text-gray-500 px-4 py-2"
            to="/docs/intro"
          >
            Docusaurus Tutorial - 5min ⏱️
          </Link>
        </div>
      </div>
    </header>
  );
}
// ...

And we can see the result:

Configure WindiCSS​

You can configure WindiCSS by creating a file windi.config.ts in the root directory.

Dark Mode​

Windi CSS has out-of-box Dark Mode support.

By prefixing the dark: variant to utilities, they will only apply when dark mode is enabled.

We have two modes for enabling dark mode, class mode and media query mode. By default, class mode is enabled.

Enable dark mode using class mode:

export default {
  darkMode: 'class',
};

To manually add class dark to the <html> element, we can add some logic in the Layout/Provider wrapper:

• Add or remove the class dark based on the color scheme.

// eslint-disable-next-line import/no-extraneous-dependencies
import { useColorMode } from '@docusaurus/theme-common';
import { ColorSchemeProvider } from '@mantine/core';
import Provider from '@theme-original/Layout/Provider';
import React, { useEffect } from 'react';
import { MantineProvider } from '@site/src/context/MantineProvider';

const CustomProvider = ({ children }: { children?: React.ReactNode }) => {
  const { colorMode, setColorMode } = useColorMode();

  useEffect(() => {
    if (colorMode === 'dark') {
      document.documentElement.classList.add('dark');
    } else if (colorMode === 'light') {
      document.documentElement.classList.remove('dark');
    }
  }, [colorMode]);

  return <>{children}</>;
};

export default function ProviderWrapper({
  children,
  ...props
}: {
  children?: React.ReactNode;
}) {
  return (
    <Provider {...props}>
      <CustomProvider>{children}</CustomProvider>
    </Provider>
  );
}

import ColorModeToggle from '@theme-original/ColorModeToggle';
import type { Props } from '@theme/ColorModeToggle';
import React, { useEffect } from 'react';

export default function ColorModeToggleWrapper(props: Props) {
  const { value: colorMode } = props;

  useEffect(() => {
    if (colorMode === 'dark') {
      document.documentElement.classList.add('dark');
    } else if (colorMode === 'light') {
      document.documentElement.classList.remove('dark');
    }
  }, [colorMode]);

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

public-hoist-pattern[]=@docusaurus/theme-common*

Typography​

WindiCSS font family utilities (font-sans, font-serif, font-mono) configured fonts are quite different from the ones configured in Docusaurus. So we can configure the fonts in windi.config.ts to match with Docusaurus configurations:

• Font family base from variable --ifm-font-family-base.
• Font family mono from variable --ifm-font-family-monospace.
• Font family serif is not present in Docusaurus, so we can use the default value.

export default {
  theme: {
    extend: {
      fontFamily: {
        sans: 'system-ui,-apple-system,Segoe UI,Roboto,Ubuntu,Cantarell,Noto Sans,sans-serif,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol"',
        mono: 'SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace',
      },
    },
  },
};

Animations​

To add quick animations to your site, you can use WindiCSS's animation default utilities, but it's quite limited. So we can install the plugin @windicss/plugin-animations to add more animations utilities from Animate CSS

Install the plugin:

pnpm add -D @windicss/plugin-animations

Add the plugin to windi.config.ts:

import pluginAnimations from '@windicss/plugin-animations';

export default {
  plugins: [
    // Other plugins
    pluginAnimations({
      settings: {
        // animatedSpeed: 1000,
      },
    }),
  ],
};

Then you can use the animation utilities:

// ...
function HomepageHeader() {
  return (
    <p className="animate-animated animate-infinite animate-rubberBand">
      Hello World
    </p>
  );
}
// ...

Attributify Mode​

To configure the attributify mode, we can configure it in windi.config.ts:

export default {
  attributify: true,
};

Then you can use the WindiCSS utilities as HTML attributes:

// ...
function HomepageHeader() {
  return (
    <button
      bg="blue-400 hover:blue-500 dark:blue-500 dark:hover:blue-600"
      text="sm white"
      font="mono light"
      p="y-2 x-4"
      border="2 rounded blue-200"
    >
      Button
    </button>
  );
}
// ...

export default {
  attributify: {
    prefix: 'w:',
  },
};

// ...
function HomepageHeader() {
  return (
    <button
      w:bg="blue-400 hover:blue-500 dark:blue-500 dark:hover:blue-600"
      w:text="sm white"
      w:font="mono light"
      w:p="y-2 x-4"
      w:border="2 rounded blue-200"
    >
      Button
    </button>
  );
}
// ...

Colors​

Docusaurus configured primary colors from src/css/custom.css:

:root {
  --ifm-color-primary: #2e8555;
  --ifm-color-primary-dark: #29784c;
  --ifm-color-primary-darker: #277148;
  --ifm-color-primary-darkest: #205d3b;
  --ifm-color-primary-light: #33925d;
  --ifm-color-primary-lighter: #359962;
  --ifm-color-primary-lightest: #3cad6e;
  --ifm-code-font-size: 95%;
  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
}

/* For readability concerns, you should choose a lighter palette in dark mode. */
[data-theme='dark'] {
  --ifm-color-primary: #25c2a0;
  --ifm-color-primary-dark: #21af90;
  --ifm-color-primary-darker: #1fa588;
  --ifm-color-primary-darkest: #1a8870;
  --ifm-color-primary-light: #29d5b0;
  --ifm-color-primary-lighter: #32d8b4;
  --ifm-color-primary-lightest: #4fddbf;
  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
}

We can configure WindiCSS to use these in class as well:

export default {
  theme: {
    extend: {
      colors: {
        primary: {
          DEFAULT: '#2e8555',
          dark: '#29784c',
          darker: '#277148',
          darkest: '#205d3b',
          light: '#33925d',
          lighter: '#359962',
          lightest: '#3cad6e',
        },
        'dark-primary': {
          DEFAULT: '#25c2a0',
          dark: '#21af90',
          darker: '#1fa588',
          darkest: '#1a8870',
          light: '#29d5b0',
          lighter: '#32d8b4',
          lightest: '#4fddbf',
        },
      },
    },
  },
};

Then you can use Docusaurus primary colors in class:

// ...
function HomepageHeader() {
  return (
    <p className="bg-primary hover:bg-primary-dark dark:bg-dark-primary dark:hover:bg-dark-primary-dark">
      Hello World
    </p>
  );
}
// ...

Setup Mantine​

Install dependencies​

pnpm add @mantine/core @mantine/hooks @emotion/react

Configure Mantine Provider​

In this step, we will add Mantine Provider to the <Root> to ensure that all Mantine components are using the same theme.

+import { MantineProvider } from '@mantine/core';
import React from 'react';
// eslint-disable-next-line import/no-unresolved
import 'windi-components.css';
// eslint-disable-next-line import/no-unresolved
import 'windi-utilities.css';

// Default implementation, that you can customize
export default function Root({ children }: { children?: React.ReactNode }) {
  return (
-     <>{children}</>
+     <MantineProvider>{children}</MantineProvider>
  );
}

Custom Mantine Provider​

In this file, we will configure the Mantine Provider to use the WindiCSS theme (colors, fonts, breakpoints, etc) and Docusaurus theme (colors, fonts, etc), so we can ensure the consistency between the Docusaurus site, Mantine components, and WindiCSS utilities.

import {
  MantineProvider as BaseMantineProvider,
  Global,
  MantineTheme,
  DEFAULT_THEME as mantineDefaultTheme,
} from '@mantine/core';
import type { MantineSizes } from '@mantine/core';
import React from 'react';
import windiDefaultColors from 'windicss/colors';
import windiDefaultTheme from 'windicss/defaultTheme';
import type { DefaultColors } from 'windicss/types/config/colors';
import type { DefaultFontSize, ThemeType } from 'windicss/types/interfaces';
import type { MantineThemeColors } from '@site/src/types/MantineThemeColors';

const convertBreakpoint = (breakpoint: ThemeType): MantineSizes => {
  const convertedBreakpoint = {} as MantineSizes;
  Object.keys(breakpoint).forEach((size) => {
    // NOTE: Have to remove 'px' from breakpoint and convert to number
    convertedBreakpoint[size] = +breakpoint[size].replace('px', '');
  });
  return convertedBreakpoint;
};

// Override Mantine colors
const convertColor = (windiColors: DefaultColors) => {
  const convertedColor = {} as MantineThemeColors;
  Object.keys(windiColors).forEach((color) => {
    if (color === 'lightBlue') {
      color = 'sky';
    } else if (color === 'warmGray') {
      color = 'stone';
    } else if (color === 'trueGray') {
      color = 'neutral';
    } else if (color === 'coolGray') {
      color = 'gray';
    } else if (color === 'blueGray') {
      color = 'slate';
    } else if (color === 'zink') {
      color = 'zinc';
    }

    if (windiColors[color] instanceof Object) {
      convertedColor[color] = Object.values(windiColors[color]);
    }
  });
  // NOTE: WindiCSS dark color is too dark
  convertedColor.dark = convertedColor.zinc;

  return convertedColor;
};

const convertFontSize = (fontSize: {
  [key: string]: DefaultFontSize;
}): MantineSizes => {
  const convertedFontSize = {} as MantineSizes;
  Object.keys(fontSize).forEach((size) => {
    // NOTE: Don't have to convert 'rem' to 'px'
    convertedFontSize[size] = fontSize[size][0];
  });
  return convertedFontSize;
};

const theme: MantineTheme = {
  ...mantineDefaultTheme,
  breakpoints: {
    ...mantineDefaultTheme.breakpoints,
    ...convertBreakpoint(windiDefaultTheme.screens), // WindiCSS
  },
  colors: {
    ...mantineDefaultTheme.colors,
    ...convertColor(windiDefaultColors),
  },
  defaultRadius: 'md',
  black: windiDefaultColors.black as string,
  white: windiDefaultColors.white as string,
  primaryColor: 'blue',
  fontSizes: {
    ...mantineDefaultTheme.fontSizes,
    ...convertFontSize(windiDefaultTheme.fontSize),
  },
  radius: {
    ...mantineDefaultTheme.radius,
    // NOTE: WindiCSS border radius messed up with Mantine
    // ...windiDefaultTheme.borderRadius,
  },
  fontFamily:
    'system-ui,-apple-system,Segoe UI,Roboto,Ubuntu,Cantarell,Noto Sans,sans-serif,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol"',
  fontFamilyMonospace:
    'SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace',
  headings: {
    ...mantineDefaultTheme.headings,
    fontFamily:
      'system-ui,-apple-system,Segoe UI,Roboto,Ubuntu,Cantarell,Noto Sans,sans-serif,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol"',
  },
  lineHeight: mantineDefaultTheme.lineHeight,
  loader: 'oval',
  shadows: {
    ...mantineDefaultTheme.shadows,
    ...windiDefaultTheme.boxShadow,
  },
};

const MyGlobalStyles = () => {
  return (
    <Global
      styles={{
        'html.dark': {
          img: {
            filter: 'brightness(.8) contrast(1.2)',
          },
        },
      }}
    />
  );
};

type MantineProps = {
  children: React.ReactNode;
  theme?: Partial<MantineTheme>;
};

const MantineProvider = ({
  children,
  theme: themeProps,
  ...props
}: MantineProps) => {
  return (
    <BaseMantineProvider theme={{ ...theme, ...themeProps }} {...props}>
      <MyGlobalStyles />
      {children}
    </BaseMantineProvider>
  );
};

export { MantineProvider };

Use our custom <MantineProvider> in src/theme/Layout/Provider/index.tsx:

import { useColorMode } from '@docusaurus/theme-common';
import Provider from '@theme-original/Layout/Provider';
import React, { useEffect } from 'react';
+import { MantineProvider } from '@site/src/context/MantineProvider';

const CustomProvider = ({ children }) => {
  const { colorMode, setColorMode } = useColorMode();

  useEffect(() => {
    if (colorMode === 'dark') {
      document.documentElement.classList.add('dark');
    } else if (colorMode === 'light') {
      document.documentElement.classList.remove('dark');
    }
  }, [colorMode]);

- return <>{children}</>;
+ return (
+   <MantineProvider>
+     {children}
+   </MantineProvider>
+ );
};

export default function ProviderWrapper({ children, ...props }) {
  return (
    <Provider {...props}>
      <CustomProvider>{children}</CustomProvider>
    </Provider>
  );
}

Configure Mantine​

Dark Mode​

We will pass the color mode to Mantine using the ColorSchemeProvider component and theme.colorScheme props:

import { useColorMode } from '@docusaurus/theme-common';
+import { ColorSchemeProvider } from '@mantine/core';
import Provider from '@theme-original/Layout/Provider';
import React, { useEffect } from 'react';
+import { MantineProvider } from '@site/src/context/MantineProvider';

const CustomProvider = ({ children }) => {
  const { colorMode, setColorMode } = useColorMode();

  useEffect(() => {
    if (colorMode === 'dark') {
      document.documentElement.classList.add('dark');
    } else if (colorMode === 'light') {
      document.documentElement.classList.remove('dark');
    }
  }, [colorMode]);

+ const toggleColorScheme = (value) =>
+   setColorMode(value || (colorMode === 'dark' ? 'light' : 'dark'));

- return (
-   <MantineProvider>
-     {children}
-   </MantineProvider>
- );
+ return (
+   <ColorSchemeProvider
+     colorScheme={colorMode}
+     toggleColorScheme={toggleColorScheme}
+   >
+     <MantineProvider theme={{ colorScheme: colorMode }}>
+       {children}
+     </MantineProvider>
+   </ColorSchemeProvider>
+ );
};

export default function ProviderWrapper({ children, ...props }) {
  return (
    <Provider {...props}>
      <CustomProvider>{children}</CustomProvider>
    </Provider>
  );
}

So now we can use the useMantineColorScheme (or useColorMode from Docusaurus) hook to get the color mode:

// ...
import { Button, useMantineColorScheme } from '@mantine/core';

function HomepageHeader() {
  const { siteConfig } = useDocusaurusContext();
  const { colorScheme, toggleColorScheme } = useMantineColorScheme();
  const dark = colorScheme === 'dark';
  return (
    <header className={clsx('hero hero--primary', styles.heroBanner)}>
      <div className="container">
        <h1 className="hero__title">{siteConfig.title}</h1>
        <p className="hero__subtitle">{siteConfig.tagline}</p>
        <div className={styles.buttons}>
          <Link
            className="button button--secondary button--lg"
            to="/docs/intro"
          >
            Docusaurus Tutorial - 5min ⏱️
          </Link>
        </div>
        <Button
          variant="outline"
          onClick={() => toggleColorScheme()}
          title="Toggle color scheme"
        >
          {dark ? 'dark' : 'light'}
        </Button>
      </div>
    </header>
  );
}
// ...

Typography​