Extension

<gem-book> renders Markdown and also extends the Markdown syntax. In addition, some methods are provided for users to customize <gem-book>.

Markdown enhancement

Code blocks info string

Syntax:

<language>? <filename>? <status>? <highlight>?

Use highlight example:

# Code Block Info ```md 1 # Code Block Info ```

Fixed heading anchor hash

By default, hash is generated based on the title text field, but sometimes you need to fix the hash, such as internationalization.

### Fixed heading anchor hash {#fixed-hash}

Highlight blockquote

> [!TIP] > This is [highlight blockquote](https://github.com/orgs/community/discussions/16925)

NOTE

This is [!NOTE]

TIP

This is [!TIP]

IMPORTANT

This is [!IMPORTANT]

WARNING

This is [!WARNING]

CAUTION

This is [!CAUTION]

Slots

Slot allows you to customize <gem-book> but the content, currently supported slots are sidebar-before, main-before, main-after, nav-inside.

<!doctype html> <html> <head> <meta charset="UTF-8"> <meta http-equiv="X-UA-Compatible" content="ie=edge"> </head> <body> <style> gem-book:not(:defined) * { display: none; } </style> <gem-book> <gbp-docsearch slot="nav-inside" app-id="05KK61XW6A" api-key="b6738e2ef6d977e01ab3a325b91937e1" index-name="book-gemjs" ></gbp-docsearch> </gem-book> </body> </html>

Can use --template specified template file

Plugins

Use plugin

GemBook uses custom elements as a plugin system, they can customize the rendering of Markdown content or enhance the ability of <gem-book>. The following is how to use the built-in plugin <gbp-raw>.

import plugin:

gem-book docs --plugin raw<script type="module" src="https://unpkg.com/gem-book/plugins/raw.js"></script>

Then use it in Markdown to render files in the warehouse:

<gbp-raw src="/src/plugins/raw.ts"></gbp-raw>

TIP

  1. Attribute should not be line break when using a plugin in Markdown, otherwise it will be interrupted by the <p> tag as the inline element.

  2. GemBook built-in plugin supports automatic import, the disadvantage is that it will be loaded after rendering documents. It is possible that the page will flash

  3. VSCode cannot use Emmet in MarkDown files by default. You can enable it through settings:

    "emmet.excludeLanguages": [], "emmet.includeLanguages": {"markdown": "html"},

Plugin development

GemBook exposes a class GemBookPluginElement, which extends from GemElement, Contains many internal methods and properties, get the GemBookPluginElement and read the <gem-book> configuration in the following way:

customElements.whenDefined('gem-book').then(({ GemBookPluginElement }) => { customElements.define( 'gbp-example', class extends GemBookPluginElement { constructor() { super(); console.log(GemBookPluginElement.config); } }, ); });