Skip to main content

Docusaurus


Admonitions​

Note:

Note

:::note Note:
Note
:::

Tip:

Tip

:::tip Tip:
Tip
:::

Info:

Info

:::info Info:
Info
:::

Caution:

Caution

:::caution Caution:
Caution
:::

Warning!

Danger

:::danger Warning!
Danger
:::


Codeblock​

  • with title

    index.js
    function foo() {
      console.log("Hello World!");
    }
    ```jsx title="index.js"
    function foo() {
      console.log("Hello World!");
    }
    ```

  • Line Highlighting

    • with comment
      function foo() {
        if (hour < 18) {
          console.log("Good day");
        } else {
          console.log("Good evening");
        }
      }
      ```javascript
      // highlight-next-line
      function foo() {
        if (hour < 18) {
          console.log("Good day");
        // highlight-start
        } else {
          console.log("Good evening");
        // highlight-end
        }
      }
      ```

  • Custom error comments

    • Declaration

      module.exports = {
        themeConfig: {
          prism: {
            magicComments: [
              // Remember to extend the default highlight class name as well!
              {
                className: 'theme-code-block-highlighted-line',
                line: 'highlight-next-line',
                block: {start: 'highlight-start', end: 'highlight-end'},
              },
              {
                className: 'code-block-error-line',
                line: 'highlight-next-line-error',
              },
            ],
          },
        },
      };

    • Usage

      const name = null;
      console.log(name.toUpperCase());
      // Uncaught TypeError: Cannot read properties of null (reading 'toUpperCase')
      ```javascript
      const name = null;
      // highlight-next-line-error
      console.log(name.toUpperCase());
      // Uncaught TypeError: Cannot read properties of null (reading 'toUpperCase')
      ```

  • with line range

    function foo() {
      if (hour < 18) {
        console.log("Good day");
      } else {
        console.log("Good evening");
      }
    }
    ```javascript {1,4-6}
    function foo() {
      if (hour < 18) {
        console.log("Good day");
      } else {
        console.log("Good evening");
      }
    }
    ```

  • Line numbering

    function foo() {
      console.log("Hello World!");
    }
    ```javascript showLineNumbers
    function foo() {
      console.log("Hello World!");
    }
    ```

Diagrams by mermaid​

  • Installation

    npm install --save @docusaurus/theme-mermaid

  • Config

    docusaurus.config.js
    module.exports = {
      markdown: {
        mermaid: true,
      },
      themes: ['@docusaurus/theme-mermaid'],
    };

  • Usage

    Class Diagram:​

    ```mermaid
    classDiagram
    direction RL
    class Student {
      -idCard : IdCard
    }
    class IdCard{
      -id : int
      -name : string
    }
    class Bike{
      -id : int
      -name : string
    }
    Student "1" --o "1" IdCard : carries
    Student "1" --o "1" Bike : rides
    ```

  • more Examples

Interactive Code Editor​

  • add Plugin package

    npm install --save @docusaurus/theme-live-codeblock

  • add plugin to config

    docusaurus.config.js
    module.exports = {
      // ...
      themes: ['@docusaurus/theme-live-codeblock'],
      // ...
    };

  • Usage

    ```jsx live
    function toCelsius(f) {
      f = 77;
      celsius = (5/9) * (f-32)
      return celsius;
    }
    ```

React Live Imports​

  • ButtonExample

    Import:

    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;

    Caution:

    Restart Dev-Server!

  • usage

    ```jsx live
    function MyPlayground(props) {
    return (
      <div>
        <ButtonExample onClick={() => alert('hey!')}>Click me</ButtonExample>
      </div>
    );
    }
    ```

Tabs​

  • Example

    html

  • Usage

    import Tabs from '@theme/Tabs';
    import TabItem from '@theme/TabItem';

    <Tabs>
      <TabItem value="html" label="html" default>
        html
      </TabItem>
      <TabItem value="css" label="css">
        css
      </TabItem>
      <TabItem value="js" label="js">
        js
      </TabItem>
    </Tabs>

Heading​

  • set heading range in toc for single document

    ---
    toc_min_heading_level: 2
    toc_max_heading_level: 6
    ---

  • set heading range in toc as default for all documents

    docusaurus.config.js
    module.exports = {
      themeConfig: {
        tableOfContents: {
          minHeadingLevel: 2,
          maxHeadingLevel: 6,
        },
      },
    };

  • TestHeading #3​

    TestHeading #4​

    TestHeading #5​
    TestHeading #6​

MDX Plugins​


Math Equations​

Katex
Documentation

  • Install

    npm install --save remark-math@3 rehype-katex@4

  • config

    docusaurus.config.js
    const math = require('remark-math');
    const katex = require('rehype-katex');

    module.exports = {
      title: 'Docusaurus',
      tagline: 'Build optimized websites quickly, focus on your content',
      presets: [
        [
          '@docusaurus/preset-classic',
          {
            docs: {
              path: 'docs',
              remarkPlugins: [math],
              rehypePlugins: [katex],
            },
          },
        ],
      ],
      stylesheets: [
        {
          href: 'https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css',
          type: 'text/css',
          integrity:
            'sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM',
          crossorigin: 'anonymous',
        },
      ],
    };

    Version must be:

    package.json
    "rehype-katex": "^4.0.0",
    "remark-math": "^3.0.1",

  • Config with Docusaurus plugin-content-docs:

    docusaurus.config.js
    /** @type {import('@docusaurus/plugin-content-docs').Options} */
    const defaultSettings = {
      remarkPlugins: [math],
      rehypePlugins: [katex],
    };

  • Usage Inline

    Fundamental Theorem of Calculus
    Let f:[a,b]→Rf:[a,b] \to \R be Riemann integrable. Let F:[a,b]→RF:[a,b]\to\R be F(x)=∫axf(t)dtF(x)= \int_{a}^{x}f(t)dt. Then FF is continuous, and at all xx such that ff is continuous at xx, FF is differentiable at xx with F′(x)=f(x)F'(x)=f(x).

      **Fundamental Theorem of Calculus**  
    Let $f:[a,b] \to \R$ be Riemann integrable. Let $F:[a,b]\to\R$ be $F(x)=
    \int_{a}^{x}f(t)dt$.
    Then $$F$$ is continuous, and at all $x$ such that $f$ is continuous at $x$,
    $F$ is differentiable at $x$ with $F'(x)=f(x)$.

  • Usage as Block

    I=∫02πsin⁡(x) dxI = \int_0^{2\pi} \sin(x)\,dx

    $$
    I = \int_0^{2\pi} \sin(x)\,dx
    $$