mdbook-gitbook

mdBook 预处理器，用于在 mdBook 中正确渲染 GitBook 特定语法。

您可以通过在 GitBook 上查看相同的示例书籍来比较此预处理器：

• GitBook
• mdBook (通过 GitHub pages)

要查看现有和受支持的语法的列表，请参阅 此 GitHub 问题。

注意

此 mdBook 预处理器是为在 NorthstarWiki 上进行本地渲染而编写的，其中它涵盖了大多数使用的 GitBook 特定语法。因此，我不打算添加对更多 GitBook 小部件等的支持，但是欢迎对扩展受支持的语法做出贡献 <3

同样，如果您想接管此 crate 的维护或所有权，请通过此 crate 的 GitHub 仓库中的问题与联系。

用法

首先，安装预处理器

cargo install mdbook-gitbook

然后，将预处理器添加到您的 book.toml

[book]
authors = ["Jill Doe"]
language = "en"
multilingual = false
src = "src"
title = "My awesome Book"

# ADD THIS
[preprocessor.gitbook]

开发

工作原理

此预处理器主要通过使用正则表达式搜索特定模式，例如

{% embed url="URL_HERE" %}

然后将其替换为相应的 HTML 代码，例如

<div style="border: 1px solid #ccc; padding: 10px; max-width: 500px; margin: 10px">
  <a href="URL_HERE">
    <div style="display: flex; align-items: center;">
      <div style="margin-right: 10px;">
        <img alt="" src="{icon_link}" width="100%" height="auto" decoding="async"
          style="width: 32px; height: 32px; border-radius: 4px;">
      </div>
      <div style="flex-grow: 1;">
        <div style="font-weight: bold; margin-bottom: 5px;">
          EXTRACTED_PAGE_TITLE
        </div>
        <div style="color: #666;">
          EXTRACTED_PAGE_NAME
        </div>
      </div>
    </div>
  </a>
</div>

扩展预处理器

目前支持的语法记录在 此 GitHub 问题

要添加对某些当前不受支持的语法的支持，请扩展现有的 main 渲染循环 lib.rs

/// Apply to all chapters
fn handle_chapter(chapter: &mut Chapter) -> Result<(), Error> {
    chapter.content = hints::render(&chapter.content)?;
    chapter.content = embeds::render(&chapter.content)?;
    chapter.content = content_refs::render(&chapter.content)?;
    // Add your additional syntax parsing here

    Ok(())
}

中的函数，该函数调用相应的解析逻辑。

在您的解析逻辑中，使用正则表达式或其他方法扫描您要支持的语法的特定模式，并将其替换为相应的 HTML 代码。