3 个版本
0.0.2 | 2024年7月28日 |
---|---|
0.0.1 | 2024年6月28日 |
0.0.0 | 2024年5月31日 |
在 文本编辑器 中排名第 97
每月下载量 141
93KB
2K SLoC
mdBook 语言服务器
mdBook-LS 提供一个语言服务器,可以实时预览 mdBook 项目,您在编辑器中输入时,会即时和异步地修补编辑的章节。
mdBook-LS 功能
https://github.com/SichangHe/mdbook_ls/assets/84777573/f75eb653-a143-4191-9c87-e6cb6064e6bc
- 实时预览:在编辑器中输入时,可以立即看到最新的预览。
- 异步修补:不会阻塞您的编辑器;在高负载下,始终尝试渲染最新版本,同时显示中间反馈,使用 一个两-JoinSet。
- 监视周边文件:更改您项目的重要文件(如
.gitignore
、book.toml
、SUMMARY.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 watch
或mdbook serve
不同,后者因为每次文件更改都要重建整本书,效率低下,mdBook-incremental-preview
只修补更改的章节,从而实现即时更新。
mdBook增量预览的使用方法
在项目根目录下运行
mdbook-incremental-preview
它基本上与mdbook serve
的功能相同,但具有增量功能
- 章节更改会逐个修补并推送到浏览器,无需刷新。
- 只有在
.gitignore
、book.toml
、SUMMARY.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