Diagnostics

All diagnostics have source vimdoc. Disable all diagnostics with --no-diagnostics or diagnostics: false.

duplicate-tag (error)

Fires when a *tag* is defined more than once.

Same-file duplicate

Two or more *tag* definitions with the same name in the same file.

INTRODUCTION                                          *plugin-intro*

...

APPENDIX                                              *plugin-intro*

Both lines receive the error: duplicate tag definition: *plugin-intro*.

Cross-file duplicate

A *tag* in the current file is also defined in another workspace file.

tag `*api-reference*` is also defined in another file

This catches tag collisions between files in the same doc/ directory. The error appears on every definition of the tag, in every file.

unresolved-tag (warning)

Fires when a |taglink| references a tag that cannot be found in the current file, workspace, or external tag files.

See |nonexistent-tag| for details.

Produces: unresolved tag reference: |nonexistent-tag|.

Reducing false positives

Both tag definitions (*...*) and tag references (|...|) use boundary checks to avoid false positives. A *tag* is only recognized when the opening * is preceded by whitespace or the start of the line. A |tag| requires the same for the opening |. This prevents glob patterns (*.o,*), quoted filenames ("*termcap*"), and path patterns (pack/*/start/*) from being misidentified as tags.

Some valid vimdoc content uses pipes in non-taglink contexts:

• Vim regex alternation: \| inside code blocks
• Lua type unions: string|fun(...)|nil
• Option values: '+,-,+,|'

If a code block is separated from its > opener by a blank line, the server may not recognize the code context and flag pipes as unresolved tags.

To eliminate false positives from external Vim documentation, load the runtime tags (enabled by default):

init_options = {
  runtimeTags = true,
}

Or point to specific tag files:

init_options = {
  tagPaths = { '/path/to/neovim/runtime/doc' },
}

missing-modeline (hint)

Fires when the last non-blank line of a file does not contain a Vim modeline with ft=help or filetype=help.

missing modeline; add ' vim:tw=78:ts=8:ft=help:norl:' to the last line

The conventional modeline for vim help files is:

 vim:tw=78:ts=8:ft=help:norl:

Configuring severity

Every diagnostic code’s severity can be overridden — or suppressed entirely — via diagnosticLevels in initializationOptions:

init_options = {
  diagnosticLevels = {
    ['unresolved-tag'] = 'error',
    ['missing-modeline'] = 'off',
  },
}

Valid levels are "error", "warning", "information", "hint", and "off". Setting a code to "off" suppresses it completely.

When using the check subcommand, pass --ignore CODE to suppress specific codes:

vimdoc-language-server check --ignore missing-modeline doc/

--ignore can be repeated for multiple codes.