跳到主要内容

丰富Admonition类型

自定义Admonitions的官方文档：https://docusaurus.io/docs/markdown-features/admonitions#customizing-admonitions

本文中增加了success、bug、abstract、question、example 5种类型的Admonition。效果如下

success

Some content with Markdown syntax. Check this api.

bug

Some content with Markdown syntax. Check this api.

abstract

Some content with Markdown syntax. Check this api.

question

Some content with Markdown syntax. Check this api.

example

Some content with Markdown syntax. Check this api.

实现​

我们借助Docusaurus已经存在的组件AdmonitionLayout来实现。

import AdmonitionLayout from '@theme/Admonition/Layout';

实现方式参考了 node_modules/@docusaurus/theme-classic/src/theme/Admonition/Type/Info.tsx，这是官方的实现。

配置​

首先我们需要在docusaurus.config.ts中增加Admonition类型。

docusaurus.config.js
export default {
  // ...
  presets: [
    [
      'classic',
      {
        // ...
        docs: {
          admonitions: {
            keywords: ['success', 'abstract', 'question', 'bug', 'example'],
            extendDefaults: true,
          },
        },
      },
    ],
  ],
};

代码实现​

首先在 src/theme文件夹下创建一个 theme.d.ts 文件，用于声明Props模块。

declare module '@theme/Admonition/Type/Success' {
    import type {Props as AdmonitionProps} from '@theme/Admonition';

    export interface Props extends AdmonitionProps {}
    export default function AdmonitionTypSuccess(props: Props): JSX.Element;
}

declare module '@theme/Admonition/Type/Abstract' {
    import type {Props as AdmonitionProps} from '@theme/Admonition';

    export interface Props extends AdmonitionProps {}
    export default function AdmonitionTypAbstract(props: Props): JSX.Element;
}

declare module '@theme/Admonition/Type/Question' {
    import type {Props as AdmonitionProps} from '@theme/Admonition';

    export interface Props extends AdmonitionProps {}
    export default function AdmonitionTypQuestion(props: Props): JSX.Element;
}

declare module '@theme/Admonition/Type/Bug' {
    import type {Props as AdmonitionProps} from '@theme/Admonition';

    export interface Props extends AdmonitionProps {}
    export default function AdmonitionTypBug(props: Props): JSX.Element;
}

declare module '@theme/Admonition/Type/Example' {
    import type {Props as AdmonitionProps} from '@theme/Admonition';

    export interface Props extends AdmonitionProps {}
    export default function AdmonitionTypExample(props: Props): JSX.Element;
}

declare module '@theme/Admonition/Type/Memo' {
    import type {Props as AdmonitionProps} from '@theme/Admonition';

    export interface Props extends AdmonitionProps {}
    export default function AdmonitionTypMemo(props: Props): JSX.Element;
}

declare module '@theme/Admonition/Type/Translate' {
    import type {Props as AdmonitionProps} from '@theme/Admonition';

    export interface Props extends AdmonitionProps {}
    export default function AdmonitionTypeTranslate(props: Props): JSX.Element;
}

组件代码实现

/src/theme/Admonition/Type/Success.tsx
/// <reference path="../../theme.d.ts" />

import React from 'react';
import clsx from 'clsx';
import Translate from '@docusaurus/Translate';
import type {Props} from '@theme/Admonition/Type/Success';
import AdmonitionLayout from '@theme/Admonition/Layout';
import SuccessIcon from '@site/static/img/admonition/success.svg';

const infimaClassName = 'alert alert--success';

const defaultProps = {
  icon: <SuccessIcon />,
  title: (
    <Translate
      id="theme.admonition.success"
      description="The default label used for the Success admonition (:::success)">
      success
    </Translate>
  ),
};

export default function AdmonitionTypeSuccess(props: Props): JSX.Element {
  return (
    <AdmonitionLayout
      {...defaultProps}
      {...props}
      className={clsx(infimaClassName, props.className)}>
      {props.children}
    </AdmonitionLayout>
  );
}

配置.d.ts文件​

还需要在tsconfig.json中加入theme.d.ts。

tsconfig.json
{
  // This file is not used in compilation. It is here just for a nice editor experience.
  "extends": "@docusaurus/tsconfig",
  "include": ["src/theme/theme.d.ts"],
  "compilerOptions": {
    "baseUrl": "."
  }
}

或者在文档中使用三斜线指令引入.d.ts。

两种方式任选一种即可，本文中两种方式都提供了。

如何修改默认样式​

根据上面的方法生成的组件会包含一个theme-admonition-<type>的样式，如success类型的组件会包含theme-admonition-success。要想自定义其样式，只需要在src/css/customer.css中定义其样式即可。

本示例中的bug组件的样式如下：

.theme-admonition-bug {
    --ifm-alert-background-color: #ffebec;
    --ifm-alert-background-color-highlight: rgba(250, 56, 62, .15);
    --ifm-alert-foreground-color: var(--ifm-color-danger-contrast-foreground);
    --ifm-alert-border-color: #e13238;
}

同样的方法也可以修改官方的默认样式。

使用​

与官方的Admonition使用方式一样

:::success
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::
success

Some content with Markdown syntax. Check this api.

:::success[执行成功]
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::
执行成功

Some content with Markdown syntax. Check this api.