Improve documentation generation.

Details:
- Don't enclose tag link as inline code, as it stands out a bit too much
  (because there are *a lot* of links in help pages). Instead improve
  `<xxx>` escape code to ignore only actual part of markdown link.
  Affecting links (https://neovim.io/doc/user/helptag.html?tag=<Leader>)
  was the initial problem of why inline code "escape" was added in the
  first place.

- Make "Generated ..." note centered and below centered images in the
  READMEs.

- Make first section in documentation pages have "module" anchor.
  Otherwise it was `minixxx` which is redundant as there is already
  `mini.xxx` anchor earlier.

- Create a single 'mini.nvim/_metadata.yml' to populate common metadata
  for all pages (instead of adding to every page via script).

  This also contains a dedicated CSS that hides Quarto titles (which are
  often redundant). NOTE: do so only in 'mini.nvim' pages and not ont he
  whole site because showing titles of blog posts is useful.

Author: echasnovski

_scripts/mini_nvim.lua

@@ -19,6 +19,18 @@ local make_anchor = function(x)
   return (x:lower():gsub('[^%w%.%-_]', ''):gsub('%s', '-'):gsub('<(.-)>', '\\<%1\\>'))
 end
 
+-- Metadata ===================================================================
+local metadata_lines = {
+  -- Hide displaying the title as it is redundant and out of place
+  'format:',
+  '  html:',
+  '    include-in-header:',
+  '      - text: "<style> .quarto-title > h1.title { display: none } </style>"',
+  -- Show more nested headers (useful for documentation pages)
+  'toc-depth: 5',
+}
+vim.fn.writefile(metadata_lines, 'mini.nvim/_metadata.yml')
+
 -- Help files =================================================================
 local get_help_tags = function()
   local tags_path = '_deps/mini.nvim/doc/tags'
@@ -115,36 +127,39 @@ local add_help_syntax = function(lines, tags)
 
   local populate_bad_ranges = function(s)
     bad_ranges = {}
+    -- Inline code
     s:gsub('`().-()`', function(from, to) table.insert(bad_ranges, { from, to }) end)
-    s:gsub('()%b[]%b()()', function(from, to) table.insert(bad_ranges, { from, to }) end)
+    -- Actual link (but not visible part!) of markdown link
+    s:gsub('%b[]()%b()()', function(from, to) table.insert(bad_ranges, { from, to }) end)
   end
 
   local repl_link = function(m)
     -- Escpe special characters to be usable inside markdown link
     if tags[m] == nil then
       local text_escaped = m:gsub('[)(]', '\\%1')
-      return string.format('[`%s`](https://neovim.io/doc/user/helptag.html?tag=%s)', m, text_escaped)
+      return string.format('[%s](https://neovim.io/doc/user/helptag.html?tag=%s)', m, text_escaped)
     end
 
-    return string.format('[`%s`](%s.qmd#%s)', m, tags[m], make_anchor(m))
+    return string.format('[%s](%s.qmd#%s)', m, tags[m], make_anchor(m))
   end
 
   local repl_right_anchor = function(m)
     -- Transform right anchor into a heading (for table of contents entry).
     -- Compute more natural title. Common tag->title transformations:
     -- - `*MiniAi*` -> "Module" ("Overview" is commonly used later as
-    --   a 'MiniXxx-overview' tag).
+    --   a 'MiniXxx-overview' tag). Both as title and anchor.
     -- - `*MiniAi.find_textobject()*` -> "find_textobject()"
     -- - `*MiniAi-builtin-textobjects*` -> "Builtin textobjects"
     -- - `*mini.nvim-disabling-recipes*` -> "Disabling recipes"
     -- - `:DepsAdd` -> ":DepsAdd"
-    local text = m:find('^Mini%w+$') ~= nil and 'Module'
-      or (m:match('^Mini%w+(%W.+)$') or m:match('^mini%.%w+(%W.+)$') or m)
+    m = m:find('^Mini%w+$') ~= nil and 'Module' or m
+    local text = m:match('^Mini%w+(%W.+)$') or m:match('^mini%.%w+(%W.+)$') or m
     local char_one, char_two = text:sub(1, 1), text:sub(2, 2)
     local title = char_one == '.' and text:sub(2)
       or (char_one == '-' and (char_two:upper() .. text:sub(3):gsub('%-', ' ')) or text)
 
-    -- Preserve original tag as anchor for other links to work more naturally
+    -- Preserve original tag as anchor for other converted links (coming from
+    -- the help files) to work more naturally
     return string.format('### %s {#%s}\n', title, make_anchor(m))
   end
 
@@ -257,17 +272,23 @@ local add_hierarchical_heading_anchors = function(lines)
 end
 
 local add_source_note = function(lines)
-  table.insert(lines, 1, "_Generated from the `main` branch of 'mini.nvim'_")
-  table.insert(lines, 2, '')
+  local msg = "_Generated from the `main` branch of 'mini.nvim'_"
+  if lines[1]:find('align="center"') ~= nil then
+    -- Center align if after center aligned element (i.e. top README image)
+    table.insert(lines, 2, '<p align="center">' .. msg .. '</p>')
+    table.insert(lines, 3, '')
+  else
+    table.insert(lines, 1, msg)
+    table.insert(lines, 2, '')
+  end
 end
 
 local adjust_header_footer = function(lines, title)
   -- Add informative header for better search
   table.insert(lines, 1, '---')
   table.insert(lines, 2, string.format('title: "%s"', title))
-  table.insert(lines, 3, 'toc-depth: 5')
-  table.insert(lines, 4, '---')
-  table.insert(lines, 5, '')
+  table.insert(lines, 3, '---')
+  table.insert(lines, 4, '')
 
   -- Remove modeline
   if lines[#lines]:find('^ vim:') then
@@ -360,8 +381,9 @@ local adjust_readmes = function()
   -- Main README
   local path = vim.fs.joinpath('mini.nvim/index.md')
   local lines = vim.fn.readfile(path)
-  adjust_header_footer(lines, 'mini.nvim')
   replace_help_links(lines)
+  add_source_note(lines)
+  adjust_header_footer(lines, 'mini.nvim')
   vim.fn.writefile(lines, path)
 end
 

mini.nvim/_metadata.yml

@@ -0,0 +1,5 @@
+format:
+  html:
+    include-in-header:
+      - text: "<style> .quarto-title > h1.title { display: none } </style>"
+toc-depth: 5