8940631 | website

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

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

8940631 — pyrossh 2026-11-06T17:18:02+05:30

Add a reading page for markdown files under /docs/

Files changed (6) hide show

assets/css/repos.css +13 -0
src/_data/repoFiles.js +3 -4
src/_helpers/repoMarkdown.js +17 -8
src/repos/doc.njk +28 -0
tests/pages.test.js +15 -1
tests/repoMarkdown.test.js +26 -14

assets/css/repos.css CHANGED Viewed

@@ -446,6 +446,19 @@
   }
 }
+/* The same strip above a doc page, with a way across to the code view. */
+.doc-header {
+  margin-bottom: 1rem;
+  border: 1px solid var(--color-pre-bg);
+  border-radius: 0.4rem;
+  a {
+    flex-shrink: 0;
+    font-size: 0.9rem;
+    text-decoration: underline;
+  }
+}
 /* diff2html ships light tokens on :root and a dark set it only applies under
    a `.d2h-dark-color-scheme` class we never add. Redefining the base tokens
    with light-dark() follows the same color-scheme as the rest of the site, so

src/_data/repoFiles.js CHANGED Viewed

@@ -13,10 +13,9 @@ import {
 } from "../_helpers/gitRepos.js";
 import { highlightCode } from "../_helpers/highlightCode.js";
 import { mapPool } from "../_helpers/pool.js";
-import { renderRepoMarkdown } from "../_helpers/repoMarkdown.js";
+import { isRenderedMarkdown, renderRepoMarkdown } from "../_helpers/repoMarkdown.js";
 const CONCURRENCY = 8;
-const MARKDOWN_EXTENSIONS = new Set(["md", "markdown"]);
 const renderFile = (repo, file) => {
   const full = path.join(repo.dir, file.path);
@@ -24,7 +23,7 @@ const renderFile = (repo, file) => {
   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)) {
+  if (isRenderedMarkdown(file)) {
     const html = renderRepoMarkdown(source, { repoId: repo.id, files: repo.files, filePath: file.path });
     return { kind: "markdown", html: inlineMarkdownImages(html, repo.dir, file.path) };
   }
@@ -41,7 +40,7 @@ export default async () => {
     // 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-v2-${repo.id}`;
+    const cacheKey = `files-v3-${repo.id}`;
     let entries = cacheable ? readCache(cacheKey, sha) : null;
     if (!entries) {

src/_helpers/repoMarkdown.js CHANGED Viewed

@@ -1,6 +1,6 @@
 import path from "node:path";
 import MarkdownIt from "markdown-it";
-import { decodePath } from "./gitRepos.js";
+import { LARGE_FILE_SIZE, decodePath } from "./gitRepos.js";
 import { highlightFenceCode } from "./highlightCode.js";
 const md = new MarkdownIt({ html: true, linkify: true, highlight: highlightFenceCode });
@@ -36,19 +36,25 @@ const FRONT_MATTER = /^---\r?\n[\w-]+:[\s\S]*?\r?\n---\r?\n/;
 const encodePath = (filePath) => filePath.split("/").map(encodeURIComponent).join("/");
+/** Whether a repo file is rendered as a document, so has a page under /docs/. */
+export const isRenderedMarkdown = (file) =>
+  /\.(md|markdown)$/i.test(file.path) && !(file.size > LARGE_FILE_SIZE);
 // 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 exact = files.find((f) => f.path === target);
+  if (exact) return exact;
   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;
+  return readme ?? inFolder[0];
 };
 // Repo markdown links relative to its own file, as GitHub resolves them. Here
+// those links need rewriting: documents open on their reading page under
-// that file's content lives at /repos/<id>/files/<path>/, so those links need
+// /repos/<id>/docs/<path>/ and anything else in the code view under
-// rewriting, and a leading `/` means the repo root. Targets not in the repo are
+// /repos/<id>/files/<path>/. A leading `/` means the repo root. Targets not in
-// left as written. `href` is still HTML-escaped, so `&` is `&amp;` here.
+// the repo are left as written. `href` is still HTML-escaped, so `&` is `&amp;`.
 const resolveLink = (href, repoId, files, filePath) => {
   if (/^(#|\/\/|[a-z][a-z0-9+.-]*:)/i.test(href)) return href;
@@ -61,7 +67,10 @@ const resolveLink = (href, repoId, files, filePath) => {
   if (target === ".") return `/repos/${repoId}/files/${suffix}`;
   const file = findLinkTarget(files, target);
+  if (file) {
+    const route = isRenderedMarkdown(file) ? "docs" : "files";
-  if (file) return `/repos/${repoId}/files/${encodePath(file)}/${suffix}`;
+    return `/repos/${repoId}/${route}/${encodePath(file.path)}/${suffix}`;
+  }
   // Scheme-less external links, e.g. [Teensy](www.pjrc.com/store/teensy3.html)
   return /^www\./i.test(href) ? `https://${href}` : href;
@@ -69,7 +78,7 @@ const resolveLink = (href, repoId, files, filePath) => {
 /**
  * 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
+ * site's doc and 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.
  *

src/repos/doc.njk ADDED Viewed

@@ -0,0 +1,28 @@
+---js
+const pagination = {
+  data: "repoFiles",
+  size: 1,
+  alias: "item",
+  before: (entries) => entries.filter((entry) => entry.render.kind === "markdown"),
+};
+const permalink = "/repos/{{ item.repoId }}/docs/{{ item.file.path }}/";
+const layout = "layout.njk";
+const eleventyComputed = {
+  title: "{{ item.file.name }} | {{ item.repo.data.title }}",
+  description: "{{ item.file.path }} — document in {{ item.repo.data.title }}",
+  robots: "noindex, follow",
+};
+---
+{% from "repo-layout.njk" import repoLayout %}
+{# The reading view of a markdown file: the same render as the code view, at the
+   README's width without the file tree. Links between documents land here. #}
+<div id="repo-page">
+  {{ repoLayout(item.repo.id, item.repo.data.title, item.repo.data.description, item.repo.data.tags, "Readme", item.repo.version) }}
+  <div id="repo-content">
+    <div class="file-layout doc-header">
+      <div class="title">{{ item.file.name | fileIcon(item.file.ext) | safe }}<span>{{ item.file.path }}</span></div>
+      <a href="/repos/{{ item.repoId }}/files/{{ item.file.path }}/">Open in Code</a>
+    </div>
+    <article class="markdown-body">{{ item.render.html | safe }}</article>
+  </div>
+</div>

tests/pages.test.js CHANGED Viewed

@@ -251,6 +251,20 @@ describe("repo pages", () => {
     assert.notEqual(style.color, style.parentColor);
   });
+  test("markdown files have a reading page without the file tree", async () => {
+    const response = await goto(`/repos/${repoId}/docs/README.md/`);
+    assert.equal(response.status(), 200);
+    await page.locator("#repo-content > .markdown-body").waitFor();
+    assert.equal(await page.locator(".file-explorer").count(), 0);
+    await page.click(".doc-header a");
+    await page.waitForURL(`${server.url}/repos/${repoId}/files/README.md/`);
+  });
+  test("other files have no reading page", async () => {
+    assert.equal((await goto(`/repos/${repoId}/docs/package.json/`)).status(), 404);
+  });
   for (const colorScheme of ["dark", "light"]) {
     test(`markdown text is comfortably readable in ${colorScheme} mode`, async () => {
       await page.emulateMedia({ colorScheme });
@@ -367,6 +381,6 @@ test("no unexpected console errors were logged across visited pages", () => {
   // The deliberate 404 tests above trigger a browser-level "failed to load
   // resource" console entry for their own navigation requests — that's the
   // behavior under test there, not a bug, so they're excluded here.
-  const unexpected = consoleErrors.filter((msg) => !/this-page-does-not-exist|\/(history|blame)\/\]/.test(msg));
+  const unexpected = consoleErrors.filter((msg) => !/this-page-does-not-exist|\/(history|blame)\/\]|\/docs\/package\.json\/\]/.test(msg));
   assert.deepEqual(unexpected, []);
 });

tests/repoMarkdown.test.js CHANGED Viewed

@@ -6,28 +6,40 @@ 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 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", "UPPER.MD"].map((p) => ({ path: p })),
+  { path: "docs/huge.md", size: LARGE_FILE_SIZE + 1 },
+];
 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", () => {
+  test("links to markdown files open their doc pages", () => {
-    assert.equal(href("[x](docs/language.md)"), "/repos/plum/files/docs/language.md/");
+    assert.equal(href("[x](docs/language.md)"), "/repos/plum/docs/docs/language.md/");
-    assert.equal(href("[x](./docs/language.md)"), "/repos/plum/files/docs/language.md/");
+    assert.equal(href("[x](./docs/language.md)"), "/repos/plum/docs/docs/language.md/");
+    assert.equal(href("[x](UPPER.MD)"), "/repos/plum/docs/UPPER.MD/");
+  });
+  test("links to other files open the code view", () => {
+    assert.equal(href("[x](examples/basics.plum)"), "/repos/plum/files/examples/basics.plum/");
+  });
+  test("markdown too large to render has no doc page, so opens the code view", () => {
+    assert.equal(href("[x](docs/huge.md)"), "/repos/plum/files/docs/huge.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](std.md)", "docs/language.md"), "/repos/plum/docs/docs/std.md/");
-    assert.equal(href("[x](../README.md)", "docs/language.md"), "/repos/plum/files/README.md/");
+    assert.equal(href("[x](../README.md)", "docs/language.md"), "/repos/plum/docs/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");
+    assert.equal(href("[x](docs/std.md#strings)"), "/repos/plum/docs/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](guide/)"), "/repos/plum/docs/guide/README.md/");
     assert.equal(href("[x](../examples)", "docs/language.md"), "/repos/plum/files/examples/arrays.plum/");
   });
@@ -36,20 +48,20 @@ describe("renderRepoMarkdown links", () => {
   });
   test("paths with spaces stay encoded", () => {
-    assert.equal(href("[x](my%20docs/a%20b.md)"), "/repos/plum/files/my%20docs/a%20b.md/");
+    assert.equal(href("[x](my%20docs/a%20b.md)"), "/repos/plum/docs/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/");
+    assert.equal(href("[x](c%23/q&a.md)"), "/repos/plum/docs/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/");
+    assert.equal(href("[x](/docs/std.md)", "guide/intro.md"), "/repos/plum/docs/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.equal(href('<a href="docs/std.md">x</a>'), "/repos/plum/docs/docs/std.md/");
-    assert.match(render("<a href='docs/std.md'>x</a>"), /href='\/repos\/plum\/files\/docs\/std\.md\/'/);
+    assert.match(render("<a href='docs/std.md'>x</a>"), /href='\/repos\/plum\/docs\/docs\/std\.md\/'/);
   });
   test("data-href isn't treated as the link", () => {
@@ -64,7 +76,7 @@ describe("renderRepoMarkdown links", () => {
   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/");
+    assert.equal(href("[x](www.site/index.md)"), "/repos/plum/docs/www.site/index.md/");
   });
   test("links shown in code blocks are not rewritten", () => {