3 个版本

0.0.2 2024年7月28日
0.0.1 2024年6月28日
0.0.0 2024年5月31日

文本编辑器 中排名第 97

Download history 105/week @ 2024-05-26 18/week @ 2024-06-02 4/week @ 2024-06-09 20/week @ 2024-06-16 142/week @ 2024-06-23 43/week @ 2024-06-30 140/week @ 2024-07-28 1/week @ 2024-08-04

每月下载量 141

MIT 许可证

93KB
2K SLoC

mdBook 语言服务器

mdBook-LS 提供一个语言服务器,可以实时预览 mdBook 项目,您在编辑器中输入时,会即时和异步地修补编辑的章节。

mdBook-LS 功能

https://github.com/SichangHe/mdbook_ls/assets/84777573/f75eb653-a143-4191-9c87-e6cb6064e6bc

  • 实时预览:在编辑器中输入时,可以立即看到最新的预览。
  • 异步修补:不会阻塞您的编辑器;在高负载下,始终尝试渲染最新版本,同时显示中间反馈,使用 一个两-JoinSet
  • 监视周边文件:更改您项目的重要文件(如 .gitignorebook.tomlSUMMARY.md 以及主题目录)并看到书籍完全重建;根据需要重新加载文件监视器和网络服务器。
  • 刷新修补的页面以手动触发完整重建。

编辑器设置

使用 Cargo 安装。
cargo install mdbook_ls -F=build-binary

✅ NeoVim 配置与 LSPConfig

请将下面的 mdbook_ls_setup 函数粘贴到您的 Nvim 配置中,并用您的客户端的 capabilities 调用它。 请参阅我的配置示例

该片段提供了两个 Vim 命令:MDBookLSOpenPreview 启动预览(如果尚未启动)并打开您正在编辑的章节的浏览器;MDBookLSStopPreview 停止更新预览(即使已取消,Warp 也可能在端口上继续服务)。

mdbook_ls_setup 函数。
local function mdbook_ls_setup(capabilities)
    local lspconfig = require('lspconfig')
    local function execute_command_with_params(params)
        local clients = lspconfig.util.get_lsp_clients {
            bufnr = vim.api.nvim_get_current_buf(),
            name = 'mdbook_ls',
        }
        for _, client in ipairs(clients) do
            client.request('workspace/executeCommand', params, nil, 0)
        end
    end
    local function open_preview()
        local params = {
            command = 'open_preview',
            arguments = { "127.0.0.1:33000", vim.api.nvim_buf_get_name(0) },
        }
        execute_command_with_params(params)
    end
    local function stop_preview()
        local params = {
            command = 'stop_preview',
            arguments = {},
        }
        execute_command_with_params(params)
    end

    require('lspconfig.configs')['mdbook_ls'] = {
        default_config = {
            cmd = { 'mdbook-ls' },
            filetypes = { 'markdown' },
            root_dir = lspconfig.util.root_pattern('book.toml'),
        },
        commands = {
            MDBookLSOpenPreview = {
                open_preview,
                description = 'Open mdBook-LS preview',
            },
            MDBookLSStopPreview = {
                stop_preview,
                description = 'Stop mdBook-LS preview',
            },
        },
        docs = {
            description = [[The mdBook Language Server for previewing mdBook projects live.]],
        },
    }
    lspconfig['mdbook_ls'].setup {
        capabilities = capabilities,
    }
end

我计划将来将其合并到 nvim-lspconfig 中。

❓ Visual Studio Code 和其他编辑器设置

没有官方支持,但欢迎社区插件。

我目前不使用 VSCode 和这些其他编辑器,因此我不想为他们维护插件。

但是,由于 mdBook-LS 实现了语言服务器协议 (LSP),因此为它们实现插件应该很简单。因此,请随时自己制作插件,并为我在这里创建一个问题。

mdBook 增量预览

mdBook-Incremental-Preview为mdBook-LS的实时预览功能提供动力。如果您只想在文件保存时更新预览,它也可以独立使用。

mdBook-Incremental-Preview为mdBook项目提供增量预览构建。与mdbook watchmdbook serve不同,后者因为每次文件更改都要重建整本书,效率低下,mdBook-incremental-preview只修补更改的章节,从而实现即时更新。

mdBook增量预览的使用方法

在项目根目录下运行

mdbook-incremental-preview

它基本上与mdbook serve的功能相同,但具有增量功能

  • 章节更改会逐个修补并推送到浏览器,无需刷新。
  • 只有在.gitignorebook.tomlSUMMARY.md或主题目录更改,或者新客户端请求修补页面时,才会进行完整重建。
  • 构建工件存储在内存中的临时目录中。
  • 它直接从源目录提供服务,包括静态文件、额外的JS & CSS和资产文件,而不是复制它们。

修补的详细信息

当章节更改时,我们将其修补内容推送到相应的浏览器选项卡,并替换它们的<main>元素的内容。因此,浏览器不会重新加载页面,而是立即更新内容。

在替换内容后,我们的注入脚本会发出一个load窗口事件。您应该监听此事件,以便在需要时重新运行任何JavaScript代码。下面在MathJax支持部分中有一个示例。

修补的当前限制

  • 不支持跨多个图书项目操作的前处理器。结果可能不正确,或者实现可能回退到完整重建。这是因为我们在修补时向前处理器提供单个章节,而不是整本书。

    这对于大多数只在一个章节上操作的前处理器来说无关紧要。即使link前处理器也有效,因为它直接读取输入文件。

  • print.html或搜索索引都不会进行增量更新。它们仅在完整重建时重建,可以通过刷新修补页面触发。

  • 书模板(index.hbs)必须在<main>标签(默认)中精确包含{{ content }},否则修补将不会正确工作。一种解决方法是允许自定义注入脚本,但除非有需求,否则我不会实现它。

MathJax支持

MathJax.js对于实时预览来说太慢了,因此您应考虑mdBook-KaTeX、客户端侧的KaTeX(如上所述,通过一个监听load事件的自定义脚本)或其他替代方案。

如果您必须坚持使用MathJax,请添加一个监听load事件并重新运行MathJax的自定义脚本,如下所示

document.addEventListener("load", () => MathJax.Hub.Typeset());

调试

我们使用带有 env-filter 功能的 tracing-subscriber 来发出日志^tracing-env-filter。请通过设置环境变量 RUST_LOG 来配置日志级别。

贡献

我欢迎高质量的 issue 和 pull request。

未来工作

  • 单元测试,这样我就不需要在每次提交时在编辑器中测试它。
  • 集成 Open Telemetry,这样我就不需要盯着所有日志了。

依赖

~28–43MB
~714K SLoC