From 75bdec14ee4bd7d2db752410cf1f10a29196a027 Mon Sep 17 00:00:00 2001
From: Sebastiaan van Stijn <github@gone.nl>
Date: Sun, 19 Apr 2020 20:44:14 +0200
Subject: [PATCH] _layouts/docs.html: remove baseURL and fix link-fixing script

The base href caused browsers to produce incorrect URLs for
anchor links on various pages, for example, pointing to:

    https://docs-test.docker.com/engine/reference/#foreground

Instead of

    https://docs-test.docker.com/engine/reference/run/#foreground

Also cleaning up and fixing the JavaScript workaround for links
in include-files;

- only fix up links in the main content, not in other parts
  of the page
- don't fix up anchor links, absolute links, or links that don't
  contain `.md`: for those we can assume they were generated
  correctly, and if not, those are links that should be fixed in
  the markdown source, not fixed afterwards.
- document the function for future readers.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
---
 _layouts/docs.html | 71 +++++++++++++++++++++++++++++++++-------------
 1 file changed, 52 insertions(+), 19 deletions(-)

diff --git a/_layouts/docs.html b/_layouts/docs.html
index 526e148ea0..66bb2b2d14 100755
--- a/_layouts/docs.html
+++ b/_layouts/docs.html
@@ -161,26 +161,59 @@
                                 </span>
                                 {% endif -%}
                             {% endunless %}
-                            <!-- link corrections -->
                             <script>
-                            var x = document.links.length;
-                            var baseHref = document.getElementsByTagName('base')[0].href
-                            for (i = 0; i < x; i++) {
-                              var munged = false;
-                              var thisHREF = document.links[i].href;
-                              var originalURL = "{{ page.url }}";
-                              if (thisHREF.indexOf(baseHref + "#") > -1) {
-                                // hash fix
-                                //console.log('BEFORE: base:',baseHref,'thisHREF:',thisHREF,'originalURL:',originalURL);
-                                thisHREF = originalURL + thisHREF.replace(baseHref, "");
-                                //console.log('AFTER: base:',baseHref,'thisHREF:',thisHREF,'originalURL:',originalURL);
-                              }
-                              if ((thisHREF.indexOf(window.location.hostname) > -1 || thisHREF.indexOf('http') == -1) && document.links[i].className.indexOf("nomunge") < 0) {
-                                munged = true;
-                                thisHREF = thisHREF.replace(".md", "/").replace("/index/", "/");
-                                document.links[i].setAttribute('href', thisHREF);
-                              }
-                            }
+                                // This is a horrible hack, and cute little kittens are sacrificed every time it's run, so we
+                                // need to remove it as soon as possible.
+                                //
+                                // Fix up links to markdown pages that weren't resolved by Jekyll (or the "jekyll-relative-links"
+                                // plugin). This is a horrible hack, and should not rely on JavaScript (perhaps be re-implemented
+                                // using Liquid). We need this hack to work around two bugs in the "jekyll-relative-links" plugin;
+                                // 1. As reported in https://github.com/benbalter/jekyll-relative-links/issues/54, (relative) links
+                                //    to markdown pages in includes are not processed by Jekyll. This means that (for example) our
+                                //    reference pages (which use includes) contain broken links. We can work around this by modifying
+                                //    the markdown for those pages to use "absolute" "html" links (/link/to/other/page/#some-anchor),
+                                //    but doing so would render the links broken when viewed on GitHub. Instead, we're fixing them up
+                                //    here, hoping the bug will be fixed, and it's only temporarily.
+                                // 2. As reported in https://github.com/benbalter/jekyll-relative-links/issues/61, (relative) links
+                                //    to markdown pages are not resolved if the link's caption/title is wrapped.
+                                //
+                                Array.prototype.forEach.call(document.querySelectorAll("section.section a:not(.nomunge)"), function (el) {
+                                    let href = el.getAttribute("href");
+                                    if (href.startsWith("/") || href.startsWith("#") || href.includes("://") || !href.includes('.md')) {
+                                        // Don't modify anchor links, absolute links, links to external websites,
+                                        // or links not pointing to a .md file; we assume those were
+                                        // resolved successfully by Jekyll.
+                                        return
+                                    }
+                                    if (href.startsWith("./")) {
+                                        href = href.substr(2)
+                                    }
+                                    if ("{{ page.name }}" !== "index.md") {
+                                        // For non-index pages, things are a bit hairy. For example, for /foo/bar/mypage.md, Jekyll
+                                        // will generate a page named /foo/bar/mypage/index.html. This means that all links relative
+                                        // to mypage.md expect those links to be relative to the /foo/bar/ directory, but end up
+                                        // being relative to /foo/bar/mypage/.
+                                        //
+                                        // For files "next to", or "below" this file, such as "file.md" or "nested/dir/file.md" we
+                                        // prepend the "parent-dir" to the URL.
+                                        //
+                                        // For links to files "up" the directory tree, we prepend
+                                        // "../" to the URL and have the browser handle this. For example, "../file.md" and "../../file.md"
+                                        // become "../../file.md" and "../../../file.md".
+                                        if (href.startsWith("../")) {
+                                            href = "../" + href
+                                        } else {
+                                            // Generate "parentPath" with Liquid, which is used below. Liquid's page.path (and page.dir)
+                                            // are relative to the _generated_ HTML page, not the source page, so we have to remove the
+                                            // last part of the path:
+                                            // {% raw %}{% assign parentPath = page.path | prepend: "/" | remove: page.name %}{% endraw %}
+                                            // {% assign parentPath = page.path | prepend: "/" | remove: page.name %}
+                                            href = "{{ parentPath}}" + href
+                                        }
+                                    }
+                                    // finally, we replace the .md extension for a slash, and update the link's href
+                                    el.setAttribute("href", href.replace(".md", "/"))
+                                });
                             </script>
                             {% if page.noratings != true %}
                             <div id="ratings-div" style="color:#b9c2cc; text-align: center; margin-top: 150px; visibility: hidden">