docusaurus-plugin-gitbook

A Docusaurus plugin that adds support for GitBook-specific block syntax in MDX files.

📖 Full Documentation

Supported Blocks

| Block | Description | Docs | |-------|-------------|------| | Cover | Page cover image from frontmatter (dark/light mode variants) | View | | Hints | Info, warning, danger, and success callouts | View | | Tabs | Tabbed content panels | View | | Stepper | Numbered step-by-step guides | View | | Columns | Side-by-side column layouts | View | | Code blocks | Code blocks with titles and line numbers | View | | Embeds | Embedded external content (YouTube, etc.) | View | | Files | File download links | View | | Buttons | Primary and secondary action buttons | View | | Cards | Card grid layouts | View | | Icons | Font Awesome icons | View | | OpenAPI | OpenAPI/Swagger endpoint documentation | View |

Installation

npm install docusaurus-plugin-gitbook
# or
yarn add docusaurus-plugin-gitbook

Configuration

Add the plugin to your docusaurus.config.js:

export default {
  plugins: ['docusaurus-plugin-gitbook'],

  // Or with options:
  plugins: [
    ['docusaurus-plugin-gitbook', {
      // options
    }]
  ],
};

Using as Remark/Rehype plugins directly

You can also use the remark and rehype plugins directly:

import { remarkGitBook, rehypeGitBook } from 'docusaurus-plugin-gitbook';

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          remarkPlugins: [remarkGitBook],
          rehypePlugins: [rehypeGitBook],
        },
      },
    ],
  ],
};

Usage

Cover

Page cover images are rendered automatically from the cover frontmatter field GitBook adds to your pages:

---
cover: .gitbook/assets/banner.png
coverY: 0
---

For dark/light mode variants:

---
cover:
  dark: .gitbook/assets/banner-dark.png
  light: .gitbook/assets/banner-light.png
---

The plugin automatically copies .gitbook/assets to your build output so image paths work without any extra configuration.

Hint

{% hint style="info" %}
This is an informational hint.
{% endhint %}

{% hint style="warning" %}
Be careful with this action.
{% endhint %}

{% hint style="danger" %}
This action cannot be undone!
{% endhint %}

{% hint style="success" %}
Operation completed successfully.
{% endhint %}

Tabs

{% tabs %}
{% tab title="JavaScript" %}
\`\`\`javascript
console.log('Hello');
\`\`\`
{% endtab %}

{% tab title="Python" %}
\`\`\`python
print('Hello')
\`\`\`
{% endtab %}
{% endtabs %}

Stepper

{% stepper %}
{% step %}
## Step 1
First step content.
{% endstep %}

{% step %}
## Step 2
Second step content.
{% endstep %}
{% endstepper %}

Columns

{% columns %}
{% column %}
Left column content.
{% endcolumn %}

{% column %}
Right column content.
{% endcolumn %}
{% endcolumns %}

Code with Title

{% code title="example.js" %}
\`\`\`javascript
const foo = 'bar';
\`\`\`
{% endcode %}

Embed

{% embed url="https://www.youtube.com/watch?v=VIDEO_ID" %}

File

{% file src="/path/to/file.pdf" %}
Optional description.
{% endfile %}

Button (HTML)

<a href="https://example.com" class="button primary">Get Started</a>
<a href="https://docs.example.com" class="button secondary">Documentation</a>

Cards (HTML)

<table data-view="cards">
    <thead>
        <tr>
            <th>Title</th>
            <th data-card-target data-type="content-ref">Target</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Getting Started</td>
            <td><a href="getting-started.md">Quick Start</a></td>
        </tr>
    </tbody>
</table>

Styling

The plugin includes default styles that work with Docusaurus's light and dark themes. You can customize the appearance using CSS variables:

:root {
  --gitbook-hint-info-bg: #e7f3ff;
  --gitbook-hint-info-border: #0969da;
  --gitbook-hint-warning-bg: #fff8e6;
  --gitbook-hint-warning-border: #9a6700;
  --gitbook-hint-danger-bg: #ffebe9;
  --gitbook-hint-danger-border: #cf222e;
  --gitbook-hint-success-bg: #dafbe1;
  --gitbook-hint-success-border: #1a7f37;
  /* ... more variables */
}

License

MIT