docs: support inline markdown

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

7 files changed, 53 insertions, 43 deletions

diff --git a/src/nvim/api/autocmd.c b/src/nvim/api/autocmd.c
index 06f21919f9..d71bcc4bcf 100644
--- a/src/nvim/api/autocmd.c
+++ b/src/nvim/api/autocmd.c
@@ -386,10 +386,10 @@ cleanup:
 ///                 - id: (number) autocommand id
 ///                 - 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>|
-///                 - data: (any) arbitrary data passed from |nvim_exec_autocmds()|
+///                 - 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. Cannot be used with
 ///             {callback}
 ///             - once (boolean) optional: defaults to false. Run the autocommand
@@ -694,7 +694,7 @@ void nvim_del_augroup_by_name(String name, Error *err)
 ///             - 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.
 /// @see |:doautocmd|
diff --git a/src/nvim/api/command.c b/src/nvim/api/command.c
index e08035b0eb..779e216c74 100644
--- a/src/nvim/api/command.c
+++ b/src/nvim/api/command.c
@@ -48,16 +48,16 @@
 /// @param[out] err  Error details, if any.
 /// @return Dictionary containing command information, with these keys:
 ///         - cmd: (string) Command name.
-///         - range: (array) (optional) Command range (|<line1>| |<line2>|).
+///         - range: (array) (optional) Command range ([<line1>] [<line2>]).
 ///                          Omitted if command doesn't accept a range.
 ///                          Otherwise, has no elements if no range was specified, one element if
 ///                          only a single range item was specified, or two elements if both range
 ///                          items were specified.
-///         - count: (number) (optional) Command |<count>|.
+///         - count: (number) (optional) Command [<count>].
 ///                           Omitted if command cannot take a count.
-///         - reg: (string) (optional) Command |<register>|.
+///         - reg: (string) (optional) Command [<register>].
 ///                         Omitted if command cannot take a register.
-///         - bang: (boolean) Whether command contains a |<bang>| (!) modifier.
+///         - bang: (boolean) Whether command contains a [<bang>] (!) modifier.
 ///         - args: (array) Command arguments.
 ///         - addr: (string) Value of |:command-addr|. Uses short name or "line" for -addr=lines.
 ///         - nargs: (string) Value of |:command-nargs|.
@@ -853,17 +853,17 @@ static void build_cmdline_str(char **cmdlinep, exarg_T *eap, CmdParseInfo *cmdin
 ///                 from Lua, the command can also be a Lua function. The function is called with a
 ///                 single table argument that contains the following keys:
 ///                 - name: (string) Command name
-///                 - args: (string) The args passed to the command, if any |<args>|
+///                 - args: (string) The args passed to the command, if any [<args>]
 ///                 - fargs: (table) The args split by unescaped whitespace (when more than one
-///                 argument is allowed), if any |<f-args>|
+///                 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>|
-///                 - line1: (number) The starting line of the command range |<line1>|
-///                 - line2: (number) The final line of the command range |<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>|
+///                 - bang: (boolean) "true" if the command was executed with a ! modifier [<bang>]
+///                 - line1: (number) The starting line of the command range [<line1>]
+///                 - line2: (number) The final line of the command range [<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>]
 ///                 - smods: (table) Command modifiers in a structured format. Has the same
 ///                 structure as the "mods" key of |nvim_parse_cmd()|.
 /// @param  opts    Optional |command-attributes|.
diff --git a/src/nvim/api/extmark.c b/src/nvim/api/extmark.c
index e35840915f..1b03a97edb 100644
--- a/src/nvim/api/extmark.c
+++ b/src/nvim/api/extmark.c
@@ -43,7 +43,7 @@ void api_extmark_free_all_mem(void)
   map_destroy(String, &namespace_ids);
 }
 
-/// Creates a new namespace or gets an existing one. \*namespace\*
+/// Creates a new namespace or gets an existing one. [namespace]()
 ///
 /// Namespaces are used for buffer highlights and virtual text, see
 /// |nvim_buf_add_highlight()| and |nvim_buf_set_extmark()|.
@@ -284,7 +284,7 @@ ArrayOf(Integer) nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id,
 ///                     their start position is less than `start`
 ///          - type: Filter marks by type: "highlight", "sign", "virt_text" and "virt_lines"
 /// @param[out] err   Error details, if any
-/// @return List of [extmark_id, row, col] tuples in "traversal order".
+/// @return List of `[extmark_id, row, col]` tuples in "traversal order".
 Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id, Object start, Object end,
                             Dict(get_extmarks) *opts, Arena *arena, Error *err)
   FUNC_API_SINCE(7)
@@ -390,7 +390,7 @@ Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id, Object start, Object e
 ///                          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
+///                   A list of `[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
@@ -425,7 +425,7 @@ Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id, Object start, Object e
 ///
 ///               - 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
+///                   turn is an 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
@@ -1040,17 +1040,27 @@ void nvim_buf_clear_namespace(Buffer buffer, Integer ns_id, Integer line_start,
 /// @param ns_id  Namespace id from |nvim_create_namespace()|
 /// @param opts  Table of callbacks:
 ///             - on_start: called first on each screen redraw
+///               ```
 ///                 ["start", tick]
+///               ```
 ///             - on_buf: called for each buffer being redrawn (before
-///                 window callbacks)
+///               window callbacks)
+///               ```
 ///                 ["buf", bufnr, tick]
+///               ```
 ///             - on_win: called when starting to redraw a specific window.
+///               ```
 ///                 ["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]
+///               ```
 void nvim_set_decoration_provider(Integer ns_id, Dict(set_decoration_provider) *opts, Error *err)
   FUNC_API_SINCE(7) FUNC_API_LUA_ONLY
 {
diff --git a/src/nvim/api/ui.c b/src/nvim/api/ui.c
index 02433b037c..692e3f95fc 100644
--- a/src/nvim/api/ui.c
+++ b/src/nvim/api/ui.c
@@ -410,7 +410,7 @@ void nvim_ui_try_resize_grid(uint64_t channel_id, Integer grid, Integer width, I
 }
 
 /// Tells Nvim the number of elements displaying in the popupmenu, to decide
-/// <PageUp> and <PageDown> movement.
+/// [<PageUp>] and [<PageDown>] movement.
 ///
 /// @param channel_id
 /// @param height  Popupmenu height, must be greater than zero.
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 6a3c6bab67..84a2f24dbc 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -249,7 +249,7 @@ void nvim_set_hl_ns_fast(Integer ns_id, Error *err)
 ///
 /// On execution error: does not fail, but updates v:errmsg.
 ///
-/// To input sequences like <C-o> use |nvim_replace_termcodes()| (typically
+/// To input sequences like [<C-o>] use |nvim_replace_termcodes()| (typically
 /// with escape_ks=false) to replace |keycodes|, then pass the result to
 /// nvim_feedkeys().
 ///
@@ -337,11 +337,11 @@ void nvim_feedkeys(String keys, String mode, Boolean escape_ks)
 ///
 /// On execution error: does not fail, but updates v:errmsg.
 ///
-/// @note |keycodes| like <CR> are translated, so "<" is special.
-///       To input a literal "<", send <LT>.
+/// @note |keycodes| like [<CR>] are translated, so "<" is special.
+///       To input a literal "<", send [<LT>].
 ///
 /// @note For mouse events use |nvim_input_mouse()|. The pseudokey form
-///       "<LeftMouse><col,row>" is deprecated since |api-level| 6.
+///       `<LeftMouse><col,row>` is deprecated since |api-level| 6.
 ///
 /// @param keys to be typed
 /// @return Number of bytes actually written (can be fewer than
@@ -362,7 +362,7 @@ Integer nvim_input(String keys)
 ///       by calling it multiple times in a loop: the intermediate mouse
 ///       positions will be ignored. It should be used to implement real-time
 ///       mouse input in a GUI. The deprecated pseudokey form
-///       ("<LeftMouse><col,row>") of |nvim_input()| has the same limitation.
+///       (`<LeftMouse><col,row>`) of |nvim_input()| has the same limitation.
 ///
 /// @param button Mouse button: one of "left", "right", "middle", "wheel", "move",
 ///               "x1", "x2".
@@ -451,13 +451,13 @@ error:
                 "invalid button or action");
 }
 
-/// Replaces terminal codes and |keycodes| (<CR>, <Esc>, ...) in a string with
+/// Replaces terminal codes and |keycodes| ([<CR>], [<Esc>], ...) in a string with
 /// the internal representation.
 ///
 /// @param str        String to be converted.
 /// @param from_part  Legacy Vim parameter. Usually true.
-/// @param do_lt      Also translate <lt>. Ignored if `special` is false.
-/// @param special    Replace |keycodes|, e.g. <CR> becomes a "\r" char.
+/// @param do_lt      Also translate [<lt>]. Ignored if `special` is false.
+/// @param special    Replace |keycodes|, e.g. [<CR>] becomes a "\r" char.
 /// @see replace_termcodes
 /// @see cpoptions
 String nvim_replace_termcodes(String str, Boolean from_part, Boolean do_lt, Boolean special)
@@ -525,7 +525,7 @@ Object nvim_notify(String msg, Integer log_level, Dictionary opts, Arena *arena,
 }
 
 /// Calculates the number of display cells occupied by `text`.
-/// Control characters including <Tab> count as one cell.
+/// Control characters including [<Tab>] count as one cell.
 ///
 /// @param text       Some text
 /// @param[out] err   Error details, if any
@@ -762,7 +762,7 @@ void nvim_set_vvar(String name, Object value, Error *err)
 
 /// Echo a message.
 ///
-/// @param chunks  A list of [text, hl_group] arrays, each representing a
+/// @param chunks  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  if true, add to |message-history|.
@@ -1019,7 +1019,7 @@ fail:
 ///            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]
+///                 `["input", term, bufnr, data]`
 ///          - force_crlf: (boolean, default true) Convert "\n" to "\r\n".
 /// @param[out] err Error details, if any
 /// @return Channel id, or 0 on error
@@ -1471,7 +1471,7 @@ ArrayOf(Dictionary) nvim_get_keymap(String mode, Arena *arena)
 /// 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.
+/// Empty {rhs} is [<Nop>]. |keycodes| are replaced as usual.
 ///
 /// Example:
 ///
@@ -1491,7 +1491,7 @@ ArrayOf(Dictionary) nvim_get_keymap(String mode, Arena *arena)
 ///               "ia", "ca" or "!a" for abbreviation in Insert mode, Cmdline mode, or both, respectively
 /// @param  lhs   Left-hand-side |{lhs}| of the mapping.
 /// @param  rhs   Right-hand-side |{rhs}| of the mapping.
-/// @param  opts  Optional parameters map: Accepts all |:map-arguments| as keys except |<buffer>|,
+/// @param  opts  Optional parameters map: Accepts all |:map-arguments| as keys except [<buffer>],
 ///               values are booleans (default false). Also:
 ///               - "noremap" disables |recursive_mapping|, like |:noremap|
 ///               - "desc" human-readable description.
@@ -1521,7 +1521,7 @@ void nvim_del_keymap(uint64_t channel_id, String mode, String lhs, Error *err)
 /// Returns a 2-tuple (Array), where item 0 is the current channel id and item
 /// 1 is the |api-metadata| map (Dictionary).
 ///
-/// @returns 2-tuple [{channel-id}, {api-metadata}]
+/// @returns 2-tuple `[{channel-id}, {api-metadata}]`
 Array nvim_get_api_info(uint64_t channel_id, Arena *arena)
   FUNC_API_SINCE(1) FUNC_API_FAST FUNC_API_REMOTE_ONLY
 {
@@ -1960,7 +1960,7 @@ Object nvim_get_proc(Integer pid, Arena *arena, Error *err)
 /// If neither |ins-completion| nor |cmdline-completion| popup menu is active
 /// this API call is silently ignored.
 /// Useful for an external UI using |ui-popupmenu| to control the popup menu with the mouse.
-/// Can also be used in a mapping; use <Cmd> |:map-cmd| or a Lua mapping to ensure the mapping
+/// Can also be used in a mapping; use [<Cmd>] |:map-cmd| or a Lua mapping to ensure the mapping
 /// doesn't end completion mode.
 ///
 /// @param item    Index (zero-based) of the item to select. Value of -1 selects nothing
diff --git a/src/nvim/api/vimscript.c b/src/nvim/api/vimscript.c
index 8f57e61c76..477cbe2428 100644
--- a/src/nvim/api/vimscript.c
+++ b/src/nvim/api/vimscript.c
@@ -365,8 +365,8 @@ typedef kvec_withinit_t(ExprASTConvStackItem, 16) ExprASTConvStack;
 ///                    - "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[in]  highlight  If true, return value will also include "highlight"
@@ -390,7 +390,7 @@ typedef kvec_withinit_t(ExprASTConvStackItem, 16) ExprASTConvStack;
 ///        - "ast": AST, either nil or a dictionary with these keys:
 ///          - "type": node type, one of the value names from ExprASTNodeType
 ///                    stringified without "kExprNode" prefix.
-///          - "start": a pair [line, column] describing where node is "started"
+///          - "start": a pair `[line, column]` describing where node is "started"
 ///                     where "line" is always 0 (will not be 0 if you will be
 ///                     using this API on e.g. ":let", but that is not
 ///                     present yet). Both elements are Integers.
diff --git a/src/nvim/api/win_config.c b/src/nvim/api/win_config.c
index 3cc520dc78..543c7b8113 100644
--- a/src/nvim/api/win_config.c
+++ b/src/nvim/api/win_config.c
@@ -116,7 +116,7 @@
 ///   - 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].
+///       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"