Package Exports

docusaurus-plugin-gitbook
docusaurus-plugin-gitbook/lib/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (docusaurus-plugin-gitbook) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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: /assets/banner.png
coverY: 0
---

For dark/light mode variants:

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

The plugin copies .gitbook/assets to /assets in your build output. References to .gitbook/assets/... are automatically rewritten to /assets/... during processing. If a file would overwrite an existing file under static/assets, the build fails with a clear conflict error.

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