docs(gen): support language annotation in docstrings

27 files changed, 262 insertions, 264 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 0eccb64517..a8433640ab 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -803,7 +803,7 @@ nvim_feedkeys({keys}, {mode}, {escape_ks})                   *nvim_feedkeys()*
     with escape_ks=false) to replace |keycodes|, then pass the result to
     nvim_feedkeys().
 
-    Example: >
+    Example: >vim
         :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true)
         :call nvim_feedkeys(key, 'n', v:false)
 <
@@ -859,7 +859,7 @@ nvim_get_color_by_name({name})                      *nvim_get_color_by_name()*
     Returns the 24-bit RGB value of a |nvim_get_color_map()| color name or
     "#rrggbb" hexadecimal string.
 
-    Example: >
+    Example: >vim
         :echo nvim_get_color_by_name("Pink")
         :echo nvim_get_color_by_name("#cbcbcb")
 <
@@ -1444,11 +1444,11 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts})             *nvim_set_keymap()*
     Unlike |:map|, leading/trailing whitespace is accepted as part of the
     {lhs} or {rhs}. Empty {rhs} is |<Nop>|. |keycodes| are replaced as usual.
 
-    Example: >
+    Example: >vim
         call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})
 <
 
-    is equivalent to: >
+    is equivalent to: >vim
         nmap <nowait> <Space><NL> <Nop>
 <
 
@@ -1746,7 +1746,7 @@ nvim_create_user_command({name}, {command}, {*opts})
 
     {command} is the replacement text or Lua function to execute.
 
-    Example: >
+    Example: >vim
        :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {})
        :SayHello
        Hello world!
@@ -2027,7 +2027,7 @@ whether a buffer is loaded.
 nvim_buf_attach({buffer}, {send_buffer}, {opts})           *nvim_buf_attach()*
     Activates buffer-update events on a channel, or as Lua callbacks.
 
-    Example (Lua): capture buffer updates in a global `events` variable (use "print(vim.inspect(events))" to see its contents): >
+    Example (Lua): capture buffer updates in a global `events` variable (use "print(vim.inspect(events))" to see its contents): >lua
       events = {}
       vim.api.nvim_buf_attach(0, false, {
         on_lines=function(...) table.insert(events, {...}) end})
@@ -2529,29 +2529,27 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts})
 
     Region can be given as (row,col) tuples, or valid extmark ids (whose
     positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1)
-    respectively, thus the following are equivalent:
->
-    nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
-    nvim_buf_get_extmarks(0, my_ns, [0,0], [-1,-1], {})
+    respectively, thus the following are equivalent: >lua
+      nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
+      nvim_buf_get_extmarks(0, my_ns, [0,0], [-1,-1], {})
 <
 
     If `end` is less than `start`, traversal works backwards. (Useful with
     `limit`, to get the first marks prior to a given position.)
 
-    Example:
->
-    local a   = vim.api
-    local pos = a.nvim_win_get_cursor(0)
-    local ns  = a.nvim_create_namespace('my-plugin')
-    -- Create new extmark at line 1, column 1.
-    local m1  = a.nvim_buf_set_extmark(0, ns, 0, 0, {})
-    -- Create new extmark at line 3, column 1.
-    local m2  = a.nvim_buf_set_extmark(0, ns, 0, 2, {})
-    -- Get extmarks only from line 3.
-    local ms  = a.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {})
-    -- Get all marks in this buffer + namespace.
-    local all = a.nvim_buf_get_extmarks(0, ns, 0, -1, {})
-    print(vim.inspect(ms))
+    Example: >lua
+      local a   = vim.api
+      local pos = a.nvim_win_get_cursor(0)
+      local ns  = a.nvim_create_namespace('my-plugin')
+      -- Create new extmark at line 1, column 1.
+      local m1  = a.nvim_buf_set_extmark(0, ns, 0, 0, {})
+      -- Create new extmark at line 3, column 1.
+      local m2  = a.nvim_buf_set_extmark(0, ns, 0, 2, {})
+      -- Get extmarks only from line 3.
+      local ms  = a.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {})
+      -- Get all marks in this buffer + namespace.
+      local all = a.nvim_buf_get_extmarks(0, ns, 0, -1, {})
+      print(vim.inspect(ms))
 <
 
     Parameters: ~
@@ -2969,12 +2967,12 @@ nvim_open_win({buffer}, {enter}, {*config})                  *nvim_open_win()*
     could let floats hover outside of the main window like a tooltip, but this
     should not be used to specify arbitrary WM screen positions.
 
-    Example (Lua): window-relative float >
+    Example (Lua): window-relative float >lua
         vim.api.nvim_open_win(0, false,
           {relative='win', row=3, col=3, width=12, height=3})
 <
 
-    Example (Lua): buffer-relative float (travels as buffer is scrolled) >
+    Example (Lua): buffer-relative float (travels as buffer is scrolled) >lua
         vim.api.nvim_open_win(0, false,
           {relative='win', width=12, height=3, bufpos={100,10}})
 <
@@ -3210,7 +3208,7 @@ nvim_clear_autocmds({*opts})                           *nvim_clear_autocmds()*
 nvim_create_augroup({name}, {*opts})                   *nvim_create_augroup()*
     Create or get an autocommand group |autocmd-groups|.
 
-    To get an existing group id, do: >
+    To get an existing group id, do: >lua
         local id = vim.api.nvim_create_augroup("MyGroup", {
             clear = false
         })
@@ -3235,7 +3233,7 @@ nvim_create_autocmd({event}, {*opts})                  *nvim_create_autocmd()*
     executed when the autocommand triggers: a callback function (Lua or
     Vimscript), or a command (like regular autocommands).
 
-    Example using callback: >
+    Example using callback: >lua
         -- Lua function
         local myluafun = function() print("This buffer enters") end
 
@@ -3250,40 +3248,39 @@ nvim_create_autocmd({event}, {*opts})                  *nvim_create_autocmd()*
 
     Lua functions receive a table with information about the autocmd event as
     an argument. To use a function which itself accepts another (optional)
-    parameter, wrap the function in a lambda:
->
-    -- Lua function with an optional parameter.
-    -- The autocmd callback would pass a table as argument but this
-    -- function expects number|nil
-    local myluafun = function(bufnr) bufnr = bufnr or vim.api.nvim_get_current_buf() end
-
-    vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
-      pattern = {"*.c", "*.h"},
-      callback = function() myluafun() end,
-    })
+    parameter, wrap the function in a lambda: >lua
+        -- Lua function with an optional parameter.
+        -- The autocmd callback would pass a table as argument but this
+        -- function expects number|nil
+        local myluafun = function(bufnr) bufnr = bufnr or vim.api.nvim_get_current_buf() end
+
+        vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
+          pattern = {"*.c", "*.h"},
+          callback = function() myluafun() end,
+        })
 <
 
-    Example using command: >
+    Example using command: >lua
         vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
           pattern = {"*.c", "*.h"},
           command = "echo 'Entering a C or C++ file'",
         })
 <
 
-    Example values for pattern: >
+    Example values for pattern: >lua
       pattern = "*.py"
       pattern = { "*.py", "*.pyi" }
 <
 
     Note: The `pattern` is passed to callbacks and commands as a literal string; environment
     variables like `$HOME` and `~` are not automatically expanded as they are by |:autocmd|. Instead,
-    |expand()| such variables explicitly: >
+    |expand()| such variables explicitly: >lua
       pattern = vim.fn.expand("~") .. "/some/path/*.py"
 <
 
-    Example values for event: >
-      "BufWritePre"
-      {"CursorHold", "BufWritePre", "BufWritePost"}
+    Example values for event: >lua
+      event = "BufWritePre"
+      event = {"CursorHold", "BufWritePre", "BufWritePost"}
 <
 
     Parameters: ~
@@ -3394,7 +3391,7 @@ nvim_exec_autocmds({event}, {*opts})                    *nvim_exec_autocmds()*
 nvim_get_autocmds({*opts})                               *nvim_get_autocmds()*
     Get all autocommands that match the corresponding {opts}.
 
-    These examples will get autocommands matching ALL the given criteria: >
+    These examples will get autocommands matching ALL the given criteria: >lua
       -- Matches all criteria
       autocommands = vim.api.nvim_get_autocmds({
         group = "MyGroup",
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 6862426b1b..9336321d73 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -185,6 +185,7 @@ Docstring format:
 - Limited markdown is supported.
   - List-items start with `-` (useful to nest or "indent")
 - Use `<pre>` for code samples.
+  Code samples can be annotated as `vim` or `lua`
 
 Example: the help for |nvim_open_win()| is generated from a docstring defined
 in src/nvim/api/win_config.c like this: >
@@ -193,7 +194,7 @@ in src/nvim/api/win_config.c like this: >
     /// ...
     ///
     /// Example (Lua): window-relative float
-    /// <pre>
+    /// <pre>lua
     ///     vim.api.nvim_open_win(0, false,
     ///       {relative='win', row=3, col=3, width=12, height=3})
     /// </pre>
@@ -223,6 +224,7 @@ Docstring format:
 - Limited markdown is supported.
   - List-items start with `-` (useful to nest or "indent")
 - Use `<pre>` for code samples.
+  Code samples can be annotated as `vim` or `lua`
 
 Example: the help for |vim.paste()| is generated from a docstring decorating
 vim.paste in runtime/lua/vim/_editor.lua like this: >
@@ -231,7 +233,7 @@ vim.paste in runtime/lua/vim/_editor.lua like this: >
     --- (such as the |TUI|) pastes text into the editor.
     ---
     --- Example: To remove ANSI color codes when pasting:
-    --- <pre>
+    --- <pre>lua
     --- vim.paste = (function()
     ---   local overridden = vim.paste
     ---   ...
diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index 56c2af10b4..457a41dc08 100644
--- a/runtime/doc/diagnostic.txt
+++ b/runtime/doc/diagnostic.txt
@@ -320,12 +320,12 @@ config({opts}, {namespace})                          *vim.diagnostic.config()*
     |vim.diagnostic.show()|). Ephemeral configuration has highest priority,
     followed by namespace configuration, and finally global configuration.
 
-    For example, if a user enables virtual text globally with >
+    For example, if a user enables virtual text globally with >lua
 
        vim.diagnostic.config({ virtual_text = true })
 <
 
-    and a diagnostic producer sets diagnostics with >
+    and a diagnostic producer sets diagnostics with >lua
 
        vim.diagnostic.set(ns, 0, diagnostics, { virtual_text = false })
 <
@@ -372,14 +372,14 @@ config({opts}, {namespace})                          *vim.diagnostic.config()*
                          to render an LSP diagnostic error code.
                        • format: (function) A function that takes a diagnostic
                          as input and returns a string. The return value is
-                         the text used to display the diagnostic. Example: >
+                         the text used to display the diagnostic. Example: >lua
 
-                           function(diagnostic)
-                             if diagnostic.severity == vim.diagnostic.severity.ERROR then
-                               return string.format("E: %s", diagnostic.message)
+                             function(diagnostic)
+                               if diagnostic.severity == vim.diagnostic.severity.ERROR then
+                                 return string.format("E: %s", diagnostic.message)
+                               end
+                               return diagnostic.message
                              end
-                             return diagnostic.message
-                           end
 <
 
                      • signs: (default true) Use signs for diagnostics.
@@ -553,12 +553,12 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults})
      WARNING filename:27:3: Variable 'foo' does not exist
 <
 
-    This can be parsed into a diagnostic |diagnostic-structure| with: >
+    This can be parsed into a diagnostic |diagnostic-structure| with: >lua
 
-     local s = "WARNING filename:27:3: Variable 'foo' does not exist"
-     local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$"
-     local groups = { "severity", "lnum", "col", "message" }
-     vim.diagnostic.match(s, pattern, groups, { WARNING = vim.diagnostic.WARN })
+       local s = "WARNING filename:27:3: Variable 'foo' does not exist"
+       local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$"
+       local groups = { "severity", "lnum", "col", "message" }
+       vim.diagnostic.match(s, pattern, groups, { WARNING = vim.diagnostic.WARN })
 <
 
     Parameters: ~
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 06c0f466e7..4c4403c38f 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -681,7 +681,7 @@ for_each_buffer_client({bufnr}, {fn})
       • {bufnr}  (number) Buffer number
       • {fn}     (function) Function to run on each client attached to buffer
                  {bufnr}. The function takes the client, client ID, and buffer
-                 number as arguments. Example: >
+                 number as arguments. Example: >lua
 
                    vim.lsp.for_each_buffer_client(0, function(client, client_id, bufnr)
                      print(vim.inspect(client))
@@ -780,14 +780,13 @@ start({config}, {opts})                                      *vim.lsp.start()*
     running client if one is found matching `name` and `root_dir`. Attaches
     the current buffer to the client.
 
-    Example:
->
+    Example: >lua
 
-    vim.lsp.start({
-       name = 'my-server-name',
-       cmd = {'name-of-language-server-executable'},
-       root_dir = vim.fs.dirname(vim.fs.find({'pyproject.toml', 'setup.py'}, { upward = true })[1]),
-    })
+     vim.lsp.start({
+        name = 'my-server-name',
+        cmd = {'name-of-language-server-executable'},
+        root_dir = vim.fs.dirname(vim.fs.find({'pyproject.toml', 'setup.py'}, { upward = true })[1]),
+     })
 <
 
     See |vim.lsp.start_client()| for all available options. The most important
@@ -964,11 +963,9 @@ start_client({config})                                *vim.lsp.start_client()*
 stop_client({client_id}, {force})                      *vim.lsp.stop_client()*
     Stops a client(s).
 
-    You can also use the `stop()` function on a |vim.lsp.client| object. To
-    stop all clients:
->
+    You can also use the `stop()` function on a |vim.lsp.client| object. To stop all clients: >lua
 
-    vim.lsp.stop_client(vim.lsp.get_active_clients())
+     vim.lsp.stop_client(vim.lsp.get_active_clients())
 <
 
     By default asks the server to shutdown, unless stop was requested already
@@ -1078,11 +1075,10 @@ definition({options})                               *vim.lsp.buf.definition()*
 document_highlight()                        *vim.lsp.buf.document_highlight()*
     Send request to the server to resolve document highlights for the current
     text document position. This request can be triggered by a key mapping or
-    by events such as `CursorHold`, e.g.:
->
-    autocmd CursorHold  <buffer> lua vim.lsp.buf.document_highlight()
-    autocmd CursorHoldI <buffer> lua vim.lsp.buf.document_highlight()
-    autocmd CursorMoved <buffer> lua vim.lsp.buf.clear_references()
+    by events such as `CursorHold` , e.g.: >vim
+      autocmd CursorHold  <buffer> lua vim.lsp.buf.document_highlight()
+      autocmd CursorHoldI <buffer> lua vim.lsp.buf.document_highlight()
+      autocmd CursorMoved <buffer> lua vim.lsp.buf.clear_references()
 <
 
     Note: Usage of |vim.lsp.buf.document_highlight()| requires the following
@@ -1126,12 +1122,12 @@ format({options})                                       *vim.lsp.buf.format()*
                      buffer (0).
                    • filter (function|nil): Predicate used to filter clients.
                      Receives a client as argument and must return a boolean.
-                     Clients matching the predicate are included. Example:               • >
+                     Clients matching the predicate are included. Example:               • >lua
 
-            -- Never request typescript-language-server for formatting
-            vim.lsp.buf.format {
-              filter = function(client) return client.name ~= "tsserver" end
-            }
+              -- Never request typescript-language-server for formatting
+              vim.lsp.buf.format {
+                filter = function(client) return client.name ~= "tsserver" end
+              }
 <
                    • async boolean|nil If true the method won't block.
                      Defaults to false. Editing the buffer while formatting
@@ -1253,7 +1249,7 @@ on_publish_diagnostics({_}, {result}, {ctx}, {config})
     |lsp-handler| for the method "textDocument/publishDiagnostics"
 
     See |vim.diagnostic.config()| for configuration options. Handler-specific
-    configuration can be set using |vim.lsp.with()|: >
+    configuration can be set using |vim.lsp.with()|: >lua
 
      vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with(
        vim.lsp.diagnostic.on_publish_diagnostics, {
@@ -1306,8 +1302,9 @@ refresh()                                         *vim.lsp.codelens.refresh()*
     Refresh the codelens for the current buffer
 
     It is recommended to trigger this using an autocmd or via keymap.
->
-    autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh()
+
+    Example: >vim
+      autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh()
 <
 
 run()                                                 *vim.lsp.codelens.run()*
@@ -1326,16 +1323,16 @@ save({lenses}, {bufnr}, {client_id})                 *vim.lsp.codelens.save()*
 Lua module: vim.lsp.handlers                                    *lsp-handlers*
 
 hover({_}, {result}, {ctx}, {config})               *vim.lsp.handlers.hover()*
-    |lsp-handler| for the method "textDocument/hover" >
-
-     vim.lsp.handlers["textDocument/hover"] = vim.lsp.with(
-       vim.lsp.handlers.hover, {
-         -- Use a sharp border with `FloatBorder` highlights
-         border = "single",
-         -- add the title in hover float window
-         title = "hover"
-       }
-     )
+    |lsp-handler| for the method "textDocument/hover" >lua
+
+       vim.lsp.handlers["textDocument/hover"] = vim.lsp.with(
+         vim.lsp.handlers.hover, {
+           -- Use a sharp border with `FloatBorder` highlights
+           border = "single",
+           -- add the title in hover float window
+           title = "hover"
+         }
+       )
 <
 
     Parameters: ~
@@ -1347,14 +1344,14 @@ hover({_}, {result}, {ctx}, {config})               *vim.lsp.handlers.hover()*
                                            *vim.lsp.handlers.signature_help()*
 signature_help({_}, {result}, {ctx}, {config})
     |lsp-handler| for the method "textDocument/signatureHelp". The active
-    parameter is highlighted with |hl-LspSignatureActiveParameter|. >
-
-     vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with(
-       vim.lsp.handlers.signature_help, {
-         -- Use a sharp border with `FloatBorder` highlights
-         border = "single"
-       }
-     )
+    parameter is highlighted with |hl-LspSignatureActiveParameter|. >lua
+
+       vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with(
+         vim.lsp.handlers.signature_help, {
+           -- Use a sharp border with `FloatBorder` highlights
+           border = "single"
+         }
+       )
 <
 
     Parameters: ~
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 1c381bd956..a5e99ae162 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1302,7 +1302,7 @@ cmd({command})                                                     *vim.cmd()*
     Note that `vim.cmd` can be indexed with a command name to return a
     callable function to the command.
 
-    Example: >
+    Example: >lua
 
        vim.cmd('echo 42')
        vim.cmd([[
@@ -1436,7 +1436,7 @@ paste({lines}, {phase})                                          *vim.paste()*
     Paste handler, invoked by |nvim_paste()| when a conforming UI (such as the
     |TUI|) pastes text into the editor.
 
-    Example: To remove ANSI color codes when pasting: >
+    Example: To remove ANSI color codes when pasting: >lua
 
      vim.paste = (function(overridden)
        return function(lines, phase)
@@ -1465,7 +1465,7 @@ paste({lines}, {phase})                                          *vim.paste()*
         |paste| @alias paste_phase -1 | 1 | 2 | 3
 
 pretty_print({...})                                       *vim.pretty_print()*
-    Prints given arguments in human-readable format. Example: >
+    Prints given arguments in human-readable format. Example: >lua
       -- Print highlight group Normal and store it's contents in a variable.
       local hl_normal = vim.pretty_print(vim.api.nvim_get_hl_by_name("Normal", true))
 <
@@ -1544,10 +1544,11 @@ defaulttable({create})                                    *vim.defaulttable()*
     If {create} is `nil`, this will create a defaulttable whose constructor
     function is this function, effectively allowing to create nested tables on
     the fly:
->
 
-    local a = vim.defaulttable()
-    a.b.c = 1
+    >lua
+
+     local a = vim.defaulttable()
+     a.b.c = 1
 <
 
     Parameters: ~
@@ -1637,12 +1638,12 @@ pesc({s})                                                         *vim.pesc()*
 split({s}, {sep}, {kwargs})                                      *vim.split()*
     Splits a string at each instance of a separator.
 
-    Examples: >
+    Examples: >lua
 
-      split(":aa::b:", ":")     => {'','aa','','b',''}
-      split("axaby", "ab?")     => {'','x','y'}
-      split("x*yz*o", "*", {plain=true})  => {'x','yz','o'}
-      split("|x|y|z|", "|", {trimempty=true}) => {'x', 'y', 'z'}
+      split(":aa::b:", ":")                   --> {'','aa','','b',''}
+      split("axaby", "ab?")                   --> {'','x','y'}
+      split("x*yz*o", "*", {plain=true})      --> {'x','yz','o'}
+      split("|x|y|z|", "|", {trimempty=true}) --> {'x', 'y', 'z'}
 <
 
     Parameters: ~
@@ -1695,10 +1696,11 @@ tbl_contains({t}, {value})                                *vim.tbl_contains()*
 
 tbl_count({t})                                               *vim.tbl_count()*
     Counts the number of non-nil values in table `t`.
->
 
-    vim.tbl_count({ a=1, b=2 }) => 2
-    vim.tbl_count({ 1, 2 }) => 2
+    >lua
+
+     vim.tbl_count({ a=1, b=2 })  --> 2
+     vim.tbl_count({ 1, 2 })      --> 2
 <
 
     Parameters: ~
@@ -1771,7 +1773,7 @@ tbl_get({o}, {...})                                            *vim.tbl_get()*
     Index into a table (first argument) via string keys passed as subsequent
     arguments. Return `nil` if the key does not exist.
 
-    Examples: >
+    Examples: >lua
 
       vim.tbl_get({ key = { nested_key = true }}, 'key', 'nested_key') == true
       vim.tbl_get({ key = {}}, 'key', 'nested_key') == nil
@@ -1858,7 +1860,7 @@ trim({s})                                                         *vim.trim()*
 validate({opt})                                               *vim.validate()*
     Validates a parameter specification (types and values).
 
-    Usage example: >
+    Usage example: >lua
 
       function user.new(name, age, hobbies)
         vim.validate{
@@ -1870,25 +1872,25 @@ validate({opt})                                               *vim.validate()*
       end
 <
 
-    Examples with explicit argument values (can be run directly): >
+    Examples with explicit argument values (can be run directly): >lua
 
       vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}}
-         => NOP (success)
+         --> NOP (success)
 
       vim.validate{arg1={1, 'table'}}
-         => error('arg1: expected table, got number')
+         --> error('arg1: expected table, got number')
 
       vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}}
-         => error('arg1: expected even number, got 3')
+         --> error('arg1: expected even number, got 3')
 <
 
-    If multiple types are valid they can be given as a list. >
+    If multiple types are valid they can be given as a list. >lua
 
       vim.validate{arg1={{'foo'}, {'table', 'string'}}, arg2={'foo', {'table', 'string'}}}
-         => NOP (success)
+         --> NOP (success)
 
       vim.validate{arg1={1, {'string', table'}}}
-         => error('arg1: expected string|table, got number')
+         --> error('arg1: expected string|table, got number')
 <
 
     Parameters: ~
@@ -1957,7 +1959,7 @@ Lua module: ui                                                        *lua-ui*
 input({opts}, {on_confirm})                                   *vim.ui.input()*
     Prompts the user for input
 
-    Example: >
+    Example: >lua
 
      vim.ui.input({ prompt = 'Enter value for shiftwidth: ' }, function(input)
          vim.o.shiftwidth = tonumber(input)
@@ -1982,7 +1984,7 @@ input({opts}, {on_confirm})                                   *vim.ui.input()*
 select({items}, {opts}, {on_choice})                         *vim.ui.select()*
     Prompts the user to pick a single item from a collection of entries
 
-    Example: >
+    Example: >lua
 
      vim.ui.select({ 'tabs', 'spaces' }, {
          prompt = 'Select tabs or spaces:',
@@ -2045,7 +2047,7 @@ add({filetypes})                                          *vim.filetype.add()*
 
     See $VIMRUNTIME/lua/vim/filetype.lua for more examples.
 
-    Example: >
+    Example: >lua
 
       vim.filetype.add({
         extension = {
@@ -2081,7 +2083,7 @@ add({filetypes})                                          *vim.filetype.add()*
       })
 <
 
-    To add a fallback match on contents, use >
+    To add a fallback match on contents, use >lua
 
      vim.filetype.add {
        pattern = {
@@ -2120,19 +2122,20 @@ match({args})                                           *vim.filetype.match()*
 
     Each of the three options is specified using a key to the single argument
     of this function. Example:
->
 
-    -- Using a buffer number
-    vim.filetype.match({ buf = 42 })
+    >lua
+
+       -- Using a buffer number
+       vim.filetype.match({ buf = 42 })
 
-    -- Override the filename of the given buffer
-    vim.filetype.match({ buf = 42, filename = 'foo.c' })
+       -- Override the filename of the given buffer
+       vim.filetype.match({ buf = 42, filename = 'foo.c' })
 
-    -- Using a filename without a buffer
-    vim.filetype.match({ filename = 'main.lua' })
+       -- Using a filename without a buffer
+       vim.filetype.match({ filename = 'main.lua' })
 
-    -- Using file contents
-    vim.filetype.match({ contents = {'#!/usr/bin/env bash'} })
+       -- Using file contents
+       vim.filetype.match({ contents = {'#!/usr/bin/env bash'} })
 <
 
     Parameters: ~
@@ -2162,7 +2165,7 @@ match({args})                                           *vim.filetype.match()*
 Lua module: keymap                                                *lua-keymap*
 
 del({modes}, {lhs}, {opts})                                 *vim.keymap.del()*
-    Remove an existing mapping. Examples: >
+    Remove an existing mapping. Examples: >lua
 
        vim.keymap.del('n', 'lhs')
 
@@ -2178,7 +2181,7 @@ del({modes}, {lhs}, {opts})                                 *vim.keymap.del()*
         |vim.keymap.set()|
 
 set({mode}, {lhs}, {rhs}, {opts})                           *vim.keymap.set()*
-    Add a new |mapping|. Examples: >
+    Add a new |mapping|. Examples: >lua
 
        -- Can add mapping to Lua functions
        vim.keymap.set('n', 'lhs', function() print("real lua function") end)
@@ -2197,14 +2200,14 @@ set({mode}, {lhs}, {rhs}, {opts})                           *vim.keymap.set()*
        vim.keymap.set('n', '[%', '<Plug>(MatchitNormalMultiBackward)')
 <
 
-    Note that in a mapping like: >
+    Note that in a mapping like: >lua
 
         vim.keymap.set('n', 'asdf', require('jkl').my_fun)
 <
 
     the `require('jkl')` gets evaluated during this call in order to access the function. If you
     want to avoid this cost at startup you can wrap it in a function, for
-    example: >
+    example: >lua
 
         vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end)
 <
@@ -2302,8 +2305,8 @@ find({names}, {opts})                                          *vim.fs.find()*
                    number of matches.
 
     Return: ~
-        (table) The normalized paths |vim.fs.normalize()| of all matching
-        files or directories
+        (table) Normalized paths |vim.fs.normalize()| of all matching files or
+        directories
 
 normalize({path})                                         *vim.fs.normalize()*
     Normalize a path to a standard format. A tilde (~) character at the
@@ -2311,16 +2314,16 @@ normalize({path})                                         *vim.fs.normalize()*
     backslash (\) characters are converted to forward slashes (/). Environment
     variables are also expanded.
 
-    Examples: >
+    Examples: >lua
 
        vim.fs.normalize('C:\Users\jdoe')
-       => 'C:/Users/jdoe'
+       --> 'C:/Users/jdoe'
 
        vim.fs.normalize('~/src/neovim')
-       => '/home/jdoe/src/neovim'
+       --> '/home/jdoe/src/neovim'
 
        vim.fs.normalize('$XDG_CONFIG_HOME/nvim/init.vim')
-       => '/Users/jdoe/.config/nvim/init.vim'
+       --> '/Users/jdoe/.config/nvim/init.vim'
 <
 
     Parameters: ~
@@ -2332,7 +2335,7 @@ normalize({path})                                         *vim.fs.normalize()*
 parents({start})                                            *vim.fs.parents()*
     Iterate over all the parents of the given file or directory.
 
-    Example: >
+    Example: >lua
 
      local root_dir
      for dir in vim.fs.parents(vim.api.nvim_buf_get_name(0)) do
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index cef48e207f..2a826e90e5 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -605,7 +605,7 @@ start({bufnr}, {lang})                                               *start()*
     required for some plugins. In this case, add `vim.bo.syntax = 'on'` after
     the call to `start`.
 
-    Example: >
+    Example: >lua
 
      vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex',
          callback = function(args)
@@ -770,7 +770,7 @@ Query:iter_captures({self}, {node}, {source}, {start}, {stop})
 
     The iterator returns three values: a numeric id identifying the capture,
     the captured node, and metadata from any directives processing the match.
-    The following example shows how to get captures by name: >
+    The following example shows how to get captures by name: >lua
 
      for id, node, metadata in query:iter_captures(tree:root(), bufnr, first, last) do
        local name = query.captures[id] -- name of the capture in the query
@@ -802,7 +802,7 @@ Query:iter_matches({self}, {node}, {source}, {start}, {stop})
     (1-based) index of the pattern in the query, a table mapping capture
     indices to nodes, and metadata from any directives processing the match.
     If the query has more than one pattern, the capture table might be sparse
-    and e.g. `pairs()` method should be used over `ipairs` . Here is an example iterating over all captures in every match: >
+    and e.g. `pairs()` method should be used over `ipairs` . Here is an example iterating over all captures in every match: >lua
 
      for pattern, match, metadata in cquery:iter_matches(tree:root(), bufnr, first, last) do
        for id, node in pairs(match) do
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index ad4dc20efb..2913a0ddc6 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -123,7 +123,7 @@ do
   --- (such as the |TUI|) pastes text into the editor.
   ---
   --- Example: To remove ANSI color codes when pasting:
-  --- <pre>
+  --- <pre>lua
   --- vim.paste = (function(overridden)
   ---   return function(lines, phase)
   ---     for i,line in ipairs(lines) do
@@ -280,7 +280,7 @@ end
 --- command.
 ---
 --- Example:
---- <pre>
+--- <pre>lua
 ---   vim.cmd('echo 42')
 ---   vim.cmd([[
 ---     augroup My_group
@@ -746,7 +746,7 @@ end
 
 ---Prints given arguments in human-readable format.
 ---Example:
----<pre>
+---<pre>lua
 ---  -- Print highlight group Normal and store it's contents in a variable.
 ---  local hl_normal = vim.pretty_print(vim.api.nvim_get_hl_by_name("Normal", true))
 ---</pre>
diff --git a/runtime/lua/vim/diagnostic.lua b/runtime/lua/vim/diagnostic.lua
index 18df1f1586..7557bc79a2 100644
--- a/runtime/lua/vim/diagnostic.lua
+++ b/runtime/lua/vim/diagnostic.lua
@@ -579,12 +579,12 @@ end
 --- followed by namespace configuration, and finally global configuration.
 ---
 --- For example, if a user enables virtual text globally with
---- <pre>
+--- <pre>lua
 ---   vim.diagnostic.config({ virtual_text = true })
 --- </pre>
 ---
 --- and a diagnostic producer sets diagnostics with
---- <pre>
+--- <pre>lua
 ---   vim.diagnostic.set(ns, 0, diagnostics, { virtual_text = false })
 --- </pre>
 ---
@@ -621,13 +621,13 @@ end
 ---                       * format: (function) A function that takes a diagnostic as input and
 ---                                 returns a string. The return value is the text used to display
 ---                                 the diagnostic. Example:
----                       <pre>
----                       function(diagnostic)
----                         if diagnostic.severity == vim.diagnostic.severity.ERROR then
----                           return string.format("E: %s", diagnostic.message)
+---                       <pre>lua
+---                         function(diagnostic)
+---                           if diagnostic.severity == vim.diagnostic.severity.ERROR then
+---                             return string.format("E: %s", diagnostic.message)
+---                           end
+---                           return diagnostic.message
 ---                         end
----                         return diagnostic.message
----                       end
 ---                       </pre>
 ---       - signs: (default true) Use signs for diagnostics. Options:
 ---                * severity: Only show signs for diagnostics matching the given severity
@@ -1577,11 +1577,11 @@ end
 ---
 --- This can be parsed into a diagnostic |diagnostic-structure|
 --- with:
---- <pre>
---- local s = "WARNING filename:27:3: Variable 'foo' does not exist"
---- local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$"
---- local groups = { "severity", "lnum", "col", "message" }
---- vim.diagnostic.match(s, pattern, groups, { WARNING = vim.diagnostic.WARN })
+--- <pre>lua
+---   local s = "WARNING filename:27:3: Variable 'foo' does not exist"
+---   local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$"
+---   local groups = { "severity", "lnum", "col", "message" }
+---   vim.diagnostic.match(s, pattern, groups, { WARNING = vim.diagnostic.WARN })
 --- </pre>
 ---
 ---@param str string String to parse diagnostics from.
diff --git a/runtime/lua/vim/filetype.lua b/runtime/lua/vim/filetype.lua
index dbad747f8f..e017843548 100644
--- a/runtime/lua/vim/filetype.lua
+++ b/runtime/lua/vim/filetype.lua
@@ -2308,7 +2308,7 @@ end
 --- See $VIMRUNTIME/lua/vim/filetype.lua for more examples.
 ---
 --- Example:
---- <pre>
+--- <pre>lua
 ---  vim.filetype.add({
 ---    extension = {
 ---      foo = 'fooscript',
@@ -2344,7 +2344,7 @@ end
 --- </pre>
 ---
 --- To add a fallback match on contents, use
---- <pre>
+--- <pre>lua
 --- vim.filetype.add {
 ---   pattern = {
 ---     ['.*'] = {
@@ -2456,7 +2456,7 @@ end
 --- Each of the three options is specified using a key to the single argument of this function.
 --- Example:
 ---
---- <pre>
+--- <pre>lua
 ---   -- Using a buffer number
 ---   vim.filetype.match({ buf = 42 })
 ---
diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua
index d128c15233..acfe8821ea 100644
--- a/runtime/lua/vim/fs.lua
+++ b/runtime/lua/vim/fs.lua
@@ -3,7 +3,7 @@ local M = {}
 --- Iterate over all the parents of the given file or directory.
 ---
 --- Example:
---- <pre>
+--- <pre>lua
 --- local root_dir
 --- for dir in vim.fs.parents(vim.api.nvim_buf_get_name(0)) do
 ---   if vim.fn.isdirectory(dir .. "/.git") == 1 then
@@ -98,8 +98,7 @@ end
 ---                       - limit (number, default 1): Stop the search after
 ---                               finding this many matches. Use `math.huge` to
 ---                               place no limit on the number of matches.
----
----@return (table) The normalized paths |vim.fs.normalize()| of all matching files or directories
+---@return (table) Normalized paths |vim.fs.normalize()| of all matching files or directories
 function M.find(names, opts)
   opts = opts or {}
   vim.validate({
@@ -214,15 +213,15 @@ end
 --- variables are also expanded.
 ---
 --- Examples:
---- <pre>
+--- <pre>lua
 ---   vim.fs.normalize('C:\\Users\\jdoe')
----   => 'C:/Users/jdoe'
+---   --> 'C:/Users/jdoe'
 ---
 ---   vim.fs.normalize('~/src/neovim')
----   => '/home/jdoe/src/neovim'
+---   --> '/home/jdoe/src/neovim'
 ---
 ---   vim.fs.normalize('$XDG_CONFIG_HOME/nvim/init.vim')
----   => '/Users/jdoe/.config/nvim/init.vim'
+---   --> '/Users/jdoe/.config/nvim/init.vim'
 --- </pre>
 ---
 ---@param path (string) Path to normalize
diff --git a/runtime/lua/vim/keymap.lua b/runtime/lua/vim/keymap.lua
index af41794c53..ef1c66ea20 100644
--- a/runtime/lua/vim/keymap.lua
+++ b/runtime/lua/vim/keymap.lua
@@ -2,7 +2,7 @@ local keymap = {}
 
 --- Add a new |mapping|.
 --- Examples:
---- <pre>
+--- <pre>lua
 ---   -- Can add mapping to Lua functions
 ---   vim.keymap.set('n', 'lhs', function() print("real lua function") end)
 ---
@@ -21,13 +21,13 @@ local keymap = {}
 --- </pre>
 ---
 --- Note that in a mapping like:
---- <pre>
+--- <pre>lua
 ---    vim.keymap.set('n', 'asdf', require('jkl').my_fun)
 --- </pre>
 ---
 --- the ``require('jkl')`` gets evaluated during this call in order to access the function.
 --- If you want to avoid this cost at startup you can wrap it in a function, for example:
---- <pre>
+--- <pre>lua
 ---    vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end)
 --- </pre>
 ---
@@ -93,7 +93,7 @@ end
 
 --- Remove an existing mapping.
 --- Examples:
---- <pre>
+--- <pre>lua
 ---   vim.keymap.del('n', 'lhs')
 ---
 ---   vim.keymap.del({'n', 'i', 'v'}, '<leader>w', { buffer = 5 })
diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua
index d717275ae4..5bbe4aeba9 100644
--- a/runtime/lua/vim/lsp.lua
+++ b/runtime/lua/vim/lsp.lua
@@ -813,8 +813,7 @@ end
 --- Attaches the current buffer to the client.
 ---
 --- Example:
----
---- <pre>
+--- <pre>lua
 --- vim.lsp.start({
 ---    name = 'my-server-name',
 ---    cmd = {'name-of-language-server-executable'},
@@ -1754,8 +1753,7 @@ end
 ---
 --- You can also use the `stop()` function on a |vim.lsp.client| object.
 --- To stop all clients:
----
---- <pre>
+--- <pre>lua
 --- vim.lsp.stop_client(vim.lsp.get_active_clients())
 --- </pre>
 ---
@@ -2239,7 +2237,7 @@ end
 ---@param fn function Function to run on each client attached to buffer
 ---                   {bufnr}. The function takes the client, client ID, and
 ---                   buffer number as arguments. Example:
----             <pre>
+---             <pre>lua
 ---               vim.lsp.for_each_buffer_client(0, function(client, client_id, bufnr)
 ---                 print(vim.inspect(client))
 ---               end)
diff --git a/runtime/lua/vim/lsp/buf.lua b/runtime/lua/vim/lsp/buf.lua
index c593e72d62..a5a66fd092 100644
--- a/runtime/lua/vim/lsp/buf.lua
+++ b/runtime/lua/vim/lsp/buf.lua
@@ -162,11 +162,11 @@ end
 ---         Predicate used to filter clients. Receives a client as argument and must return a
 ---         boolean. Clients matching the predicate are included. Example:
 ---
----         <pre>
----         -- Never request typescript-language-server for formatting
----         vim.lsp.buf.format {
----           filter = function(client) return client.name ~= "tsserver" end
----         }
+---         <pre>lua
+---           -- Never request typescript-language-server for formatting
+---           vim.lsp.buf.format {
+---             filter = function(client) return client.name ~= "tsserver" end
+---           }
 ---         </pre>
 ---
 ---     - async boolean|nil
@@ -555,11 +555,10 @@ end
 --- Send request to the server to resolve document highlights for the current
 --- text document position. This request can be triggered by a  key mapping or
 --- by events such as `CursorHold`, e.g.:
----
---- <pre>
---- autocmd CursorHold  <buffer> lua vim.lsp.buf.document_highlight()
---- autocmd CursorHoldI <buffer> lua vim.lsp.buf.document_highlight()
---- autocmd CursorMoved <buffer> lua vim.lsp.buf.clear_references()
+--- <pre>vim
+---   autocmd CursorHold  <buffer> lua vim.lsp.buf.document_highlight()
+---   autocmd CursorHoldI <buffer> lua vim.lsp.buf.document_highlight()
+---   autocmd CursorMoved <buffer> lua vim.lsp.buf.clear_references()
 --- </pre>
 ---
 --- Note: Usage of |vim.lsp.buf.document_highlight()| requires the following highlight groups
diff --git a/runtime/lua/vim/lsp/codelens.lua b/runtime/lua/vim/lsp/codelens.lua
index 4fa02c8db2..71b6bfae30 100644
--- a/runtime/lua/vim/lsp/codelens.lua
+++ b/runtime/lua/vim/lsp/codelens.lua
@@ -241,7 +241,8 @@ end
 ---
 --- It is recommended to trigger this using an autocmd or via keymap.
 ---
---- <pre>
+--- Example:
+--- <pre>vim
 ---   autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh()
 --- </pre>
 ---
diff --git a/runtime/lua/vim/lsp/diagnostic.lua b/runtime/lua/vim/lsp/diagnostic.lua
index 1f9d084e2b..5e2bf75f1b 100644
--- a/runtime/lua/vim/lsp/diagnostic.lua
+++ b/runtime/lua/vim/lsp/diagnostic.lua
@@ -150,7 +150,7 @@ end
 ---
 --- See |vim.diagnostic.config()| for configuration options. Handler-specific
 --- configuration can be set using |vim.lsp.with()|:
---- <pre>
+--- <pre>lua
 --- vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with(
 ---   vim.lsp.diagnostic.on_publish_diagnostics, {
 ---     -- Enable underline, use default values
diff --git a/runtime/lua/vim/lsp/handlers.lua b/runtime/lua/vim/lsp/handlers.lua
index 39e2577294..e0162218f1 100644
--- a/runtime/lua/vim/lsp/handlers.lua
+++ b/runtime/lua/vim/lsp/handlers.lua
@@ -313,15 +313,15 @@ M['textDocument/completion'] = function(_, result, _, _)
 end
 
 --- |lsp-handler| for the method "textDocument/hover"
---- <pre>
---- vim.lsp.handlers["textDocument/hover"] = vim.lsp.with(
----   vim.lsp.handlers.hover, {
----     -- Use a sharp border with `FloatBorder` highlights
----     border = "single",
----     -- add the title in hover float window
----     title = "hover"
----   }
---- )
+--- <pre>lua
+---   vim.lsp.handlers["textDocument/hover"] = vim.lsp.with(
+---     vim.lsp.handlers.hover, {
+---       -- Use a sharp border with `FloatBorder` highlights
+---       border = "single",
+---       -- add the title in hover float window
+---       title = "hover"
+---     }
+---   )
 --- </pre>
 ---@param config table Configuration table.
 ---     - border:     (default=nil)
@@ -399,13 +399,13 @@ M['textDocument/implementation'] = location_handler
 
 --- |lsp-handler| for the method "textDocument/signatureHelp".
 --- The active parameter is highlighted with |hl-LspSignatureActiveParameter|.
---- <pre>
---- vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with(
----   vim.lsp.handlers.signature_help, {
----     -- Use a sharp border with `FloatBorder` highlights
----     border = "single"
----   }
---- )
+--- <pre>lua
+---   vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with(
+---     vim.lsp.handlers.signature_help, {
+---       -- Use a sharp border with `FloatBorder` highlights
+---       border = "single"
+---     }
+---   )
 --- </pre>
 ---@param config table Configuration table.
 ---     - border:     (default=nil)
diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index f4a57c13c8..9129500866 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -102,11 +102,11 @@ end
 --- Splits a string at each instance of a separator.
 ---
 --- Examples:
---- <pre>
----  split(":aa::b:", ":")     => {'','aa','','b',''}
----  split("axaby", "ab?")     => {'','x','y'}
----  split("x*yz*o", "*", {plain=true})  => {'x','yz','o'}
----  split("|x|y|z|", "|", {trimempty=true}) => {'x', 'y', 'z'}
+--- <pre>lua
+---  split(":aa::b:", ":")                   --> {'','aa','','b',''}
+---  split("axaby", "ab?")                   --> {'','x','y'}
+---  split("x*yz*o", "*", {plain=true})      --> {'x','yz','o'}
+---  split("|x|y|z|", "|", {trimempty=true}) --> {'x', 'y', 'z'}
 --- </pre>
 ---
 ---@see |vim.gsplit()|
@@ -383,7 +383,7 @@ end
 --- Return `nil` if the key does not exist.
 ---
 --- Examples:
---- <pre>
+--- <pre>lua
 ---  vim.tbl_get({ key = { nested_key = true }}, 'key', 'nested_key') == true
 ---  vim.tbl_get({ key = {}}, 'key', 'nested_key') == nil
 --- </pre>
@@ -495,9 +495,9 @@ end
 
 --- Counts the number of non-nil values in table `t`.
 ---
---- <pre>
---- vim.tbl_count({ a=1, b=2 }) => 2
---- vim.tbl_count({ 1, 2 }) => 2
+--- <pre>lua
+--- vim.tbl_count({ a=1, b=2 })  --> 2
+--- vim.tbl_count({ 1, 2 })      --> 2
 --- </pre>
 ---
 ---@see https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua
@@ -571,7 +571,7 @@ end
 --- Validates a parameter specification (types and values).
 ---
 --- Usage example:
---- <pre>
+--- <pre>lua
 ---  function user.new(name, age, hobbies)
 ---    vim.validate{
 ---      name={name, 'string'},
@@ -583,24 +583,24 @@ end
 --- </pre>
 ---
 --- Examples with explicit argument values (can be run directly):
---- <pre>
+--- <pre>lua
 ---  vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}}
----     => NOP (success)
+---     --> NOP (success)
 ---
 ---  vim.validate{arg1={1, 'table'}}
----     => error('arg1: expected table, got number')
+---     --> error('arg1: expected table, got number')
 ---
 ---  vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}}
----     => error('arg1: expected even number, got 3')
+---     --> error('arg1: expected even number, got 3')
 --- </pre>
 ---
 --- If multiple types are valid they can be given as a list.
---- <pre>
+--- <pre>lua
 ---  vim.validate{arg1={{'foo'}, {'table', 'string'}}, arg2={'foo', {'table', 'string'}}}
----     => NOP (success)
+---     --> NOP (success)
 ---
 ---  vim.validate{arg1={1, {'string', table'}}}
----     => error('arg1: expected string|table, got number')
+---     --> error('arg1: expected string|table, got number')
 ---
 --- </pre>
 ---
@@ -735,7 +735,7 @@ end
 --- If {create} is `nil`, this will create a defaulttable whose constructor function is
 --- this function, effectively allowing to create nested tables on the fly:
 ---
---- <pre>
+--- <pre>lua
 --- local a = vim.defaulttable()
 --- a.b.c = 1
 --- </pre>
diff --git a/runtime/lua/vim/treesitter.lua b/runtime/lua/vim/treesitter.lua
index 6cd00516bf..0603ddb421 100644
--- a/runtime/lua/vim/treesitter.lua
+++ b/runtime/lua/vim/treesitter.lua
@@ -313,7 +313,7 @@ end
 --- In this case, add ``vim.bo.syntax = 'on'`` after the call to `start`.
 ---
 --- Example:
---- <pre>
+--- <pre>lua
 --- vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex',
 ---     callback = function(args)
 ---         vim.treesitter.start(args.buf, 'latex')
diff --git a/runtime/lua/vim/treesitter/query.lua b/runtime/lua/vim/treesitter/query.lua
index 7ca7384a88..4bec5db527 100644
--- a/runtime/lua/vim/treesitter/query.lua
+++ b/runtime/lua/vim/treesitter/query.lua
@@ -549,7 +549,7 @@ end
 --- The iterator returns three values: a numeric id identifying the capture,
 --- the captured node, and metadata from any directives processing the match.
 --- The following example shows how to get captures by name:
---- <pre>
+--- <pre>lua
 --- for id, node, metadata in query:iter_captures(tree:root(), bufnr, first, last) do
 ---   local name = query.captures[id] -- name of the capture in the query
 ---   -- typically useful info about the node:
@@ -603,7 +603,7 @@ end
 --- If the query has more than one pattern, the capture table might be sparse
 --- and e.g. `pairs()` method should be used over `ipairs`.
 --- Here is an example iterating over all captures in every match:
---- <pre>
+--- <pre>lua
 --- for pattern, match, metadata in cquery:iter_matches(tree:root(), bufnr, first, last) do
 ---   for id, node in pairs(match) do
 ---     local name = query.captures[id]
diff --git a/runtime/lua/vim/ui.lua b/runtime/lua/vim/ui.lua
index 97dccd83ab..8f5be15221 100644
--- a/runtime/lua/vim/ui.lua
+++ b/runtime/lua/vim/ui.lua
@@ -21,7 +21,7 @@ local M = {}
 ---
 ---
 --- Example:
---- <pre>
+--- <pre>lua
 --- vim.ui.select({ 'tabs', 'spaces' }, {
 ---     prompt = 'Select tabs or spaces:',
 ---     format_item = function(item)
@@ -78,7 +78,7 @@ end
 ---               `nil` if the user aborted the dialog.
 ---
 --- Example:
---- <pre>
+--- <pre>lua
 --- vim.ui.input({ prompt = 'Enter value for shiftwidth: ' }, function(input)
 ---     vim.o.shiftwidth = tonumber(input)
 --- end)
diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py
index a720f055ed..801c8ea790 100755
--- a/scripts/gen_vimdoc.py
+++ b/scripts/gen_vimdoc.py
@@ -496,7 +496,12 @@ def render_node(n, text, prefix='', indent='', width=text_width - indentation,
     if n.nodeName == 'preformatted':
         o = get_text(n, preformatted=True)
         ensure_nl = '' if o[-1] == '\n' else '\n'
-        text += '>{}{}\n<'.format(ensure_nl, o)
+        if o[0:4] == 'lua\n':
+            text += '>lua{}{}\n<'.format(ensure_nl, o[3:-1])
+        elif o[0:4] == 'vim\n':
+            text += '>vim{}{}\n<'.format(ensure_nl, o[3:-1])
+        else:
+            text += '>{}{}\n<'.format(ensure_nl, o)
 
     elif is_inline(n):
         text = doc_wrap(get_text(n), indent=indent, width=width)
diff --git a/src/nvim/api/autocmd.c b/src/nvim/api/autocmd.c
index af185c50c9..db84ecb5d8 100644
--- a/src/nvim/api/autocmd.c
+++ b/src/nvim/api/autocmd.c
@@ -47,7 +47,7 @@ static int64_t next_autocmd_id = 1;
 /// Get all autocommands that match the corresponding {opts}.
 ///
 /// These examples will get autocommands matching ALL the given criteria:
-/// <pre>
+/// <pre>lua
 ///   -- Matches all criteria
 ///   autocommands = vim.api.nvim_get_autocmds({
 ///     group = "MyGroup",
@@ -367,7 +367,7 @@ cleanup:
 /// triggers: a callback function (Lua or Vimscript), or a command (like regular autocommands).
 ///
 /// Example using callback:
-/// <pre>
+/// <pre>lua
 ///     -- Lua function
 ///     local myluafun = function() print("This buffer enters") end
 ///
@@ -383,8 +383,7 @@ cleanup:
 /// Lua functions receive a table with information about the autocmd event as an argument. To use
 /// a function which itself accepts another (optional) parameter, wrap the function
 /// in a lambda:
-///
-/// <pre>
+/// <pre>lua
 ///     -- Lua function with an optional parameter.
 ///     -- The autocmd callback would pass a table as argument but this
 ///     -- function expects number|nil
@@ -397,7 +396,7 @@ cleanup:
 /// </pre>
 ///
 /// Example using command:
-/// <pre>
+/// <pre>lua
 ///     vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
 ///       pattern = {"*.c", "*.h"},
 ///       command = "echo 'Entering a C or C++ file'",
@@ -405,7 +404,7 @@ cleanup:
 /// </pre>
 ///
 /// Example values for pattern:
-/// <pre>
+/// <pre>lua
 ///   pattern = "*.py"
 ///   pattern = { "*.py", "*.pyi" }
 /// </pre>
@@ -413,14 +412,14 @@ cleanup:
 /// Note: The `pattern` is passed to callbacks and commands as a literal string; environment
 /// variables like `$HOME` and `~` are not automatically expanded as they are by |:autocmd|.
 /// Instead, |expand()| such variables explicitly:
-/// <pre>
+/// <pre>lua
 ///   pattern = vim.fn.expand("~") .. "/some/path/*.py"
 /// </pre>
 ///
 /// Example values for event:
-/// <pre>
-///   "BufWritePre"
-///   {"CursorHold", "BufWritePre", "BufWritePost"}
+/// <pre>lua
+///   event = "BufWritePre"
+///   event = {"CursorHold", "BufWritePre", "BufWritePost"}
 /// </pre>
 ///
 /// @param event (string|array) The event or events to register this autocommand
@@ -703,7 +702,7 @@ cleanup:
 /// Create or get an autocommand group |autocmd-groups|.
 ///
 /// To get an existing group id, do:
-/// <pre>
+/// <pre>lua
 ///     local id = vim.api.nvim_create_augroup("MyGroup", {
 ///         clear = false
 ///     })
diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index 0a31286df7..fe9e6077d6 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -84,7 +84,7 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err)
 ///
 /// Example (Lua): capture buffer updates in a global `events` variable
 /// (use "print(vim.inspect(events))" to see its contents):
-/// <pre>
+/// <pre>lua
 ///   events = {}
 ///   vim.api.nvim_buf_attach(0, false, {
 ///     on_lines=function(...) table.insert(events, {...}) end})
diff --git a/src/nvim/api/command.c b/src/nvim/api/command.c
index 8a7abf0845..416dbc0e5d 100644
--- a/src/nvim/api/command.c
+++ b/src/nvim/api/command.c
@@ -889,7 +889,7 @@ static void build_cmdline_str(char **cmdlinep, exarg_T *eap, CmdParseInfo *cmdin
 /// {command} is the replacement text or Lua function to execute.
 ///
 /// Example:
-/// <pre>
+/// <pre>vim
 ///    :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {})
 ///    :SayHello
 ///    Hello world!
diff --git a/src/nvim/api/extmark.c b/src/nvim/api/extmark.c
index 3a96c42dba..b406672aa5 100644
--- a/src/nvim/api/extmark.c
+++ b/src/nvim/api/extmark.c
@@ -255,8 +255,7 @@ ArrayOf(Integer) nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id,
 /// Region can be given as (row,col) tuples, or valid extmark ids (whose
 /// positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1)
 /// respectively, thus the following are equivalent:
-///
-/// <pre>
+/// <pre>lua
 ///   nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
 ///   nvim_buf_get_extmarks(0, my_ns, [0,0], [-1,-1], {})
 /// </pre>
@@ -265,8 +264,7 @@ ArrayOf(Integer) nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id,
 /// with `limit`, to get the first marks prior to a given position.)
 ///
 /// Example:
-///
-/// <pre>
+/// <pre>lua
 ///   local a   = vim.api
 ///   local pos = a.nvim_win_get_cursor(0)
 ///   local ns  = a.nvim_create_namespace('my-plugin')
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index c3f71cc625..857c03eb27 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -229,7 +229,7 @@ void nvim_set_hl_ns_fast(Integer ns_id, Error *err)
 /// nvim_feedkeys().
 ///
 /// Example:
-/// <pre>
+/// <pre>vim
 ///     :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true)
 ///     :call nvim_feedkeys(key, 'n', v:false)
 /// </pre>
@@ -1295,7 +1295,7 @@ void nvim_unsubscribe(uint64_t channel_id, String event)
 /// "#rrggbb" hexadecimal string.
 ///
 /// Example:
-/// <pre>
+/// <pre>vim
 ///     :echo nvim_get_color_by_name("Pink")
 ///     :echo nvim_get_color_by_name("#cbcbcb")
 /// </pre>
@@ -1437,12 +1437,12 @@ ArrayOf(Dictionary) nvim_get_keymap(String mode)
 /// Empty {rhs} is |<Nop>|. |keycodes| are replaced as usual.
 ///
 /// Example:
-/// <pre>
+/// <pre>vim
 ///     call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})
 /// </pre>
 ///
 /// is equivalent to:
-/// <pre>
+/// <pre>vim
 ///     nmap <nowait> <Space><NL> <Nop>
 /// </pre>
 ///
diff --git a/src/nvim/api/win_config.c b/src/nvim/api/win_config.c
index cfe887d762..828ef2f0eb 100644
--- a/src/nvim/api/win_config.c
+++ b/src/nvim/api/win_config.c
@@ -55,13 +55,13 @@
 /// this should not be used to specify arbitrary WM screen positions.
 ///
 /// Example (Lua): window-relative float
-/// <pre>
+/// <pre>lua
 ///     vim.api.nvim_open_win(0, false,
 ///       {relative='win', row=3, col=3, width=12, height=3})
 /// </pre>
 ///
 /// Example (Lua): buffer-relative float (travels as buffer is scrolled)
-/// <pre>
+/// <pre>lua
 ///     vim.api.nvim_open_win(0, false,
 ///       {relative='win', width=12, height=3, bufpos={100,10}})
 /// </pre>