20e9f21 | website

git clone https://git.pyrossh.dev/website

木 Personal website of pyrossh. Built with astrojs, shiki, vite.

20e9f21 — pyrossh 2026-11-06T15:29:20+05:30

Fix markdown links and render docs on file pages

Files changed (9) hide show

assets/css/markdown.css +7 -0
assets/css/repos.css +8 -0
src/_data/localRepos.js +8 -4
src/_data/repoFiles.js +16 -5
src/_helpers/gitRepos.js +24 -0
src/_helpers/repoMarkdown.js +87 -0
src/_includes/file-layout.njk +2 -0
tests/pages.test.js +14 -0
tests/repoMarkdown.test.js +142 -0

assets/css/markdown.css CHANGED Viewed

@@ -39,6 +39,13 @@
     padding-bottom: 1rem;
   }
+  /* shared.css resets links to inherit their color with no underline, which
+     leaves links in prose indistinguishable from the text around them. */
+  a[href] {
+    color: var(--color-link);
+    text-decoration: underline;
+  }
   /* shared.css resets ul/ol to list-style: none globally (for nav-style
      lists elsewhere in the site), so markdown content needs its bullets/
      numbering and indentation restored here, plus breathing room between

assets/css/repos.css CHANGED Viewed

@@ -375,6 +375,14 @@
           border-radius: 0;
         }
       }
+      /* Rendered markdown brings its own padding (see #repo-content
+         .markdown-body), so the pane only supplies the matching background
+         for documents shorter than the pane. */
+      &:has(> .markdown-body) {
+        padding: 0;
+        background: var(--color-box-bg);
+      }
     }
   }

src/_data/localRepos.js CHANGED Viewed

@@ -1,13 +1,17 @@
-import MarkdownIt from "markdown-it";
 import { discoverLocalRepos, resolveReadmeImages } from "../_helpers/gitRepos.js";
-import { highlightFenceCode } from "../_helpers/highlightCode.js";
+import { renderRepoMarkdown } from "../_helpers/repoMarkdown.js";
+const renderReadme = (repo) =>
+  resolveReadmeImages(
-const md = new MarkdownIt({ html: true, linkify: true, highlight: highlightFenceCode });
+    renderRepoMarkdown(repo.readme, { repoId: repo.id, files: repo.files, filePath: "README.md" }),
+    repo.id,
+    repo.dir,
+  );
 export default async () => {
   const repos = discoverLocalRepos();
   return repos.map((repo) => ({
     ...repo,
-    readmeHtml: repo.readme ? resolveReadmeImages(md.render(repo.readme), repo.id, repo.dir) : undefined,
+    readmeHtml: repo.readme ? renderReadme(repo) : undefined,
   }));
 };

src/_data/repoFiles.js CHANGED Viewed

@@ -7,20 +7,28 @@ import {
   LARGE_FILE_SIZE,
   discoverLocalRepos,
   getHeadSha,
+  inlineMarkdownImages,
   isDirty,
   toDataUri,
 } from "../_helpers/gitRepos.js";
 import { highlightCode } from "../_helpers/highlightCode.js";
 import { mapPool } from "../_helpers/pool.js";
+import { renderRepoMarkdown } from "../_helpers/repoMarkdown.js";
 const CONCURRENCY = 8;
+const MARKDOWN_EXTENSIONS = new Set(["md", "markdown"]);
-const renderFile = (repoDir, file) => {
+const renderFile = (repo, file) => {
-  const full = path.join(repoDir, file.path);
+  const full = path.join(repo.dir, file.path);
   if (BINARY_EXTENSIONS.has(file.ext)) return { kind: "binary" };
   if (file.size > LARGE_FILE_SIZE) return { kind: "large" };
   if (IMAGE_EXTENSIONS.has(file.ext)) return { kind: "image", src: toDataUri(fs.readFileSync(full), file.ext) };
+  const source = fs.readFileSync(full, "utf8");
+  if (MARKDOWN_EXTENSIONS.has(file.ext)) {
+    const html = renderRepoMarkdown(source, { repoId: repo.id, files: repo.files, filePath: file.path });
+    return { kind: "markdown", html: inlineMarkdownImages(html, repo.dir, file.path) };
+  }
-  const { html, lang } = highlightCode(fs.readFileSync(full, "utf8"), file.ext);
+  const { html, lang } = highlightCode(source, file.ext);
   return { kind: "text", html, lang };
 };
@@ -30,13 +38,16 @@ export default async () => {
   for (const repo of repos) {
     const sha = getHeadSha(repo.dir);
     const cacheable = sha && !isDirty(repo.dir);
+    // The version is part of the key because the cache is otherwise keyed by
+    // HEAD: bump it when renderFile's output changes, or unchanged repos keep
+    // serving the old render.
-    const cacheKey = `files-${repo.id}`;
+    const cacheKey = `files-v2-${repo.id}`;
     let entries = cacheable ? readCache(cacheKey, sha) : null;
     if (!entries) {
       entries = await mapPool(repo.files, CONCURRENCY, async (file) => ({
         file,
-        render: renderFile(repo.dir, file),
+        render: renderFile(repo, file),
       }));
       if (cacheable) writeCache(cacheKey, sha, entries);
     }

src/_helpers/gitRepos.js CHANGED Viewed

@@ -220,6 +220,16 @@ export const toDataUri = (buf, ext) => {
   return `data:${mime};base64,${buf.toString("base64")}`;
 };
+// Percent-decodes a path from a markdown link or image. Malformed escapes are
+// kept as written, since hand-written markdown can contain a bare `%`.
+export const decodePath = (encoded) => {
+  try {
+    return decodeURIComponent(encoded);
+  } catch {
+    return encoded;
+  }
+};
 const isAbsoluteSrc = (src) => /^([a-z][a-z0-9+.-]*:)?\/\//i.test(src) || src.startsWith("data:");
 const IMG_SRC_PATTERNS = [
@@ -260,6 +270,20 @@ export const resolveReadmeImages = (html, repoId, repoDir) =>
     return `${pre}/repos/${repoId}/raw/${path.posix.normalize(src)}${post}`;
   });
+// Markdown shown on a file page. Only README images get a raw/ copy, so these
+// are inlined the same way image files' own pages are, with paths relative to
+// the markdown file rather than the repo root.
+export const inlineMarkdownImages = (html, repoDir, filePath) =>
+  html.replace(/(<img\b[^>]*?(?<![\w-])src\s*=\s*)(["'])(.*?)\2/gi, (match, pre, quote, src) => {
+    if (!src || isAbsoluteSrc(src)) return match;
+    const relPath = path.posix.join(path.posix.dirname(filePath), decodePath(src.split(/[?#]/)[0]));
+    if (!isLocalRepoImage(repoDir, relPath)) return match;
+    const full = path.join(repoDir, relPath);
+    if (fs.statSync(full).size > LARGE_FILE_SIZE) return match;
+    const ext = path.extname(relPath).slice(1).toLowerCase();
+    return `${pre}${quote}${toDataUri(fs.readFileSync(full), ext)}${quote}`;
+  });
 const readCargoVersion = (repoDir) => {
   const p = path.join(repoDir, "Cargo.toml");
   if (!fs.existsSync(p)) return undefined;

src/_helpers/repoMarkdown.js ADDED Viewed

@@ -0,0 +1,87 @@
+import path from "node:path";
+import MarkdownIt from "markdown-it";
+import { decodePath } from "./gitRepos.js";
+import { highlightFenceCode } from "./highlightCode.js";
+const md = new MarkdownIt({ html: true, linkify: true, highlight: highlightFenceCode });
+// Same ids GitHub generates, since that's what `#section` links in these repos
+// were written against. A repeated heading gets -1, -2, ... appended.
+const headingSlug = (text) =>
+  text
+    .trim()
+    .toLowerCase()
+    .replace(/[^\p{L}\p{M}\p{N}\s_-]/gu, "")
+    .replace(/\s/g, "-");
+md.renderer.rules.heading_open = (tokens, idx, options, env, self) => {
+  const text = tokens[idx + 1].children
+    .filter((t) => t.type === "text" || t.type === "code_inline")
+    .map((t) => t.content)
+    .join("");
+  const slug = headingSlug(text);
+  // An image-only heading has no text to link to, so it gets no id.
+  if (slug) {
+    let id = slug;
+    for (let n = 1; env.headingIds.has(id); n++) id = `${slug}-${n}`;
+    env.headingIds.add(id);
+    tokens[idx].attrSet("id", id);
+  }
+  return self.renderToken(tokens, idx, options);
+};
+// The first line must look like a YAML key, so a document that merely opens
+// with a `---` rule keeps its content.
+const FRONT_MATTER = /^---\r?\n[\w-]+:[\s\S]*?\r?\n---\r?\n/;
+const encodePath = (filePath) => filePath.split("/").map(encodeURIComponent).join("/");
+// Folders have no page of their own, so a link to one opens its README or else
+// its first file, which also expands that folder in the file tree.
+const findLinkTarget = (files, target) => {
+  if (files.some((f) => f.path === target)) return target;
+  const inFolder = files.filter((f) => f.path.startsWith(`${target}/`));
+  const readme = inFolder.find((f) => f.path.toLowerCase() === `${target}/readme.md`.toLowerCase());
+  return (readme ?? inFolder[0])?.path;
+};
+// Repo markdown links relative to its own file, as GitHub resolves them. Here
+// that file's content lives at /repos/<id>/files/<path>/, so those links need
+// rewriting, and a leading `/` means the repo root. Targets not in the repo are
+// left as written. `href` is still HTML-escaped, so `&` is `&amp;` here.
+const resolveLink = (href, repoId, files, filePath) => {
+  if (/^(#|\/\/|[a-z][a-z0-9+.-]*:)/i.test(href)) return href;
+  const [, linkPath, suffix] = href.match(/^([^?#]*)(.*)$/s);
+  if (!linkPath) return href;
+  const decoded = decodePath(linkPath.replaceAll("&amp;", "&"));
+  const base = decoded.startsWith("/") ? "." : path.posix.dirname(filePath);
+  const target = path.posix.join(base, decoded).replace(/\/$/, "");
+  if (target === ".") return `/repos/${repoId}/files/${suffix}`;
+  const file = findLinkTarget(files, target);
+  if (file) return `/repos/${repoId}/files/${encodePath(file)}/${suffix}`;
+  // Scheme-less external links, e.g. [Teensy](www.pjrc.com/store/teensy3.html)
+  return /^www\./i.test(href) ? `https://${href}` : href;
+};
+/**
+ * Render a markdown file from a repo, pointing its relative links at this
+ * site's file pages. Runs over the final HTML rather than a markdown-it link
+ * rule so raw <a> tags in the markdown are covered too; code blocks can't match
+ * because their `<` is already escaped.
+ *
+ * @param {string} source markdown text
+ * @param {{ repoId: string, files: { path: string }[], filePath: string }} context
+ *   filePath is the markdown file's path within the repo
+ * @returns {string} HTML
+ */
+export const renderRepoMarkdown = (source, { repoId, files, filePath }) =>
+  md
+    .render(source.replace(FRONT_MATTER, ""), { headingIds: new Set() })
+    .replace(
+      /(<a\b[^>]*?(?<![\w-])href\s*=\s*)(["'])(.*?)\2/gi,
+      (_, pre, quote, href) => `${pre}${quote}${resolveLink(href, repoId, files, filePath)}${quote}`,
+    );

src/_includes/file-layout.njk CHANGED Viewed

@@ -12,6 +12,8 @@
     <p>File too large to display ({{ size }} bytes).</p>
   {% elif render.kind == "image" %}
     <img src="{{ render.src }}" alt="{{ filepath }}" />
+  {% elif render.kind == "markdown" %}
+    <article class="markdown-body">{{ render.html | safe }}</article>
   {% else %}
     <pre class="code-view" data-lang="{{ render.lang }}"><code class="language-{{ render.lang }}">{{ render.html | safe }}</code></pre>
   {% endif %}

tests/pages.test.js CHANGED Viewed

@@ -237,6 +237,20 @@ describe("repo pages", () => {
     }
   });
+  test("markdown files render as documents with visible links", async () => {
+    await goto(`/repos/${repoId}/files/README.md/`);
+    await page.locator("#file-content > .markdown-body").waitFor();
+    assert.equal(await page.locator("#file-content pre.code-view").count(), 0);
+    const link = page.locator("#file-content .markdown-body a[href]").first();
+    const style = await link.evaluate((el) => {
+      const { color, textDecorationLine } = getComputedStyle(el);
+      return { color, textDecorationLine, parentColor: getComputedStyle(el.parentElement).color };
+    });
+    assert.equal(style.textDecorationLine, "underline");
+    assert.notEqual(style.color, style.parentColor);
+  });
   test("repo files index renders the tree and a default file", async () => {
     const response = await goto(`/repos/${repoId}/files/`);
     assert.equal(response.status(), 200);

tests/repoMarkdown.test.js ADDED Viewed

@@ -0,0 +1,142 @@
+import { after, describe, test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { LARGE_FILE_SIZE, inlineMarkdownImages } from "../src/_helpers/gitRepos.js";
+import { renderRepoMarkdown } from "../src/_helpers/repoMarkdown.js";
+const files = ["README.md", "docs/language.md", "docs/std.md", "examples/arrays.plum", "examples/basics.plum", "guide/intro.md", "guide/README.md", "my docs/a b.md", "c#/q&a.md", "www.site/index.md"].map((p) => ({ path: p }));
+const render = (source, filePath = "README.md") => renderRepoMarkdown(source, { repoId: "plum", files, filePath });
+const href = (source, filePath) => render(source, filePath).match(/href="([^"]*)"/)[1];
+describe("renderRepoMarkdown links", () => {
+  test("relative file links point at the repo's file pages", () => {
+    assert.equal(href("[x](docs/language.md)"), "/repos/plum/files/docs/language.md/");
+    assert.equal(href("[x](./docs/language.md)"), "/repos/plum/files/docs/language.md/");
+  });
+  test("links resolve against the markdown file's own folder", () => {
+    assert.equal(href("[x](std.md)", "docs/language.md"), "/repos/plum/files/docs/std.md/");
+    assert.equal(href("[x](../README.md)", "docs/language.md"), "/repos/plum/files/README.md/");
+  });
+  test("a section in another file keeps its fragment", () => {
+    assert.equal(href("[x](docs/std.md#strings)"), "/repos/plum/files/docs/std.md/#strings");
+  });
+  test("folder links open the folder's README, else its first file", () => {
+    assert.equal(href("[x](guide/)"), "/repos/plum/files/guide/README.md/");
+    assert.equal(href("[x](../examples)", "docs/language.md"), "/repos/plum/files/examples/arrays.plum/");
+  });
+  test("a link to the repo root opens the Code tab", () => {
+    assert.equal(href("[x](..)", "docs/language.md"), "/repos/plum/files/");
+  });
+  test("paths with spaces stay encoded", () => {
+    assert.equal(href("[x](my%20docs/a%20b.md)"), "/repos/plum/files/my%20docs/a%20b.md/");
+  });
+  test("filenames with URL-special characters are encoded per segment", () => {
+    assert.equal(href("[x](c%23/q&a.md)"), "/repos/plum/files/c%23/q%26a.md/");
+  });
+  test("a leading slash means the repo root", () => {
+    assert.equal(href("[x](/docs/std.md)", "guide/intro.md"), "/repos/plum/files/docs/std.md/");
+  });
+  test("raw HTML links are resolved too, with either quote style", () => {
+    assert.equal(href('<a href="docs/std.md">x</a>'), "/repos/plum/files/docs/std.md/");
+    assert.match(render("<a href='docs/std.md'>x</a>"), /href='\/repos\/plum\/files\/docs\/std\.md\/'/);
+  });
+  test("data-href isn't treated as the link", () => {
+    assert.match(render('<a data-href="docs/std.md">x</a>'), /data-href="docs\/std\.md"/);
+  });
+  test("other links are left alone", () => {
+    for (const link of ["https://example.com/a.md", "mailto:[email protected]", "#section", "/posts/", "?x=1", "docs/missing.md", "../../outside.md"]) {
+      assert.equal(href(`[x](${link})`), link);
+    }
+  });
+  test("scheme-less www links become external, unless the repo has that path", () => {
+    assert.equal(href("[x](www.pjrc.com/store/teensy3.html)"), "https://www.pjrc.com/store/teensy3.html");
+    assert.equal(href("[x](www.site/index.md)"), "/repos/plum/files/www.site/index.md/");
+  });
+  test("links shown in code blocks are not rewritten", () => {
+    assert.match(render('```html\n<a href="docs/std.md">x</a>\n```'), /docs\/std\.md/);
+    assert.doesNotMatch(render('```html\n<a href="docs/std.md">x</a>\n```'), /\/repos\/plum/);
+  });
+});
+describe("renderRepoMarkdown headings", () => {
+  test("headings get ids that match section links", () => {
+    assert.match(render("## Pattern matching"), /<h2 id="pattern-matching">/);
+    assert.match(render("## The `plum` CLI: tools!"), /<h2 id="the-plum-cli-tools">/);
+  });
+  test("repeated headings get distinct ids, in each render", () => {
+    const html = render("## Usage\n\n## Usage");
+    assert.match(html, /id="usage"/);
+    assert.match(html, /id="usage-1"/);
+    assert.match(render("## Usage"), /id="usage"/);
+    assert.doesNotMatch(render("## Usage"), /usage-1/);
+  });
+  test("a heading that collides with a generated id still gets a unique one", () => {
+    const ids = [...render("## Usage\n\n## Usage\n\n## Usage-1").matchAll(/id="([^"]+)"/g)].map((m) => m[1]);
+    assert.equal(new Set(ids).size, 3);
+  });
+  test("image-only headings get no id", () => {
+    assert.match(render("## ![logo](logo.png)"), /<h2>/);
+  });
+  test("combining marks are kept", () => {
+    assert.match(render("## हिन्दी"), /id="हिन्दी"/);
+  });
+});
+describe("renderRepoMarkdown front matter", () => {
+  test("isn't rendered as content", () => {
+    const html = render("---\ntitle: Hello\n---\n\n# Body");
+    assert.doesNotMatch(html, /title: Hello/);
+    assert.match(html, /<h1 id="body">/);
+  });
+  test("a document opening with a rule keeps its content", () => {
+    assert.match(render("---\n\nKeep me\n\n---\n\nAnd me"), /Keep me/);
+  });
+});
+describe("inlineMarkdownImages", () => {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "repo-markdown-"));
+  const repoDir = path.join(tempDir, "repo");
+  fs.mkdirSync(path.join(repoDir, "docs"), { recursive: true });
+  fs.writeFileSync(path.join(repoDir, "docs", "my img.png"), "png");
+  fs.writeFileSync(path.join(repoDir, "docs", "big.png"), Buffer.alloc(LARGE_FILE_SIZE + 1));
+  fs.writeFileSync(path.join(tempDir, "outside.png"), "png");
+  const inline = (html) => inlineMarkdownImages(html, repoDir, "docs/game.md");
+  after(() => fs.rmSync(tempDir, { recursive: true, force: true }));
+  test("inlines images relative to the markdown file, ignoring encoding and suffixes", () => {
+    assert.match(inline('<img src="my%20img.png?raw=true">'), /<img src="data:image\/png;base64,/);
+    assert.match(inline("<img src='my%20img.png'>"), /<img src='data:image\/png;base64,/);
+  });
+  test("leaves oversized, missing and out-of-repo images alone", () => {
+    for (const html of ['<img src="big.png">', '<img src="nope.png">', '<img src="../../outside.png">']) {
+      assert.equal(inline(html), html);
+    }
+  });
+  test("data-src isn't treated as the image", () => {
+    const html = '<img data-src="my%20img.png">';
+    assert.equal(inline(html), html);
+  });
+});