mdBook Language Server

mdBook-LS provides a language server to preview mdBook projects live, patching the edited chapter instantly and asynchronously as you type in your editor.

mdBook-LS Features

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

• Live preview: Instantly see the latest preview as you type in the editor.
• Asynchronous patching: No blocking your editor; under high load, always tries to render the latest version while showing intermediate feedbacks, using a two-JoinSet.
• Peripheral watching: Change the important files of your project (.gitignore, book.toml, SUMMARY.md, and the theme directory) and see the book fully rebuilt; it reloads the file watcher and the web server as needed.
• Refresh a patched page to manually trigger a full rebuild.

Editor Setup

✅ NeoVim setup with LSPConfig

Please paste the below mdbook_ls_setup function in your Nvim configuration and call it with your client's capabilities. Please see my config for an example.

The snippet provides two Vim commands: MDBookLSOpenPreview starts the preview (if not already started) and opens the browser at the chapter you are editing; MDBookLSStopPreview stops updating the preview (Warp may keep serving on the port despite being cancelled).

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

I plan to merge this into nvim-lspconfig in the future.

❓ Visual Studio Code and other editor setup

mdBook Incremental Preview

mdBook-Incremental-Preview powers the live preview feature of mdBook-LS. It can also be used standalone if you only wish to update the preview on file saves.

mdBook-Incremental-Preview provides incremental preview building for mdBook projects. Unlike mdbook watch or mdbook serve, which are inefficient because they rebuild the whole book on file changes, mdBook-incremental-preview only patches the changed chapters, thus producing instant updates.

Usage of mdBook Incremental Preview

At your project root, run:

mdbook-incremental-preview

It has basically the same functionality as mdbook serve but incremental:

• Chapter changes are patched individually and pushed to the browser, without refresh.
• Full rebuilds happen only when the .gitignore, book.toml, SUMMARY.md, or the theme directory changes, or a patched page is requested by a new client.
• Build artifacts are stored in a temporary directory in memory.
• It directly serves static files, additional JS & CSS, and asset files from the source directory, instead of copying them.

Details of patching

When a chapter changes, we push its patched content to the corresponding browser tabs and replace the contents of their <main> elements. So, the browser does not reload the page, but updates the content instantly.

After replacing the content, our injected script issues a load window event. You should listen to this event to rerun any JavaScript code as needed. An example is below in the MathJax support section.

Current limitations of patching

• Preprocessors that operate across multiple book item are not supported. The results may be incorrect, or the implementation may fall back to a full rebuild. This is because we feed the preprocessors the individual chapters rather than the whole book when patching.

  This is irrelevant for most preprocessors, which operate on a single chapter. Even the link preprocessor works because it reads the input files directly.

• Neither print.html or the search index are updated incrementally. They are only rebuilt on full rebuilds, which can be triggered by refreshing a patched page.

• The book template (index.hbs) has to include exactly {{ content }} in the <main> tag (the default), otherwise the patching will not work correctly. A workaround would be to allow custom injected scripts, but I will not implement that unless demanded.

MathJax support

MathJax.js is too slow for live preview, so you should instead consider mdBook-KaTeX, client-side KaTeX (with a custom script that listens to the load event, as mentioned above), or other alternatives.

If you have to stick with MathJax, please add a custom script that listens to the load event and reruns MathJax, like this:

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

Debugging

We use tracing-subscriber with the env-filter feature to emit logs^tracing-env-filter. Please configure the log level by setting the RUST_LOG environment variable.

Contributing

I welcome high-quality issues and pull requests.

Future work

• Unit tests so I do not need to test it in the editor on every commit.
• Integrate with Open Telemetry so I do not need to stare at all the logs.