mdita-lsp

mdita-lsp

An LSP server for MDITA (Markdown DITA) documents.

Provides comprehensive language support for .md and .mditamap files with 29 diagnostic codes, MDITA extended profile support (domain specializations, task sections, conditional processing), 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 extended profile

mdita-lsp supports the MDITA extended profile with inline attribute syntax for DITA domain specializations:

# Install the software {.task}

## Prerequisites

{platform="linux"}

1. Click **File > Open**{.menucascade} to open the dialog.
2. Edit `config.yaml`{.filepath} to set options.
3. Run the `installer`{.cmdname} command.

## Related information

- [User Guide](user-guide.md)

Supported domain elements

Conditional processing

Block-level attributes for DITA profiling:

{platform="linux" audience="admin"}

Supported attributes: audience, platform, product, otherprops, deliveryTarget, props, rev.

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.

Relationship tables

Tables in .mditamap files are parsed as DITA relationship tables:

| [Overview](overview.md) | [Install](install.md) |
|-------------------------|----------------------|
| [Config](config.md)     | [Troubleshoot](ts.md) |

Map references

Links to .ditamap or .mditamap files are treated as map references (mapref).

Development

make build     # Build binary
make test      # Run 210+ 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.