From 27a566f3f8e07a4cebb426674800bdf9a7f4f222 Mon Sep 17 00:00:00 2001
From: Gregory Anders <8965202+gpanders@users.noreply.github.com>
Date: Wed, 13 Sep 2023 08:38:28 -0500
Subject: [PATCH] feat(vimdoc): support Markdown code blocks (#25127)

Support Markdown code blocks in addition to <pre> blocks in Doxygen doc
comments.

Update doc comments in iter.lua as a test.
---
 runtime/doc/develop.txt  |  16 ++-
 runtime/doc/lua.txt      | 268 +++++++++++++++++++--------------------
 runtime/lua/vim/iter.lua | 179 ++++++++++++++------------
 scripts/gen_vimdoc.py    |  28 +++-
 4 files changed, 271 insertions(+), 220 deletions(-)

diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index b3f7d1fadc..0ed537c248 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -192,7 +192,7 @@ Docstring format:
   `@note`, `@param`, `@returns`
 - Limited markdown is supported.
   - List-items start with `-` (useful to nest or "indent")
-- Use `<pre>` for code samples.
+- Use ``` 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
@@ -202,10 +202,16 @@ in src/nvim/api/win_config.c like this: >
     /// ...
     ///
     /// Example (Lua): window-relative float
-    /// <pre>lua
-    ///     vim.api.nvim_open_win(0, false,
-    ///       {relative='win', row=3, col=3, width=12, height=3})
-    /// </pre>
+    ///
+    /// ```lua
+    /// vim.api.nvim_open_win(0, false, {
+    ///   relative='win',
+    ///   row=3,
+    ///   col=3,
+    ///   width=12,
+    ///   height=3,
+    /// })
+    /// ```
     ///
     /// @param buffer Buffer to display
     /// @param enter  Enter the window
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 71f001f4fc..61afd4698a 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -3229,42 +3229,42 @@ first value returned by the function is nil).
 
 Examples: >lua
 
-   local it = vim.iter({ 1, 2, 3, 4, 5 })
-   it:map(function(v)
-     return v * 3
-   end)
-   it:rev()
-   it:skip(2)
-   it:totable()
-   -- { 9, 6, 3 }
+    local it = vim.iter({ 1, 2, 3, 4, 5 })
+    it:map(function(v)
+      return v * 3
+    end)
+    it:rev()
+    it:skip(2)
+    it:totable()
+    -- { 9, 6, 3 }
 
-   -- ipairs() is a function iterator which returns both the index (i) and the value (v)
-   vim.iter(ipairs({ 1, 2, 3, 4, 5 })):map(function(i, v)
-     if i > 2 then return v end
-   end):totable()
-   -- { 3, 4, 5 }
+    -- ipairs() is a function iterator which returns both the index (i) and the value (v)
+    vim.iter(ipairs({ 1, 2, 3, 4, 5 })):map(function(i, v)
+      if i > 2 then return v end
+    end):totable()
+    -- { 3, 4, 5 }
 
-   local it = vim.iter(vim.gsplit('1,2,3,4,5', ','))
-   it:map(function(s) return tonumber(s) end)
-   for i, d in it:enumerate() do
-     print(string.format("Column %d is %d", i, d))
-   end
-   -- Column 1 is 1
-   -- Column 2 is 2
-   -- Column 3 is 3
-   -- Column 4 is 4
-   -- Column 5 is 5
+    local it = vim.iter(vim.gsplit('1,2,3,4,5', ','))
+    it:map(function(s) return tonumber(s) end)
+    for i, d in it:enumerate() do
+      print(string.format("Column %d is %d", i, d))
+    end
+    -- Column 1 is 1
+    -- Column 2 is 2
+    -- Column 3 is 3
+    -- Column 4 is 4
+    -- Column 5 is 5
 
-   vim.iter({ a = 1, b = 2, c = 3, z = 26 }):any(function(k, v)
-     return k == 'z'
-   end)
-   -- true
+    vim.iter({ a = 1, b = 2, c = 3, z = 26 }):any(function(k, v)
+      return k == 'z'
+    end)
+    -- true
 
-   local rb = vim.ringbuf(3)
-   rb:push("a")
-   rb:push("b")
-   vim.iter(rb):totable()
-   -- { "a", "b" }
+    local rb = vim.ringbuf(3)
+    rb:push("a")
+    rb:push("b")
+    vim.iter(rb):totable()
+    -- { "a", "b" }
 
 <
 
@@ -3276,7 +3276,7 @@ filter({f}, {src}, {...})                                  *vim.iter.filter()*
 
     This is a convenience function that performs: >lua
 
-     vim.iter(src):filter(f):totable()
+        vim.iter(src):filter(f):totable()
 <
 
     Parameters: ~
@@ -3326,25 +3326,25 @@ Iter:enumerate()                                            *Iter:enumerate()*
 
     For list tables, prefer >lua
 
-     vim.iter(ipairs(t))
+        vim.iter(ipairs(t))
 <
 
     over >lua
 
-     vim.iter(t):enumerate()
+        vim.iter(t):enumerate()
 <
 
     as the former is faster.
 
     Example: >lua
 
-     local it = vim.iter(vim.gsplit('abc', '')):enumerate()
-     it:next()
-     -- 1   'a'
-     it:next()
-     -- 2   'b'
-     it:next()
-     -- 3   'c'
+        local it = vim.iter(vim.gsplit('abc', '')):enumerate()
+        it:next()
+        -- 1   'a'
+        it:next()
+        -- 2   'b'
+        it:next()
+        -- 3   'c'
 <
 
     Return: ~
@@ -3355,7 +3355,7 @@ Iter:filter({f})                                               *Iter:filter()*
 
     Example: >lua
 
-     local bufs = vim.iter(vim.api.nvim_list_bufs()):filter(vim.api.nvim_buf_is_loaded)
+        local bufs = vim.iter(vim.api.nvim_list_bufs()):filter(vim.api.nvim_buf_is_loaded)
 <
 
     Parameters: ~
@@ -3374,17 +3374,17 @@ Iter:find({f})                                                   *Iter:find()*
 
     Examples: >lua
 
-     local it = vim.iter({ 3, 6, 9, 12 })
-     it:find(12)
-     -- 12
+        local it = vim.iter({ 3, 6, 9, 12 })
+        it:find(12)
+        -- 12
 
-     local it = vim.iter({ 3, 6, 9, 12 })
-     it:find(20)
-     -- nil
+        local it = vim.iter({ 3, 6, 9, 12 })
+        it:find(20)
+        -- nil
 
-     local it = vim.iter({ 3, 6, 9, 12 })
-     it:find(function(v) return v % 4 == 0 end)
-     -- 12
+        local it = vim.iter({ 3, 6, 9, 12 })
+        it:find(function(v) return v % 4 == 0 end)
+        -- 12
 <
 
     Return: ~
@@ -3395,15 +3395,15 @@ Iter:fold({init}, {f})                                           *Iter:fold()*
 
     Examples: >lua
 
-     -- Create a new table with only even values
-     local t = { a = 1, b = 2, c = 3, d = 4 }
-     local it = vim.iter(t)
-     it:filter(function(k, v) return v % 2 == 0 end)
-     it:fold({}, function(t, k, v)
-       t[k] = v
-       return t
-     end)
-     -- { b = 2, d = 4 }
+        -- Create a new table with only even values
+        local t = { a = 1, b = 2, c = 3, d = 4 }
+        local it = vim.iter(t)
+        it:filter(function(k, v) return v % 2 == 0 end)
+        it:fold({}, function(t, k, v)
+          t[k] = v
+          return t
+        end)
+        -- { b = 2, d = 4 }
 <
 
     Parameters: ~
@@ -3420,13 +3420,13 @@ Iter:last()                                                      *Iter:last()*
 
     Example: >lua
 
-     local it = vim.iter(vim.gsplit('abcdefg', ''))
-     it:last()
-     -- 'g'
+        local it = vim.iter(vim.gsplit('abcdefg', ''))
+        it:last()
+        -- 'g'
 
-     local it = vim.iter({ 3, 6, 9, 12, 15 })
-     it:last()
-     -- 15
+        local it = vim.iter({ 3, 6, 9, 12, 15 })
+        it:last()
+        -- 15
 <
 
     Return: ~
@@ -3439,13 +3439,13 @@ Iter:map({f})                                                     *Iter:map()*
 
     Example: >lua
 
-     local it = vim.iter({ 1, 2, 3, 4 }):map(function(v)
-       if v % 2 == 0 then
-         return v * 3
-       end
-     end)
-     it:totable()
-     -- { 6, 12 }
+        local it = vim.iter({ 1, 2, 3, 4 }):map(function(v)
+          if v % 2 == 0 then
+            return v * 3
+          end
+        end)
+        it:totable()
+        -- { 6, 12 }
 <
 
     Parameters: ~
@@ -3462,13 +3462,13 @@ Iter:next()                                                      *Iter:next()*
 
     Example: >lua
 
-     local it = vim.iter(string.gmatch('1 2 3', 'd+')):map(tonumber)
-     it:next()
-     -- 1
-     it:next()
-     -- 2
-     it:next()
-     -- 3
+        local it = vim.iter(string.gmatch('1 2 3', '%d+')):map(tonumber)
+        it:next()
+        -- 1
+        it:next()
+        -- 2
+        it:next()
+        -- 3
 <
 
     Return: ~
@@ -3481,11 +3481,11 @@ Iter:nextback()                                              *Iter:nextback()*
 
     Example: >lua
 
-     local it = vim.iter({1, 2, 3, 4})
-     it:nextback()
-     -- 4
-     it:nextback()
-     -- 3
+        local it = vim.iter({1, 2, 3, 4})
+        it:nextback()
+        -- 4
+        it:nextback()
+        -- 3
 <
 
     Return: ~
@@ -3498,11 +3498,11 @@ Iter:nth({n})                                                     *Iter:nth()*
 
     Example: >lua
 
-     local it = vim.iter({ 3, 6, 9, 12 })
-     it:nth(2)
-     -- 6
-     it:nth(2)
-     -- 12
+        local it = vim.iter({ 3, 6, 9, 12 })
+        it:nth(2)
+        -- 6
+        it:nth(2)
+        -- 12
 <
 
     Parameters: ~
@@ -3520,11 +3520,11 @@ Iter:nthback({n})                                             *Iter:nthback()*
 
     Example: >lua
 
-     local it = vim.iter({ 3, 6, 9, 12 })
-     it:nthback(2)
-     -- 9
-     it:nthback(2)
-     -- 3
+        local it = vim.iter({ 3, 6, 9, 12 })
+        it:nthback(2)
+        -- 9
+        it:nthback(2)
+        -- 3
 <
 
     Parameters: ~
@@ -3540,13 +3540,13 @@ Iter:peek()                                                      *Iter:peek()*
 
     Example: >lua
 
-     local it = vim.iter({ 3, 6, 9, 12 })
-     it:peek()
-     -- 3
-     it:peek()
-     -- 3
-     it:next()
-     -- 3
+        local it = vim.iter({ 3, 6, 9, 12 })
+        it:peek()
+        -- 3
+        it:peek()
+        -- 3
+        it:next()
+        -- 3
 <
 
     Return: ~
@@ -3559,13 +3559,13 @@ Iter:peekback()                                              *Iter:peekback()*
 
     Example: >lua
 
-     local it = vim.iter({1, 2, 3, 4})
-     it:peekback()
-     -- 4
-     it:peekback()
-     -- 4
-     it:nextback()
-     -- 4
+        local it = vim.iter({1, 2, 3, 4})
+        it:peekback()
+        -- 4
+        it:peekback()
+        -- 4
+        it:nextback()
+        -- 4
 <
 
     Return: ~
@@ -3578,9 +3578,9 @@ Iter:rev()                                                        *Iter:rev()*
 
     Example: >lua
 
-     local it = vim.iter({ 3, 6, 9, 12 }):rev()
-     it:totable()
-     -- { 12, 9, 6, 3 }
+        local it = vim.iter({ 3, 6, 9, 12 }):rev()
+        it:totable()
+        -- { 12, 9, 6, 3 }
 <
 
     Return: ~
@@ -3597,11 +3597,11 @@ Iter:rfind({f})                                                 *Iter:rfind()*
 
     Examples: >lua
 
-     local it = vim.iter({ 1, 2, 3, 2, 1 }):enumerate()
-     it:rfind(1)
-     -- 5   1
-     it:rfind(1)
-     -- 1   1
+        local it = vim.iter({ 1, 2, 3, 2, 1 }):enumerate()
+        it:rfind(1)
+        -- 5   1
+        it:rfind(1)
+        -- 1   1
 <
 
     Return: ~
@@ -3615,9 +3615,9 @@ Iter:skip({n})                                                   *Iter:skip()*
 
     Example: >lua
 
-     local it = vim.iter({ 3, 6, 9, 12 }):skip(2)
-     it:next()
-     -- 9
+        local it = vim.iter({ 3, 6, 9, 12 }):skip(2)
+        it:next()
+        -- 9
 <
 
     Parameters: ~
@@ -3633,11 +3633,11 @@ Iter:skipback({n})                                           *Iter:skipback()*
 
     Example: >lua
 
-     local it = vim.iter({ 1, 2, 3, 4, 5 }):skipback(2)
-     it:next()
-     -- 1
-     it:nextback()
-     -- 3
+        local it = vim.iter({ 1, 2, 3, 4, 5 }):skipback(2)
+        it:next()
+        -- 1
+        it:nextback()
+        -- 3
 <
 
     Parameters: ~
@@ -3670,14 +3670,14 @@ Iter:totable()                                                *Iter:totable()*
 
     Examples: >lua
 
-     vim.iter(string.gmatch('100 20 50', 'd+')):map(tonumber):totable()
-     -- { 100, 20, 50 }
+        vim.iter(string.gmatch('100 20 50', '%d+')):map(tonumber):totable()
+        -- { 100, 20, 50 }
 
-     vim.iter({ 1, 2, 3 }):map(function(v) return v, 2 * v end):totable()
-     -- { { 1, 2 }, { 2, 4 }, { 3, 6 } }
+        vim.iter({ 1, 2, 3 }):map(function(v) return v, 2 * v end):totable()
+        -- { { 1, 2 }, { 2, 4 }, { 3, 6 } }
 
-     vim.iter({ a = 1, b = 2, c = 3 }):filter(function(k, v) return v % 2 ~= 0 end):totable()
-     -- { { 'a', 1 }, { 'c', 3 } }
+        vim.iter({ a = 1, b = 2, c = 3 }):filter(function(k, v) return v % 2 ~= 0 end):totable()
+        -- { { 'a', 1 }, { 'c', 3 } }
 <
 
     The generated table is a list-like table with consecutive, numeric
@@ -3692,7 +3692,7 @@ map({f}, {src}, {...})                                        *vim.iter.map()*
 
     This is a convenience function that performs: >lua
 
-     vim.iter(src):map(f):totable()
+        vim.iter(src):map(f):totable()
 <
 
     Parameters: ~
@@ -3712,7 +3712,7 @@ totable({f}, {...})                                       *vim.iter.totable()*
 
     This is a convenience function that performs: >lua
 
-     vim.iter(f):totable()
+        vim.iter(f):totable()
 <
 
     Parameters: ~
diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index 56c130dd0c..595baa7019 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -15,44 +15,45 @@
 --- (for function iterators, this means that the first value returned by the function is nil).
 ---
 --- Examples:
---- <pre>lua
----   local it = vim.iter({ 1, 2, 3, 4, 5 })
----   it:map(function(v)
----     return v * 3
----   end)
----   it:rev()
----   it:skip(2)
----   it:totable()
----   -- { 9, 6, 3 }
 ---
----   -- ipairs() is a function iterator which returns both the index (i) and the value (v)
----   vim.iter(ipairs({ 1, 2, 3, 4, 5 })):map(function(i, v)
----     if i > 2 then return v end
----   end):totable()
----   -- { 3, 4, 5 }
+--- ```lua
+--- local it = vim.iter({ 1, 2, 3, 4, 5 })
+--- it:map(function(v)
+---   return v * 3
+--- end)
+--- it:rev()
+--- it:skip(2)
+--- it:totable()
+--- -- { 9, 6, 3 }
 ---
----   local it = vim.iter(vim.gsplit('1,2,3,4,5', ','))
----   it:map(function(s) return tonumber(s) end)
----   for i, d in it:enumerate() do
----     print(string.format("Column %d is %d", i, d))
----   end
----   -- Column 1 is 1
----   -- Column 2 is 2
----   -- Column 3 is 3
----   -- Column 4 is 4
----   -- Column 5 is 5
+--- -- ipairs() is a function iterator which returns both the index (i) and the value (v)
+--- vim.iter(ipairs({ 1, 2, 3, 4, 5 })):map(function(i, v)
+---   if i > 2 then return v end
+--- end):totable()
+--- -- { 3, 4, 5 }
 ---
----   vim.iter({ a = 1, b = 2, c = 3, z = 26 }):any(function(k, v)
----     return k == 'z'
----   end)
----   -- true
+--- local it = vim.iter(vim.gsplit('1,2,3,4,5', ','))
+--- it:map(function(s) return tonumber(s) end)
+--- for i, d in it:enumerate() do
+---   print(string.format("Column %d is %d", i, d))
+--- end
+--- -- Column 1 is 1
+--- -- Column 2 is 2
+--- -- Column 3 is 3
+--- -- Column 4 is 4
+--- -- Column 5 is 5
 ---
----   local rb = vim.ringbuf(3)
----   rb:push("a")
----   rb:push("b")
----   vim.iter(rb):totable()
----   -- { "a", "b" }
---- </pre>
+--- vim.iter({ a = 1, b = 2, c = 3, z = 26 }):any(function(k, v)
+---   return k == 'z'
+--- end)
+--- -- true
+---
+--- local rb = vim.ringbuf(3)
+--- rb:push("a")
+--- rb:push("b")
+--- vim.iter(rb):totable()
+--- -- { "a", "b" }
+--- ```
 ---
 --- In addition to the |vim.iter()| function, the |vim.iter| module provides
 --- convenience functions like |vim.iter.filter()| and |vim.iter.totable()|.
@@ -140,9 +141,10 @@ end
 --- Add a filter step to the iterator pipeline.
 ---
 --- Example:
---- <pre>lua
+---
+--- ```lua
 --- local bufs = vim.iter(vim.api.nvim_list_bufs()):filter(vim.api.nvim_buf_is_loaded)
---- </pre>
+--- ```
 ---
 ---@param f function(...):bool Takes all values returned from the previous stage
 ---                            in the pipeline and returns false or nil if the
@@ -176,7 +178,8 @@ end
 --- If the map function returns nil, the value is filtered from the iterator.
 ---
 --- Example:
---- <pre>lua
+---
+--- ```lua
 --- local it = vim.iter({ 1, 2, 3, 4 }):map(function(v)
 ---   if v % 2 == 0 then
 ---     return v * 3
@@ -184,7 +187,7 @@ end
 --- end)
 --- it:totable()
 --- -- { 6, 12 }
---- </pre>
+--- ```
 ---
 ---@param f function(...):any Mapping function. Takes all values returned from
 ---                           the previous stage in the pipeline as arguments
@@ -288,7 +291,8 @@ end
 --- pipeline, each value will be included in a table.
 ---
 --- Examples:
---- <pre>lua
+---
+--- ```lua
 --- vim.iter(string.gmatch('100 20 50', '%d+')):map(tonumber):totable()
 --- -- { 100, 20, 50 }
 ---
@@ -297,7 +301,7 @@ end
 ---
 --- vim.iter({ a = 1, b = 2, c = 3 }):filter(function(k, v) return v % 2 ~= 0 end):totable()
 --- -- { { 'a', 1 }, { 'c', 3 } }
---- </pre>
+--- ```
 ---
 --- The generated table is a list-like table with consecutive, numeric indices.
 --- To create a map-like table with arbitrary keys, use |Iter:fold()|.
@@ -352,7 +356,8 @@ end
 --- Fold ("reduce") an iterator or table into a single value.
 ---
 --- Examples:
---- <pre>lua
+---
+--- ```lua
 --- -- Create a new table with only even values
 --- local t = { a = 1, b = 2, c = 3, d = 4 }
 --- local it = vim.iter(t)
@@ -362,7 +367,7 @@ end
 ---   return t
 --- end)
 --- -- { b = 2, d = 4 }
---- </pre>
+--- ```
 ---
 ---@generic A
 ---
@@ -398,7 +403,8 @@ end
 --- Return the next value from the iterator.
 ---
 --- Example:
---- <pre>lua
+---
+--- ```lua
 ---
 --- local it = vim.iter(string.gmatch('1 2 3', '%d+')):map(tonumber)
 --- it:next()
@@ -408,7 +414,7 @@ end
 --- it:next()
 --- -- 3
 ---
---- </pre>
+--- ```
 ---
 ---@return any
 function Iter.next(self) -- luacheck: no unused args
@@ -431,13 +437,14 @@ end
 --- Only supported for iterators on list-like tables.
 ---
 --- Example:
---- <pre>lua
+---
+--- ```lua
 ---
 --- local it = vim.iter({ 3, 6, 9, 12 }):rev()
 --- it:totable()
 --- -- { 12, 9, 6, 3 }
 ---
---- </pre>
+--- ```
 ---
 ---@return Iter
 function Iter.rev(self)
@@ -457,7 +464,8 @@ end
 --- Only supported for iterators on list-like tables.
 ---
 --- Example:
---- <pre>lua
+---
+--- ```lua
 ---
 --- local it = vim.iter({ 3, 6, 9, 12 })
 --- it:peek()
@@ -467,7 +475,7 @@ end
 --- it:next()
 --- -- 3
 ---
---- </pre>
+--- ```
 ---
 ---@return any
 function Iter.peek(self) -- luacheck: no unused args
@@ -486,7 +494,8 @@ end
 --- Advances the iterator. Returns nil and drains the iterator if no value is found.
 ---
 --- Examples:
---- <pre>lua
+---
+--- ```lua
 ---
 --- local it = vim.iter({ 3, 6, 9, 12 })
 --- it:find(12)
@@ -500,7 +509,7 @@ end
 --- it:find(function(v) return v % 4 == 0 end)
 --- -- 12
 ---
---- </pre>
+--- ```
 ---
 ---@return any
 function Iter.find(self, f)
@@ -536,7 +545,8 @@ end
 --- Only supported for iterators on list-like tables.
 ---
 --- Examples:
---- <pre>lua
+---
+--- ```lua
 ---
 --- local it = vim.iter({ 1, 2, 3, 2, 1 }):enumerate()
 --- it:rfind(1)
@@ -544,7 +554,7 @@ end
 --- it:rfind(1)
 --- -- 1	1
 ---
---- </pre>
+--- ```
 ---
 ---@see Iter.find
 ---
@@ -578,13 +588,14 @@ end
 --- Only supported for iterators on list-like tables.
 ---
 --- Example:
---- <pre>lua
+---
+--- ```lua
 --- local it = vim.iter({1, 2, 3, 4})
 --- it:nextback()
 --- -- 4
 --- it:nextback()
 --- -- 3
---- </pre>
+--- ```
 ---
 ---@return any
 function Iter.nextback(self) -- luacheck: no unused args
@@ -604,7 +615,8 @@ end
 --- Only supported for iterators on list-like tables.
 ---
 --- Example:
---- <pre>lua
+---
+--- ```lua
 --- local it = vim.iter({1, 2, 3, 4})
 --- it:peekback()
 --- -- 4
@@ -612,7 +624,7 @@ end
 --- -- 4
 --- it:nextback()
 --- -- 4
---- </pre>
+--- ```
 ---
 ---@return any
 function Iter.peekback(self) -- luacheck: no unused args
@@ -629,13 +641,14 @@ end
 --- Skip values in the iterator.
 ---
 --- Example:
---- <pre>lua
+---
+--- ```lua
 ---
 --- local it = vim.iter({ 3, 6, 9, 12 }):skip(2)
 --- it:next()
 --- -- 9
 ---
---- </pre>
+--- ```
 ---
 ---@param n number Number of values to skip.
 ---@return Iter
@@ -661,13 +674,14 @@ end
 --- Only supported for iterators on list-like tables.
 ---
 --- Example:
---- <pre>lua
+---
+--- ```lua
 --- local it = vim.iter({ 1, 2, 3, 4, 5 }):skipback(2)
 --- it:next()
 --- -- 1
 --- it:nextback()
 --- -- 3
---- </pre>
+--- ```
 ---
 ---@param n number Number of values to skip.
 ---@return Iter
@@ -691,7 +705,8 @@ end
 --- This function advances the iterator.
 ---
 --- Example:
---- <pre>lua
+---
+--- ```lua
 ---
 --- local it = vim.iter({ 3, 6, 9, 12 })
 --- it:nth(2)
@@ -699,7 +714,7 @@ end
 --- it:nth(2)
 --- -- 12
 ---
---- </pre>
+--- ```
 ---
 ---@param n number The index of the value to return.
 ---@return any
@@ -716,7 +731,8 @@ end
 --- Only supported for iterators on list-like tables.
 ---
 --- Example:
---- <pre>lua
+---
+--- ```lua
 ---
 --- local it = vim.iter({ 3, 6, 9, 12 })
 --- it:nthback(2)
@@ -724,7 +740,7 @@ end
 --- it:nthback(2)
 --- -- 3
 ---
---- </pre>
+--- ```
 ---
 ---@param n number The index of the value to return.
 ---@return any
@@ -805,7 +821,8 @@ end
 --- Drains the iterator.
 ---
 --- Example:
---- <pre>lua
+---
+--- ```lua
 ---
 --- local it = vim.iter(vim.gsplit('abcdefg', ''))
 --- it:last()
@@ -815,7 +832,7 @@ end
 --- it:last()
 --- -- 15
 ---
---- </pre>
+--- ```
 ---
 ---@return any
 function Iter.last(self)
@@ -839,19 +856,22 @@ end
 --- Add an iterator stage that returns the current iterator count as well as the iterator value.
 ---
 --- For list tables, prefer
---- <pre>lua
+---
+--- ```lua
 --- vim.iter(ipairs(t))
---- </pre>
+--- ```
 ---
 --- over
---- <pre>lua
+---
+--- ```lua
 --- vim.iter(t):enumerate()
---- </pre>
+--- ```
 ---
 --- as the former is faster.
 ---
 --- Example:
---- <pre>lua
+---
+--- ```lua
 ---
 --- local it = vim.iter(vim.gsplit('abc', '')):enumerate()
 --- it:next()
@@ -861,7 +881,7 @@ end
 --- it:next()
 --- -- 3	'c'
 ---
---- </pre>
+--- ```
 ---
 ---@return Iter
 function Iter.enumerate(self)
@@ -959,9 +979,10 @@ end
 --- Collect an iterator into a table.
 ---
 --- This is a convenience function that performs:
---- <pre>lua
+---
+--- ```lua
 --- vim.iter(f):totable()
---- </pre>
+--- ```
 ---
 ---@param f function Iterator function
 ---@return table
@@ -972,9 +993,10 @@ end
 --- Filter a table or iterator.
 ---
 --- This is a convenience function that performs:
---- <pre>lua
+---
+--- ```lua
 --- vim.iter(src):filter(f):totable()
---- </pre>
+--- ```
 ---
 ---@see |Iter:filter()|
 ---
@@ -990,9 +1012,10 @@ end
 --- Map and filter a table or iterator.
 ---
 --- This is a convenience function that performs:
---- <pre>lua
+---
+--- ```lua
 --- vim.iter(src):map(f):totable()
---- </pre>
+--- ```
 ---
 ---@see |Iter:map()|
 ---
diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py
index dfad1f000c..d485e68e2f 100755
--- a/scripts/gen_vimdoc.py
+++ b/scripts/gen_vimdoc.py
@@ -440,7 +440,7 @@ def is_blank(text):
     return '' == clean_lines(text)
 
 
-def get_text(n, preformatted=False):
+def get_text(n):
     """Recursively concatenates all text in a node tree."""
     text = ''
     if n.nodeType == n.TEXT_NODE:
@@ -449,11 +449,13 @@ def get_text(n, preformatted=False):
         for node in n.childNodes:
             text += get_text(node)
         return '`{}`'.format(text)
+    if n.nodeName == 'sp': # space, used in "programlisting" nodes
+        return ' '
     for node in n.childNodes:
         if node.nodeType == node.TEXT_NODE:
             text += node.data
         elif node.nodeType == node.ELEMENT_NODE:
-            text += get_text(node, preformatted)
+            text += get_text(node)
     return text
 
 
@@ -571,7 +573,7 @@ def render_node(n, text, prefix='', indent='', width=text_width - indentation,
     # text += (int(not space_preceding) * ' ')
 
     if n.nodeName == 'preformatted':
-        o = get_text(n, preformatted=True)
+        o = get_text(n)
         ensure_nl = '' if o[-1] == '\n' else '\n'
         if o[0:4] == 'lua\n':
             text += '>lua{}{}\n<'.format(ensure_nl, o[3:-1])
@@ -581,7 +583,15 @@ def render_node(n, text, prefix='', indent='', width=text_width - indentation,
             text += o[4:-1]
         else:
             text += '>{}{}\n<'.format(ensure_nl, o)
+    elif n.nodeName == 'programlisting': # codeblock (```)
+        o = get_text(n)
+        filename = n.attributes['filename'].value
+        if filename:
+            text += '>{}'.format(filename.lstrip('.'))
+        else:
+            text += '>'
 
+        text += '\n\n{}\n<'.format(textwrap.indent(o, ' ' * 4))
     elif is_inline(n):
         text = doc_wrap(get_text(n), prefix=prefix, indent=indent, width=width)
     elif n.nodeName == 'verbatim':
@@ -786,6 +796,18 @@ def fmt_node_as_vimhelp(parent: Element, width=text_width - indentation, indent=
     for child in parent.childNodes:
         para, _ = para_as_map(child, indent, width, fmt_vimhelp)
 
+        # 'programlisting' blocks are Markdown code blocks. Do not include
+        # these as a separate paragraph, but append to the last non-empty line
+        # in the text
+        if (
+            len(child.childNodes) == 1
+            and child.childNodes[0].nodeName == 'programlisting'
+        ):
+            while rendered_blocks and rendered_blocks[-1] == '':
+                rendered_blocks.pop()
+            rendered_blocks[-1] += ' ' + para['text']
+            continue
+
         # Generate text from the gathered items.
         chunks = [para['text']]
         if len(para['note']) > 0: