update-docs: make anchors backwards-compatible again

Command options in Git's documentation are now being wrapped in HTML
tags like `<code>` for prettier formatting. Unfortunately, these tags
were being included in the generated anchor IDs, breaking links that
used to work. For example, an anchor for the
`--recurse-submodules[=<pathspec>]` option of the `clone` command would
now include 'code' in the anchor, causing existing deep links across the
web to fail to navigate to said option.

The documentation generation has been using these anchors for years and
many links using the old format (without HTML tags) are widely shared.
These links should continue to work, even as the document formatting
evolves to include more HTML.

This change modifies the anchor ID generation to strip HTML tags before
creating IDs, ensuring backward compatibility with existing references
while also supporting the new HTML-enhanced documentation format. Both
regular and localized documentation processing now handle HTML tags in
command options correctly.

These anchor IDs still include the `lt` and `gt` left-overs from the
pointy brackets that are encoded as `&lt;`/`&gt;` in HTML. This is
intentional because the existing deep links all over the web do include
those.

Technically, this here patch is not needed to fix the regression because
the preceding commit introduced code that is running on the client side
and automagically adjusts incorrect anchors in URLs when practical.

Having said that, the resulting anchors look a lot nicer, so let's do
this anyway, even if it is not strictly needed to address
git#2002.

Reported-by: Toon Claes <[email protected]>
Helped-by: Jean-Noël Avila <[email protected]>
Co-authored-by: Johannes Schindelin <[email protected]>
Signed-off-by: Johannes Schindelin <[email protected]>

Author: Copilot

script/update-docs.rb

@@ -1,6 +1,7 @@
 #!/usr/bin/env ruby
 
 require "asciidoctor"
+require "nokogiri"
 require "octokit"
 require "time"
 require "digest/sha1"
@@ -182,7 +183,15 @@ def index_l10n_doc(filter_tags, doc_list, get_content)
         anchor += "-1" while ids.include?(anchor)
         ids.add(anchor)
 
-        "<dt class=\"hdlist1\" id=\"#{anchor}\"> <a class=\"anchor\" href=\"##{anchor}\"></a>#{$1} </dt>"
+        clean_text = Nokogiri::HTML.parse($1).text.tr("^A-Za-z0-9-", "")
+        if clean_text != text
+          clean_anchor = "#{txt_path}-#{clean_text}"
+          clean_anchor += "-1" while ids.include?(clean_anchor)
+          ids.add(clean_anchor)
+          clean_anchor = "<a class=\"anchor\" href=\"##{clean_anchor}\"></a> "
+        end
+
+        "<dt class=\"hdlist1\" id=\"#{anchor}\"> #{clean_anchor}<a class=\"anchor\" href=\"##{anchor}\"></a>#{$1} </dt>"
       end
       # Make links relative
       html.gsub!(/(<a href=['"])\/([^'"]*)/) do |match|
@@ -472,7 +481,16 @@ def index_doc(filter_tags, doc_list, get_content)
           # handle anchor collisions by appending -1
           anchor += "-1" while ids.include?(anchor)
           ids.add(anchor)
-          "<dt class=\"hdlist1\" id=\"#{anchor}\"> <a class=\"anchor\" href=\"##{anchor}\"></a>#{$1} </dt>"
+
+          clean_text = Nokogiri::HTML.parse($1).text.tr("^A-Za-z0-9-", "")
+          if clean_text != text
+            clean_anchor = "#{txt_path}-#{clean_text}"
+            clean_anchor += "-1" while ids.include?(clean_anchor)
+            ids.add(clean_anchor)
+            clean_anchor = "<a class=\"anchor\" href=\"##{clean_anchor}\"></a> "
+          end
+
+          "<dt class=\"hdlist1\" id=\"#{anchor}\"> #{clean_anchor}<a class=\"anchor\" href=\"##{anchor}\"></a>#{$1} </dt>"
         end
         # Make links relative
         html.gsub!(/(<a href=['"])\/([^'"]*)/) do |relurl|

tests/git-scm.spec.js

@@ -193,6 +193,16 @@ test('manual pages', async ({ page }) => {
   await expect(synopsis).not.toHaveText(/git remote renom.*<ancien> <nouveau>/)
 })
 
+test('anchor links in manual pages', async ({ page }) => {
+  // Test that anchor links work without HTML tags
+  const anchor = '#Documentation/git-clone.txt---recurse-submodulesltpathspecgt'
+  await page.goto(`${url}docs/git-clone${anchor}`)
+
+  // Find the anchored element that should be scrolled into view
+  const anchoredElement = await page.getByText(/^--recurse-submodules.*pathspec/)
+  await expect(anchoredElement).toBeVisible()
+})
+
 test('book', async ({ page }) => {
   await page.goto(`${url}book/`)
   await expect(page).toHaveURL(`${url}book/en/v2`)