fix: a README homepage's links to guide pages reach the built pages

README.md

@@ -76,6 +76,12 @@ up at `<base-path>/images`. When the homepage is rendered from `README.md`, its
 are rewritten to that copy. The README's images then show on the site and on
 GitHub alike, and a path into a directory that isn't listed stays as written.
 
+The same homepage's links to guide pages are rewritten too: `docs/guide/x.md`
+(or `./docs/guide/x.md`, with or without a `#fragment`) becomes
+`<base-path>/guide/x.html`, the page the build writes. A link to any other file
+in the repository stays as written and has no page on the site, so give it a
+full GitHub URL if the homepage should reach it.
+
 Markdown pages get GitHub's alerts too. A blockquote opening with `[!NOTE]`,
 `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]` or `[!CAUTION]` renders as a titled
 callout.

src/site/generic_home.clj

@@ -45,6 +45,18 @@
           html
           asset-names))
 
+(defn rewrite-readme-guide-links
+  "A README links to its guide pages as GitHub needs them, docs/guide/x.md
+   from the repository root. The site has each one at
+   <site-base>/guide/x.html, so on a homepage rendered from the README those
+   links were dead. Rewrites each href that starts with docs/guide/ or
+   ./docs/guide/ and names a .md file, in either quote style, keeping a
+   #fragment. A link to anything else under docs/ is left as it was."
+  [html site-base]
+  (str/replace html
+               #"href=([\"'])(?:\./)?docs/guide/([^\"'#]+)\.md(#[^\"']*)?\1"
+               (fn [[_ q path frag]] (str "href=" q site-base "/guide/" path ".html" frag q))))
+
 (defn rendered-source
   "What the homepage's source document rendered to, so a caller can both
    build the page and index it without rendering the markdown twice.
@@ -71,7 +83,8 @@
    guide/-prefixed. README-sourced content keeps whatever the default
    rewrite produced, since its links are relative to the repository root,
    except that links into a configured asset directory point at the copy the
-   build makes (rewrite-readme-asset-links).
+   build makes (rewrite-readme-asset-links) and links to guide pages at the
+   pages the build writes (rewrite-readme-guide-links).
 
    The three-arity form takes an already-computed rendered-source, for a
    caller that needs the same render for something else."
@@ -80,9 +93,10 @@
    (let [content (case source
                    nil          (str "<h1>" (:site-title site-ctx) "</h1><p>No documentation yet.</p>")
                    :guide-index (prefix-guide-links body-html)
-                   (rewrite-readme-asset-links body-html
-                                               (map fs/file-name (:asset-dirs project))
-                                               (:site-base site-ctx)))]
+                   (-> body-html
+                       (rewrite-readme-asset-links (map fs/file-name (:asset-dirs project))
+                                                   (:site-base site-ctx))
+                       (rewrite-readme-guide-links (:site-base site-ctx))))]
      (selmer/render-file "generic-home.html"
                          (merge site-ctx
                                 {:page    "home"

test/site/core_test.clj

@@ -185,6 +185,28 @@
   (let [{:keys [out]} (build-fixture-site! "/some-lib" {:assets? true})]
     (is (fs/exists? (io/file out "media" "x.gif")))))
 
+(deftest a-readme-homepage-points-guide-links-at-the-built-pages
+  ;; A README links to docs/guide/x.md, which is right on GitHub. The site
+  ;; has that page at <site-base>/guide/x.html, so the homepage rendered
+  ;; from the README needs the site's path or every such link is a 404.
+  (let [{:keys [home]}
+        (build-fixture-site! "/some-lib"
+                             {:readme? true
+                              :readme-text (str "# R\n\n[a](docs/guide/usage.md) [b](./docs/guide/usage.md#run) "
+                                                "[c](docs/guide/deep/page.md) [d](bench/README.md) "
+                                                "[e](https://example.com/docs/guide/x.md) "
+                                                "<a href=\"docs/guide/usage.md\">raw</a>\n")})]
+    (testing "plain, with ./ and a fragment, nested, and raw HTML"
+      (is (str/includes? home "href='/some-lib/guide/usage.html'"))
+      (is (str/includes? home "href='/some-lib/guide/usage.html#run'"))
+      (is (str/includes? home "href='/some-lib/guide/deep/page.html'"))
+      (is (str/includes? home "href=\"/some-lib/guide/usage.html\"")))
+    (testing "what isn't a guide page is left as written"
+      (is (str/includes? home "bench/README.md"))
+      (is (str/includes? home "https://example.com/docs/guide/x.md")))
+    (testing "no guide link is left pointing at the markdown"
+      (is (nil? (re-find #"href=[\"']\.?/?docs/guide/" home))))))
+
 (deftest a-readme-homepage-points-asset-links-at-the-copied-directory
   ;; A README's paths are right on GitHub (docs/media/x.gif from the repo
   ;; root), but the build copies docs/media to <site-base>/media, so the