docs: support inline markdown

- Tags are now created with `[tag]()`
- References are now created with `[tag]`
- Code spans are no longer wrapped

11 files changed, 72 insertions, 56 deletions

diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index b73fad6bfa..6cf77b4648 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -502,7 +502,7 @@ end
 ---@param bufnr integer Buffer number, or 0 for current buffer
 ---@param pos1 integer[]|string Start of region as a (line, column) tuple or |getpos()|-compatible string
 ---@param pos2 integer[]|string End of region as a (line, column) tuple or |getpos()|-compatible string
----@param regtype string \|setreg()|-style selection type
+---@param regtype string [setreg()]-style selection type
 ---@param inclusive boolean Controls whether the ending column is inclusive (see also 'selection').
 ---@return table region Dict of the form `{linenr = {startcol,endcol}}`. `endcol` is exclusive, and
 ---whole lines are returned as `{startcol,endcol} = {0,-1}`.
diff --git a/runtime/lua/vim/_inspector.lua b/runtime/lua/vim/_inspector.lua
index 2999630fce..afbd6211cd 100644
--- a/runtime/lua/vim/_inspector.lua
+++ b/runtime/lua/vim/_inspector.lua
@@ -25,7 +25,7 @@ local defaults = {
 
 ---Get all the items at a given buffer position.
 ---
----Can also be pretty-printed with `:Inspect!`. *:Inspect!*
+---Can also be pretty-printed with `:Inspect!`. [:Inspect!]()
 ---
 ---@param bufnr? integer defaults to the current buffer
 ---@param row? integer row to inspect, 0-based. Defaults to the row of the current cursor
@@ -143,7 +143,7 @@ end
 
 ---Show all the items at a given buffer position.
 ---
----Can also be shown with `:Inspect`. *:Inspect*
+---Can also be shown with `:Inspect`. [:Inspect]()
 ---
 ---@param bufnr? integer defaults to the current buffer
 ---@param row? integer row to inspect, 0-based. Defaults to the row of the current cursor
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index 94eab72291..cb4c8749b8 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -530,7 +530,7 @@ function vim.api.nvim_buf_line_count(buffer) end
 ---               EOL of a line, continue the highlight for the rest of the
 ---               screen line (just like for diff and cursorline highlight).
 ---             • virt_text : virtual text to link to this mark. A list of
----               [text, highlight] tuples, each representing a text chunk
+---               `[text, highlight]` tuples, each representing a text chunk
 ---               with specified highlight. `highlight` element can either be
 ---               a single highlight group, or an array of multiple highlight
 ---               groups that will be stacked (highest priority last). A
@@ -563,8 +563,8 @@ function vim.api.nvim_buf_line_count(buffer) end
 ---                 for "inline" virt_text.
 ---             • virt_lines : virtual lines to add next to this mark This
 ---               should be an array over lines, where each line in turn is an
----               array over [text, highlight] tuples. In general, buffer and
----               window options do not affect the display of the text. In
+---               array over `[text, highlight]` tuples. In general, buffer
+---               and window options do not affect the display of the text. In
 ---               particular 'wrap' and 'linebreak' options do not take
 ---               effect, so the number of extra screen lines will always
 ---               match the size of the array. However the 'tabstop' buffer
@@ -690,9 +690,9 @@ function vim.api.nvim_buf_set_option(buffer, name, value) end
 --- Indexing is zero-based. Row indices are end-inclusive, and column indices
 --- are end-exclusive.
 ---
---- To insert text at a given `(row, column)` location, use `start_row =
---- end_row = row` and `start_col = end_col = col`. To delete the text in a
---- range, use `replacement = {}`.
+--- To insert text at a given `(row, column)` location, use
+--- `start_row = end_row = row` and `start_col = end_col = col`. To delete the
+--- text in a range, use `replacement = {}`.
 ---
 --- Prefer `nvim_buf_set_lines()` if you are only adding or deleting entire
 --- lines.
@@ -903,9 +903,9 @@ function vim.api.nvim_create_augroup(name, opts) end
 ---               • event: (string) name of the triggered event
 ---                 `autocmd-events`
 ---               • group: (number|nil) autocommand group id, if any
----               • match: (string) expanded value of `<amatch>`
----               • buf: (number) expanded value of `<abuf>`
----               • file: (string) expanded value of `<afile>`
+---               • match: (string) expanded value of <amatch>
+---               • buf: (number) expanded value of <abuf>
+---               • file: (string) expanded value of <afile>
 ---               • data: (any) arbitrary data passed from
 ---                 `nvim_exec_autocmds()`
 ---             • command (string) optional: Vim command to execute on event.
@@ -960,22 +960,21 @@ function vim.api.nvim_create_namespace(name) end
 ---                argument that contains the following keys:
 ---                • name: (string) Command name
 ---                • args: (string) The args passed to the command, if any
----                  `<args>`
+---                  <args>
 ---                • fargs: (table) The args split by unescaped whitespace
----                  (when more than one argument is allowed), if any
----                  `<f-args>`
+---                  (when more than one argument is allowed), if any <f-args>
 ---                • nargs: (string) Number of arguments `:command-nargs`
 ---                • bang: (boolean) "true" if the command was executed with a
----                  ! modifier `<bang>`
+---                  ! modifier <bang>
 ---                • line1: (number) The starting line of the command range
----                  `<line1>`
+---                  <line1>
 ---                • line2: (number) The final line of the command range
----                  `<line2>`
+---                  <line2>
 ---                • range: (number) The number of items in the command range:
----                  0, 1, or 2 `<range>`
----                • count: (number) Any count supplied `<count>`
----                • reg: (string) The optional register, if specified `<reg>`
----                • mods: (string) Command modifiers, if any `<mods>`
+---                  0, 1, or 2 <range>
+---                • count: (number) Any count supplied <count>
+---                • reg: (string) The optional register, if specified <reg>
+---                • mods: (string) Command modifiers, if any <mods>
 ---                • smods: (table) Command modifiers in a structured format.
 ---                  Has the same structure as the "mods" key of
 ---                  `nvim_parse_cmd()`.
@@ -1049,9 +1048,9 @@ function vim.api.nvim_del_var(name) end
 
 --- Echo a message.
 ---
---- @param chunks any[] A list of [text, hl_group] arrays, each representing a text
----               chunk with specified highlight. `hl_group` element can be
----               omitted for no highlight.
+--- @param chunks any[] A list of `[text, hl_group]` arrays, each representing a
+---               text chunk with specified highlight. `hl_group` element can
+---               be omitted for no highlight.
 --- @param history boolean if true, add to `message-history`.
 --- @param opts vim.api.keyset.echo_opts Optional parameters.
 ---             • verbose: Message was printed as a result of 'verbose' option
@@ -1134,7 +1133,7 @@ function vim.api.nvim_exec2(src, opts) end
 ---             • buffer (integer) optional: buffer number `autocmd-buflocal`.
 ---               Cannot be used with {pattern}.
 ---             • modeline (bool) optional: defaults to true. Process the
----               modeline after the autocommands `<nomodeline>`.
+---               modeline after the autocommands <nomodeline>.
 ---             • data (any): arbitrary data to send to the autocommand
 ---               callback. See `nvim_create_autocmd()` for details.
 function vim.api.nvim_exec_autocmds(event, opts) end
@@ -1541,7 +1540,7 @@ function vim.api.nvim_notify(msg, log_level, opts) end
 ---               be to the pty master end. For instance, a carriage return is
 ---               sent as a "\r", not as a "\n". `textlock` applies. It is
 ---               possible to call `nvim_chan_send()` directly in the callback
----               however. ["input", term, bufnr, data]
+---               however. `["input", term, bufnr, data]`
 ---             • force_crlf: (boolean, default true) Convert "\n" to "\r\n".
 --- @return integer
 function vim.api.nvim_open_term(buffer, opts) end
@@ -1625,9 +1624,9 @@ function vim.api.nvim_open_term(buffer, opts) end
 ---               • width: Window width (in character cells). Minimum of 1.
 ---               • height: Window height (in character cells). Minimum of 1.
 ---               • bufpos: Places float relative to buffer text (only when
----                 relative="win"). Takes a tuple of zero-indexed [line,
----                 column]. `row` and `col` if given are applied relative to
----                 this position, else they default to:
+---                 relative="win"). Takes a tuple of zero-indexed
+---                 `[line, column]`. `row` and `col` if given are applied
+---                 relative to this position, else they default to:
 ---                 • `row=1` and `col=0` if `anchor` is "NW" or "NE"
 ---                 • `row=0` and `col=0` if `anchor` is "SW" or "SE" (thus
 ---                   like a tooltip near the buffer text).
@@ -1756,8 +1755,8 @@ function vim.api.nvim_parse_cmd(str, opts) end
 ---                operator/space, though also yielding an error).
 ---              • "l" when needing to start parsing with lvalues for ":let"
 ---                or ":for". Common flag sets:
----              • "m" to parse like for ":echo".
----              • "E" to parse like for "<C-r>=".
+---              • "m" to parse like for `":echo"`.
+---              • "E" to parse like for `"<C-r>="`.
 ---              • empty string for ":call".
 ---              • "lm" to parse for ":let".
 --- @param highlight boolean If true, return value will also include "highlight" key
@@ -1887,15 +1886,32 @@ function vim.api.nvim_set_current_win(window) end
 ---
 --- @param ns_id integer Namespace id from `nvim_create_namespace()`
 --- @param opts vim.api.keyset.set_decoration_provider Table of callbacks:
----             • on_start: called first on each screen redraw ["start", tick]
+---             • on_start: called first on each screen redraw
+--- ```
+---                ["start", tick]
+--- ```
+---
 ---             • on_buf: called for each buffer being redrawn (before window
----               callbacks) ["buf", bufnr, tick]
+---               callbacks)
+--- ```
+---                ["buf", bufnr, tick]
+--- ```
+---
 ---             • on_win: called when starting to redraw a specific window.
----               ["win", winid, bufnr, topline, botline]
+--- ```
+---                ["win", winid, bufnr, topline, botline]
+--- ```
+---
 ---             • on_line: called for each buffer line being redrawn. (The
----               interaction with fold lines is subject to change) ["line",
----               winid, bufnr, row]
----             • on_end: called at the end of a redraw cycle ["end", tick]
+---               interaction with fold lines is subject to change)
+--- ```
+---                ["line", winid, bufnr, row]
+--- ```
+---
+---             • on_end: called at the end of a redraw cycle
+--- ```
+---                ["end", tick]
+--- ```
 function vim.api.nvim_set_decoration_provider(ns_id, opts) end
 
 --- Sets a highlight group.
@@ -1955,7 +1971,7 @@ function vim.api.nvim_set_hl_ns_fast(ns_id) end
 --- To set a buffer-local mapping, use `nvim_buf_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.
+--- {lhs} or {rhs}. Empty {rhs} is <Nop>. `keycodes` are replaced as usual.
 ---
 --- Example:
 ---
@@ -1977,7 +1993,7 @@ function vim.api.nvim_set_hl_ns_fast(ns_id) end
 --- @param lhs string Left-hand-side `{lhs}` of the mapping.
 --- @param rhs string Right-hand-side `{rhs}` of the mapping.
 --- @param opts vim.api.keyset.keymap Optional parameters map: Accepts all `:map-arguments` as keys
----             except `<buffer>`, values are booleans (default false). Also:
+---             except <buffer>, values are booleans (default false). Also:
 ---             • "noremap" disables `recursive_mapping`, like `:noremap`
 ---             • "desc" human-readable description.
 ---             • "callback" Lua function called in place of {rhs}.
diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua
index 60dcf8c64a..13ad6cc58f 100644
--- a/runtime/lua/vim/_options.lua
+++ b/runtime/lua/vim/_options.lua
@@ -276,7 +276,7 @@ vim.go = setmetatable({}, {
 })
 
 --- Get or set buffer-scoped |options| for the buffer with number {bufnr}.
---- If [{bufnr}] is omitted then the current buffer is used.
+--- If {bufnr} is omitted then the current buffer is used.
 --- Invalid {bufnr} or key is an error.
 ---
 --- Note: this is equivalent to `:setlocal` for |global-local| options and `:set` otherwise.
@@ -293,7 +293,7 @@ vim.bo = new_buf_opt_accessor()
 
 --- Get or set window-scoped |options| for the window with handle {winid} and
 --- buffer with number {bufnr}. Like `:setlocal` if setting a |global-local| option
---- or if {bufnr} is provided, like `:set` otherwise. If [{winid}] is omitted then
+--- or if {bufnr} is provided, like `:set` otherwise. If {winid} is omitted then
 --- the current window is used. Invalid {winid}, {bufnr} or key is an error.
 ---
 --- Note: only {bufnr} with value `0` (the current buffer in the window) is
diff --git a/runtime/lua/vim/diagnostic.lua b/runtime/lua/vim/diagnostic.lua
index 9483474a40..d5075d7d3d 100644
--- a/runtime/lua/vim/diagnostic.lua
+++ b/runtime/lua/vim/diagnostic.lua
@@ -2,7 +2,7 @@ local api, if_nil = vim.api, vim.F.if_nil
 
 local M = {}
 
---- *diagnostic-structure*
+--- [diagnostic-structure]()
 ---
 --- Diagnostics use the same indexing as the rest of the Nvim API (i.e. 0-based
 --- rows and columns). |api-indexing|
@@ -68,7 +68,7 @@ local M = {}
 ---
 --- Update diagnostics in Insert mode
 --- (if `false`, diagnostics are updated on |InsertLeave|)
---- (default: `false)
+--- (default: `false`)
 --- @field update_in_insert? boolean
 ---
 --- Sort diagnostics by severity. This affects the order in which signs and
diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index 357dd35bdc..a37b7f7858 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -1,7 +1,7 @@
 --- @brief
 ---
---- \*vim.iter()\* is an interface for |iterable|s: it wraps a table or function argument into an
---- \*Iter\* object with methods (such as |Iter:filter()| and |Iter:map()|) that transform the
+--- [vim.iter()]() is an interface for [iterable]s: it wraps a table or function argument into an
+--- [Iter]() object with methods (such as [Iter:filter()] and [Iter:map()]) that transform the
 --- underlying source data. These methods can be chained to create iterator "pipelines": the output
 --- of each pipeline stage is input to the next stage. The first stage depends on the type passed to
 --- `vim.iter()`:
diff --git a/runtime/lua/vim/lsp/client.lua b/runtime/lua/vim/lsp/client.lua
index d0054e073c..ff0db166d5 100644
--- a/runtime/lua/vim/lsp/client.lua
+++ b/runtime/lua/vim/lsp/client.lua
@@ -219,7 +219,7 @@ local validate = vim.validate
 --- checking.
 --- If {handler} is not specified and if there's no respective global
 --- handler, then an error will occur.
---- Returns: {status}, {[client_id]}. {status} is a boolean indicating if
+--- Returns: {status}, {client_id}?. {status} is a boolean indicating if
 --- the notification was successful. If it is `false`, then it will always
 --- be `false` (the client has shutdown).
 --- If {status} is `true`, the function returns {request_id} as the second
@@ -262,7 +262,7 @@ local validate = vim.validate
 ---
 --- Checks if a client supports a given method.
 --- Always returns true for unknown off-spec methods.
---- [opts] is a optional `{bufnr?: integer}` table.
+--- {opts} is a optional `{bufnr?: integer}` table.
 --- Some language server capabilities can be file specific.
 --- @field supports_method fun(method: string, opts?: {bufnr: integer?}): boolean
 ---
diff --git a/runtime/lua/vim/treesitter.lua b/runtime/lua/vim/treesitter.lua
index d1215885d8..a09619f369 100644
--- a/runtime/lua/vim/treesitter.lua
+++ b/runtime/lua/vim/treesitter.lua
@@ -432,10 +432,10 @@ end
 ---
 --- While in the window, press "a" to toggle display of anonymous nodes, "I" to toggle the
 --- display of the source language of each node, "o" to toggle the query editor, and press
---- <Enter> to jump to the node under the cursor in the source buffer. Folding also works
+--- [<Enter>] to jump to the node under the cursor in the source buffer. Folding also works
 --- (try |zo|, |zc|, etc.).
 ---
---- Can also be shown with `:InspectTree`. *:InspectTree*
+--- Can also be shown with `:InspectTree`. [:InspectTree]()
 ---
 ---@param opts table|nil Optional options table with the following possible keys:
 ---                      - lang (string|nil): The language of the source buffer. If omitted, detect
diff --git a/runtime/lua/vim/treesitter/languagetree.lua b/runtime/lua/vim/treesitter/languagetree.lua
index 640477eed4..62714d3f1b 100644
--- a/runtime/lua/vim/treesitter/languagetree.lua
+++ b/runtime/lua/vim/treesitter/languagetree.lua
@@ -1,4 +1,4 @@
---- @brief A \*LanguageTree\* contains a tree of parsers: the root treesitter parser for {lang} and
+--- @brief A [LanguageTree]() contains a tree of parsers: the root treesitter parser for {lang} and
 --- any "injected" language parsers, which themselves may inject other languages, recursively.
 --- For example a Lua buffer containing some Vimscript commands needs multiple parsers to fully
 --- understand its contents.
@@ -93,8 +93,8 @@ local LanguageTree = {}
 ---Optional arguments:
 ---@class vim.treesitter.LanguageTree.new.Opts
 ---@inlinedoc
----@field queries table<string,string>  -- Deprecated
----@field injections table<string,string>
+---@field queries? table<string,string>  -- Deprecated
+---@field injections? table<string,string>
 
 LanguageTree.__index = LanguageTree
 
diff --git a/runtime/lua/vim/treesitter/query.lua b/runtime/lua/vim/treesitter/query.lua
index 85e477be58..a086f5e876 100644
--- a/runtime/lua/vim/treesitter/query.lua
+++ b/runtime/lua/vim/treesitter/query.lua
@@ -995,7 +995,7 @@ end
 
 --- Opens a live editor to query the buffer you started from.
 ---
---- Can also be shown with *:EditQuery*.
+--- Can also be shown with [:EditQuery]().
 ---
 --- If you move the cursor to a capture name ("@foo"), text matching the capture is highlighted in
 --- the source buffer. The query editor is a scratch buffer, use `:write` to save it. You can find
diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index cd8748ede7..0b149700b5 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -12,9 +12,9 @@
 --- end
 --- ```
 ---
---- *vim.version()* returns the version of the current Nvim process.
+--- [vim.version()]() returns the version of the current Nvim process.
 ---
---- VERSION RANGE SPEC *version-range*
+--- VERSION RANGE SPEC [version-range]()
 ---
 --- A version "range spec" defines a semantic version range which can be tested against a version,
 --- using |vim.version.range()|.