mdita-lsp

mdita-lsp

An LSP server for MDITA (Markdown DITA) documents.

Provides comprehensive language support for .md and .mditamap files with 19 diagnostic codes, keyref resolution, incremental text sync, and full IDE integration.

Install

From GitHub Releases

Download the binary for your platform from Releases and place it on your PATH.

From source

go install github.com/aireilly/mdita-lsp/cmd/mdita-lsp@latest

Or clone and build:

git clone https://github.com/aireilly/mdita-lsp.git
cd mdita-lsp
make install   # installs to ~/.local/bin

Ensure the install location is on your PATH:

# For go install:
echo 'export PATH=$PATH:~/go/bin' >> ~/.bashrc
# For make install:
echo 'export PATH=$PATH:~/.local/bin' >> ~/.bashrc
source ~/.bashrc

Editor setup

VS Code

Use any generic LSP client extension with:

{
  "lsp.server.command": "mdita-lsp",
  "lsp.server.filetypes": ["markdown"]
}

Neovim (nvim-lspconfig)

vim.api.nvim_create_autocmd("FileType", {
  pattern = { "markdown" },
  callback = function()
    vim.lsp.start({
      name = "mdita-lsp",
      cmd = { "mdita-lsp" },
      root_dir = vim.fs.dirname(vim.fs.find({ ".mdita-lsp.yaml", ".git" }, { upward = true })[1]),
    })
  end,
})

Helix

Add to ~/.config/helix/languages.toml:

[[language]]
name = "markdown"
language-servers = ["mdita-lsp"]

[language-server.mdita-lsp]
command = "mdita-lsp"

Configuration

Create .mdita-lsp.yaml in your project root or ~/.config/mdita-lsp/config.yaml for user-wide settings.

core:
  markdown:
    file_extensions: [md, markdown, mditamap]
  mdita:
    enable: true
    map_extensions: [mditamap]

completion:
  wiki_style: title-slug

code_actions:
  toc:
    enable: true
    include_levels: [2, 3, 4]
  create_missing_file:
    enable: true

build:
  dita_ot:
    enable: true
    dita_path: ""          # Path to dita binary (empty = search $PATH)
    output_dir: "out"      # Output directory relative to workspace root

diagnostics:
  mdita_compliance: true
  ditamap_validation: true
  keyref_resolution: true
  link_validation: true
  nbsp_detection: true

Features

Diagnostic codes

MDITA map format

.mditamap files define document structure using nested markdown lists:

# Product Documentation

- [Getting Started](getting-started.md)
  - [Installation](install.md)
  - [Configuration](config.md)
- [User Guide](user-guide.md)

Keys are derived from filenames (e.g., install.md → key install). Use [install] in topic files to create keyref shortcut references.

Development

make build     # Build binary
make test      # Run 202 tests with race detection
make lint      # Run golangci-lint
make publish   # Cross-compile for 5 platforms (~3.5 MB each)
make clean     # Remove build artifacts

License

See LICENSE.