docs: Fix relative link generation in mdbook post-processor

[aac6fef]

Closes: #35310

This PR fixes a persistent issue with broken navigation links in the mdbook-generated documentation. The problem occurred when navigating between pages in different subdirectories, causing incorrect URL resolution.

This is a known issue of mdbook. However, after #35112, we now have the ability to post-process the generated html files and fix the links to be absolute ourselves

1. Calculates the directory depth of each HTML page being processed.
2. Creates a relative prefix (../ for each level of depth).
3. Prepends this prefix to all relative href links within the page, ensuring they resolve correctly from any location.

Using the following lychee command to check links in the generated html files (we currently only check the .md file links in CI with lychee) with the following command, the number of errors is reduced from 12854 to 74 by this PR.

lychee docs/book --exclude '^https' --no-progress

Release Notes:

• N/A

[probably-neb]

Thanks! Well done connecting my addition of post-processing to the inter-subdirectory link issue. I've updated what I assume were AI hallucinations in your PR description to link to the actual issue and document how many link errors this PR resolves.

If you would please fix the clippy issue (compiling regex in a loop) and add a bit of documentation to docs/README.md explaining the link logic and linking to the upstream mdbook issue I added to the PR description (basically copy the PR description) so that we can track it and remove the link fixing once that mdbook issue is resolved.

Additionally, it seems that the relative link modifications are a bit too eager, if you run the lychee command I put in the PR description, you'll see that most of the errors are now relative links (like the ./css.md link in languages/html.md) that used to work properly but are now broken with this change. While we could make these links absolute, I'd much prefer if we updated the link fixing logic to do something more intelligent to handle such cases

[probably-neb]

Another thought I just had, is that it may be worth copying the lychee check in .github/actions/build_docs/action.yml below the build and update it to work with the generated html, so it would look like:

    - name: Check for broken links (in MD)
      uses: lycheeverse/lychee-action@82202e5e9c2f4ef1a55a3d02563e1cb6041e5332 # v2.4.1
      with:
        args: --no-progress --exclude '^http' './docs/src/**/*'
        fail: true

    - name: Build book
      shell: bash -euxo pipefail {0}
      run: |
        mkdir -p target/deploy
        mdbook build ./docs --dest-dir=../target/deploy/docs/
        
    - name: Check for broken links (in HTML)
      uses: lycheeverse/lychee-action@82202e5e9c2f4ef1a55a3d02563e1cb6041e5332 # v2.4.1
      with:
        args: --no-progress --exclude '^http' '../target/deploy/docs/'
        fail: true

Then the remaining work for this PR would be making CI pass by fixing all the links! Leaving this as an option for you as it will likely be a bit more work and I didn't look at all of the 74 errors that closely so I'm not sure if there are some that aren't just broken relative links. Let me know if you're interested in doing it though, and I'm happy to help as needed

[probably-neb]

Hey, closing this as we found out the broken links were caused by a bug in a new version of mdbook. We're rolling back to v0.4.40 which fixes the issue: #35380