Skip to main content

Tricks

约定​

位于 src/pages 目录下的以 .md, .mdx, 或者 tsx, jsx 结尾的后缀名默认为会生成页面. 但是如果文件名以 _ 开头则会被忽略, 比如 src/pages/demo/_hello.tsx 就不会被生成页面 /demo/hello 或者 /demo/_hello. 所以一般 partial markdown 或者 code snippest, reac component 文件采用 _ 开头.

Tricks​

创建带有模板的页面​

下面的代码使用 Layout 会创建一个带有公共导航和底部信息的页面.

src/pages/page1.tsx
import React from 'react';
import Layout from '@theme/Layout';
import Head from '@docusaurus/Head';

export default function Index() {
  return (
    <Layout title='首页'>
      <Head>
        <meta />
        <style> </style>
      </Head>
      <main className='container'>
        这里是页面内容
      </main>
    </Layout>
  );
}

Markdown import React component​

Markdown 导入React组件

blog/2022-01-01-blog-name.md
# 标题

<!-- Docusaurus 原生组件 -->
import TOCInline from '@theme/TOCInline';
<!-- 第三方组件 -->
import Button from '@mui/material/Button';
<!-- 这个是自定义组件 -->
import BrowserWindow from '@site/src/components/BrowserWindow';

## 标题2

* 列表1
* 列表2

下面使用组件:

<TOCInline />

使用自定义组件

<BrowserWindow hello="world" />

Register global component​

利用 MDXComponent 注册Markdown全局组件:

手动创建文件 src/theme/MDXComponents.js 或者 src/theme/MDXComponents.tsx

src/theme/MDXComponents.tsx
import React from 'react';
import MDXComponents from '@theme-original/MDXComponents';
import { ResourceLink, GiteeImage, GitTalkComment, NetworkCopyRight } from "../components/index";

export default {
    // Re-use the default mapping
    ...MDXComponents,
    ResourceLink: ResourceLink,
    GiteeImage: GiteeImage,
    GitTalkComment: GitTalkComment,
    NetworkCopyRight: NetworkCopyRight
    // Map the "collapse-block" tag to our <CollapseBlock /> component!
    // `collapse-block` will receive all props that were passed to `collapse-block` in MDX
    //   HandlerGetDataForAppEnv: HandlerGetDataForAppEnv
};

接下来就可以在任意Markdown文件时用上面注册的全局组件, 比如:

src/pages/hello.md
# title

* list
* list

<ResourceLink link="xxxx" />

Importing code snippets​

在markdown或者react页面里导入代码片段进行展示:

install​

安装 webpack raw-loader 依赖:

npm install --save raw-loader

利用 CodeBlock 展示代码片段​

下面的代码可以在markdown和react组件上使用:

import CodeBlock from '@theme/CodeBlock';
import MyComponentSource from '!!raw-loader!./myComponent';

<CodeBlock language="jsx">{MyComponentSource}</CodeBlock>

Live Code​

安装插件 Docusaurus Live Codeblock, 可以在页面上直接渲染jsx代码:

config​

安装依赖
npm i @docusaurus/theme-live-codeblock

修改文件 docusaurus.config.js, 新增以下配置:

module.exports = {
  ...
+ themes: ['@docusaurus/theme-live-codeblock'],
  presets: ['@docusaurus/preset-classic']
  ...
}

use​

给代码块增加 live 标识, 然后代码块生成一个函数, 并返回 jsx element 即可:

```jsx live
function Clock(props) {
  const [date, setDate] = useState(new Date());
  useEffect(() => {
    var timerID = setInterval(() => tick(), 1000);

    return function cleanup() {
      clearInterval(timerID);
    };
  });

  function tick() {
    setDate(new Date());
  }

  return (
    <div>
      <h2>It is {date.toLocaleTimeString()}.</h2>
    </div>
  );
}
```

除了上面编写一个函数的方式, live code 还支持手动调用 render 方法渲染:

```jsx live noInline
const project = "Docusaurus";

const Greeting = () => <p>Helloe {project}!</p>;

render(<Greeting />)
```

也可以在 live code 中注册全局组件, 方便 live code 使用:

执行 npm run swizzle @docusaurus/theme-live-codeblock ReactLiveScope -- --eject, 然后修改文件 src/theme/ReactLiveScope/index.js:

import React from 'react';

const ButtonExample = (props) => (
  <button
    {...props}
    style={{
      backgroundColor: 'white',
      color: 'black',
      border: 'solid red',
      borderRadius: 20,
      padding: 10,
      cursor: 'pointer',
      ...props.style,
    }}
  />
);

// Add react-live imports you need here
const ReactLiveScope = {
  React,
  ...React,
  ButtonExample, // 这个就是自定义的全局组件
};

export default ReactLiveScope;

然后 live code 里就可以直接使用 <ButtonExample /> 这个组件了.(无需import导入)

React component render code block​

在React组件或者页面里渲染代码块:

src/pages/hello.jsx
import CodeBlock from '@theme/CodeBlock';

export default function MyReactPage() {
  return (
    <div>
      <CodeBlock
        language="jsx"
        title="/src/components/HelloCodeTitle.js"
        showLineNumbers>
        {`function HelloCodeTitle(props) {
  return <h1>Hello, {props.name}</h1>;
}`}
      </CodeBlock>
    </div>
  );
}

上面生成代码块仅能展示, 无法渲染, 下面是 live code block 示例, 主要区别是把 @theme/CodeBlock 换成了 @docusaurus/theme-live-codeblock/lib/theme/CodeBlock:

import React from 'react';
import Layout from '@theme/Layout';
import CodeBlock  from "@docusaurus/theme-live-codeblock/lib/theme/CodeBlock";

export default function Index() {
  return (
    <Layout title='首页'>
      <main className='container'>
        <CodeBlock showLineNumbers live >
          {`
          function render(){
            return (<div>hello</div>);
          }
          `}
        </CodeBlock>
      </main>
    </Layout>
  );
}

React component render markdown​

React 组件或者页面利用 @theme/MDXContent 原生组件可以渲染 Markdown 内容:

  1. 创建一个markdown代码片段
src/pages/demo/_hello.md
**这里是 markdown 文件内容**
*hello*
  1. 在React页面或者组件使用
src/pages/demo/index.tsx
import React from 'react';
import Layout from '@theme/Layout';
import Intro from "./_intro.md";
import MDXContent from '@theme/MDXContent';

export default function Index() {
  return (
    <Layout title='演示页面'>
      <main className='container'>
        <MDXContent>
          <Intro />
        </MDXContent>
      </main>
    </Layout>
  );
}

Code snippets + Markdown live code​

下面演示在 Markdown 中动态渲染 JSX 代码片段.

下面是代码片段 src/pages/demo/_PartialCode.jsx:

src/pages/demo/_PartialCode.jsx
import React from "react";

export function RenderComponent() {
  return (
    <div>Hello world.</div>
  );
}

然后Markdown文件内利用 @docusaurus/theme-live-codeblock 和 raw-loader 实现动态加载代码片段并渲染:

注意这是markdown文件
import CodeBlock from "@docusaurus/theme-live-codeblock/lib/theme/CodeBlock";
import RawData from "!!raw-loader!@site/src/pages/demo/\_PartialCode";

# 以下创建 live code

<CodeBlock language="jsx" live>
  { RawData }
</CodeBlock>
note

虽然上述代码是markdown里写的, 但是 React 页面或者组件同样适用.