is a table with a "show"
and (optionally) a "hide" function. The "show" function has the signature
>
    function(namespace, bufnr, diagnostics, opts)
<
and is responsible for displaying or otherwise handling the given
diagnostics. The "hide" function takes care of "cleaning up" any actions taken
by the "show" function and has the signature
>
    function(namespace, bufnr)
<
Handlers can be configured with |vim.diagnostic.config()| and added by
creating a new key in `vim.diagnostic.handlers` (see
|diagnostic-handlers-example|).

The {opts} table passed to a handler is the full set of configuration options
(that is, it is not limited to just the options for the handler itself). The
values in the table are already resolved (i.e. if a user specifies a
function for a config option, the function has already been evaluated).

If a diagnostic handler is configured with a "severity" key then the list of
diagnostics passed to that handler will be filtered using the value of that
key (see example below).

Nvim provides these handlers by default: "virtual_text", "virtual_lines",
"signs", and "underline".

                                                *diagnostic-handlers-example*
The example below creates a new handler that notifies the user of diagnostics
with |vim.notify()|: >lua

    -- It's good practice to namespace custom handlers to avoid collisions
    vim.diagnostic.handlers["my/notify"] = {
      show = function(namespace, bufnr, diagnostics, opts)
        -- In our example, the opts table has a "log_level" option
        local level = opts["my/notify"].log_level

        local name = vim.diagnostic.get_namespace(namespace).name
        local msg = string.format("%d diagnostics in buffer %d from %s",
                                  #diagnostics,
                                  bufnr,
                                  name)
        vim.notify(msg, level)
      end,
    }

    -- Users can configure the handler
    vim.diagnostic.config({
      ["my/notify"] = {
        log_level = vim.log.levels.INFO,

        -- This handler will only receive "error" diagnostics.
        severity = vim.diagnostic.severity.ERROR,
      }
    })
<
In this example, there is nothing to do when diagnostics are hidden, so we
omit the "hide" function.

Existing handlers can be overridden. For example, use the following to only
show a sign for the highest severity diagnostic on a given line: >lua

    -- Create a custom namespace. This will aggregate signs from all other
    -- namespaces and only show the one with the highest severity on a
    -- given line
    local ns = vim.api.nvim_create_namespace("my_namespace")

    -- Get a reference to the original signs handler
    local orig_signs_handler = vim.diagnostic.handlers.signs

    -- Override the built-in signs handler
    vim.diagnostic.handlers.signs = {
      show = function(_, bufnr, _, opts)
        -- Get all diagnostics from the whole buffer rather than just the
        -- diagnostics passed to the handler
        local diagnostics = vim.diagnostic.get(bufnr)

        -- Find the "worst" diagnostic per line
        local max_severity_per_line = {}
        for _, d in pairs(diagnostics) do
          local m = max_severity_per_line[d.lnum]
          if not m or d.severity < m.severity then
            max_severity_per_line[d.lnum] = d
          end
        end

        -- Pass the filtered diagnostics (with our custom namespace) to
        -- the original handler
        local filtered_diagnostics = vim.tbl_values(max_severity_per_line)
        orig_signs_handler.show(ns, bufnr, filtered_diagnostics, opts)
      end,
      hide = function(_, bufnr)
        orig_signs_handler.hide(ns, bufnr)
      end,
    }
<

                                          *diagnostic-toggle-virtual-lines-example*
Diagnostic handlers can also be toggled. For example, you might want to toggle
the `virtual_lines` handler with the following keymap: >lua

    vim.keymap.set('n', 'gK', function()
      local new_config