Address most review feedback

Author: alex-snezhko

README.md

@@ -34,9 +34,11 @@ git pull --recurse-submodules
 
 To make a change to a document, edit the corresponding Markdown file in [src](src). The file path matches the URL path after `/docs`, but if you have trouble finding the page you're looking for, you can click the "Edit on GitHub" button at the top of page on the website.
 
+Please note that standard library documentation is auto-generated from our standard library source with our documentation tool `grain doc`. If you'd like to make an edit to the standard library docs please do so in the corresponding source file in the main compiler monorepo found [here](https://github.com/grain-lang/grain/tree/main/stdlib). After editing the source file, you can run `grain doc stdlib -o stdlib --current-version=$(grain -v)` from the project root directory to generate the `.md` docs. The changes will be reflected on the website the next time we deploy changes for the next release!
+
 ### Adding a New Document
 
-Create your new Markdown file in the desired location within `src/content/docs`. Each document starts with some front-matter, which is a bit of yml that is given to the renderer. Since the title of the page is an `h1`, headers in your document should begin at level 2:
+Create your new Markdown file in the desired location within `src/content/docs`. Each document starts with some front-matter, which is a bit of yaml that is given to the renderer. Since the title of the page is an `h1`, headers in your document should begin at level 2:
 
 ```markdown
 ---

scripts/generateContributors.js

@@ -1,19 +1,38 @@
 import { Octokit } from "octokit";
-import fs from "node:fs";
+import fs from "node:fs/promises";
 import path from "node:path";
 import url from "node:url";
 
 async function generateContributors() {
   const octokit = new Octokit({ auth: process.env.GITHUB_ACCESS_TOKEN });
 
-  const results = await octokit.paginate(octokit.rest.repos.listContributors, {
-    owner: "grain-lang",
-    repo: "grain",
-    per_page: 25,
+  const repos = await octokit.paginate(octokit.rest.repos.listForOrg, {
+    org: "grain-lang",
+    per_page: 100,
   });
 
+  const repoContributions = await Promise.all(
+    repos
+      .filter(repo => !repo.fork)
+      .map(repo => octokit.paginate(octokit.rest.repos.listContributors, {
+        owner: "grain-lang",
+        repo: repo.name,
+        per_page: 100,
+      }))
+  );
+  
+  const contributionsFlattened = repoContributions.flat();
+
+  const groupedByLogin = Object.groupBy(contributionsFlattened, c => c.login);
+  const results = Object.entries(groupedByLogin).map(([login, contributionInfos]) => ({
+    login,
+    profileUrl: contributionInfos[0].html_url,
+    avatarUrl: contributionInfos[0].avatar_url,
+    count: contributionInfos.reduce((acc, c) => acc + c.contributions, 0)
+  }))
+
   const cwd = path.dirname(url.fileURLToPath(import.meta.url));
-  fs.writeFileSync(path.join(cwd, "..", "contributors.json"), JSON.stringify(results, undefined, 4));
+  await fs.writeFile(path.join(cwd, "..", "contributors.json"), JSON.stringify(results, undefined, 4));
 }
 
 await generateContributors();

src/blogAuthors.ts

@@ -0,0 +1,14 @@
+import { ImageMetadata } from "astro";
+import type { BlogAuthor } from "./types";
+
+import oscarHeadshot from "./images/headshots/oscar-headshot-square.jpg";
+import philipHeadshot from "./images/headshots/philip-headshot-square.jpg";
+import blaineHeadshot from "./images/headshots/blaine-headshot-square.jpg";
+import marcusHeadshot from "./images/headshots/marcus-headshot-square.jpg";
+
+export const authorInfo: Record<BlogAuthor, { xLink: string; github: string; headshot: ImageMetadata }> = {
+  "Oscar Spencer": { xLink: "oscar_spen", github: "ospencer", headshot: oscarHeadshot },
+  "Philip Blair": { xLink: "Philip_E_Blair", github: "peblair", headshot: philipHeadshot },
+  "Blaine Bublitz": { xLink: "BlaineBublitz", github: "phated", headshot: blaineHeadshot },
+  "Marcus Roberts": { xLink: "marcusr", github: "marcusroberts", headshot: marcusHeadshot },
+};

src/components/BlogAuthor.astro

@@ -1,18 +1,8 @@
 ---
 import { Image } from "astro:assets";
-import oscarHeadshot from "../images/headshots/oscar-headshot-square.jpg";
-import philipHeadshot from "../images/headshots/philip-headshot-square.jpg";
-import blaineHeadshot from "../images/headshots/blaine-headshot-square.jpg";
-import marcusHeadshot from "../images/headshots/marcus-headshot-square.jpg";
 import type { CollectionEntry } from "astro:content";
 import type { BlogAuthor } from "../types";
-
-const headshotMap: Record<BlogAuthor, ImageMetadata> = {
-  "Oscar Spencer": oscarHeadshot,
-  "Philip Blair": philipHeadshot,
-  "Blaine Bublitz": blaineHeadshot,
-  "Marcus Roberts": marcusHeadshot,
-};
+import { authorInfo } from "../blogAuthors";
 
 interface Props {
   entry: CollectionEntry<"blog">;
@@ -26,7 +16,7 @@ const { entry, imgClass, nameClass, dateClass } = Astro.props;
 
 <div class="flex items-center gap-3 w-fit">
   <Image
-    src={headshotMap[entry.data.author as BlogAuthor]}
+    src={authorInfo[entry.data.author as BlogAuthor].headshot}
     alt={entry.data.author}
     class={`rounded-full object-cover ${imgClass ?? ""}`}
   />

src/components/BlogEntry.astro

@@ -2,21 +2,11 @@
 import type { CollectionEntry } from "astro:content"
 import TypographyContainer from "./TypographyContainer.astro";
 import ArrowLeft from "./icons/ArrowLeft.astro";
-import TwitterIcon from "./icons/TwitterIcon.astro";
 import GithubIcon from "./icons/GithubIcon.astro";
-import oscarHeadshot from "../images/headshots/oscar-headshot-square.jpg";
-import philipHeadshot from "../images/headshots/philip-headshot-square.jpg";
-import blaineHeadshot from "../images/headshots/blaine-headshot-square.jpg";
-import marcusHeadshot from "../images/headshots/marcus-headshot-square.jpg";
 import type { BlogAuthor } from "../types";
 import { Image } from "astro:assets";
-
-const authorInfo: Record<BlogAuthor, { twitter: string; github: string; headshot: ImageMetadata }> = {
-  "Oscar Spencer": { twitter: "oscar_spen", github: "ospencer", headshot: oscarHeadshot },
-  "Philip Blair": { twitter: "Philip_E_Blair", github: "peblair", headshot: philipHeadshot },
-  "Blaine Bublitz": { twitter: "BlaineBublitz", github: "phated", headshot: blaineHeadshot },
-  "Marcus Roberts": { twitter: "marcusr", github: "marcusroberts", headshot: marcusHeadshot },
-};
+import { authorInfo } from "../blogAuthors";
+import NewsletterSignup from "./NewsletterSignup.astro";
 
 interface Props {
   entry: CollectionEntry<"blog">;
@@ -47,8 +37,8 @@ const { entry } = Astro.props;
         <p class="uppercase text-xs font-semibold">Author</p>
         <div class="flex gap-2 items-center">
           {entry.data.author}
-          <a class="hidden md:block" href={`https://twitter.com/${authorInfo[entry.data.author as BlogAuthor].twitter}`}><TwitterIcon class="w-4" /></a>
-          <a class="hidden md:block" href={`https://github.com/${authorInfo[entry.data.author as BlogAuthor].github}`}><GithubIcon class="w-4" /></a>
+          <a class="hidden md:block" href={`https://x.com/${authorInfo[entry.data.author as BlogAuthor].xLink}`} aria-label="X link"><span class="font-bold text-xl">𝕏</span></a>
+          <a class="hidden md:block" href={`https://github.com/${authorInfo[entry.data.author as BlogAuthor].github}`} aria-label="GitHub link"><GithubIcon class="w-4" /></a>
         </div>
       </div>
     </div>
@@ -68,4 +58,6 @@ const { entry } = Astro.props;
   <TypographyContainer>
     <slot />
   </TypographyContainer>
+  <hr class="border-color-dim-2 my-10 md:my-16" />
+  <NewsletterSignup />
 </div>

src/components/BlogHero.astro

@@ -3,7 +3,6 @@ import type { CollectionEntry } from "astro:content";
 import { Image } from "astro:assets";
 import BlogAuthor from "./BlogAuthor.astro";
 import ChevronRightIcon from "./icons/ChevronRightIcon.astro";
-import TwitterIcon from "./icons/TwitterIcon.astro";
 import DiscordIcon from "./icons/DiscordIcon.astro";
 import GrainLogo from "./icons/GrainLogo.astro";
 
@@ -20,23 +19,25 @@ const { entry } = Astro.props;
       <GrainLogo class="w-8 h-8 md:w-12 md:h-12 inline-block align-middle fill-color-accent" />
       <span class="md:pl-1 text-2xl md:text-4xl font-semibold align-middle">The Grain Blog</span>
     </div>
-    <div class="flex md:hidden gap-4 text-color-accent">
+    <div class="flex md:hidden gap-4 text-color-accent items-center">
       <a
-        href="https://twitter.com/grain_lang"
+        href="https://x.com/grain_lang"
         target="_blank"
+        aria-label="X link"
       >
-        <TwitterIcon class="w-7 h-7 fill-color-accent" />
+        <span class="font-bold text-3xl text-color-accent">𝕏</span>
       </a>
       <a
-        href="https://twitter.com/grain_lang"
+        href="https://discord.com/invite/grain-lang"
         target="_blank"
+        aria-label="Discord link"
       >
         <DiscordIcon class="w-7 h-7 fill-color-accent" />
       </a>
     </div>
     <div class="hidden md:block text-color-accent">
       Also find us on
-      <a href="https://twitter.com/grain_lang" class="underline">Twitter</a>
+      <a href="https://x.com/grain_lang" class="underline">X</a>
       and
       <a href="https://discord.com/invite/grain-lang" class="underline">Discord</a>
     </div>

src/components/CodeExamples.astro

@@ -67,11 +67,11 @@ const lang = grainLang as any;
       ))}
     </div>
     <div class="flex justify-between items-center text-purple-40 w-full lg:w-3/5 mx-auto">
-      <button id="prev" class="inline-block border border-purple-40 hover:bg-purple-80 rounded-full p-3 rotate-180">
+      <button id="prev" class="inline-block border border-purple-40 hover:bg-purple-80 rounded-full p-3 rotate-180" aria-label="Previous example">
         <ChevronRightIcon class="h-3.5" />
       </button>
       <p id="selected-example" class="text-lg"></p>
-      <button id="next" class="inline-block border border-purple-40 hover:bg-purple-80 rounded-full p-3">
+      <button id="next" class="inline-block border border-purple-40 hover:bg-purple-80 rounded-full p-3" aria-label="Next example">
         <ChevronRightIcon class="h-3.5" />
       </button>
     </div>

src/components/Contributors.astro

@@ -9,7 +9,9 @@ const excludeList = [
   "ng-marcus",
   "alex-snezhko",
   "spotandjake",
-  "github-actions[bot]"
+  "github-actions[bot]",
+  "grainbot",
+  "dependabot[bot]",
 ];
 
 const special = [
@@ -24,13 +26,28 @@ const special = [
   </h2>
   {contributors
     .filter(x => !excludeList.includes(x.login))
+    .toSorted((x, y) => {
+      const xSpecial = special.includes(x.login);
+      const ySpecial = special.includes(y.login);
+      if (xSpecial && !ySpecial) {
+        return -1;
+      } else if (!xSpecial && ySpecial) {
+        return 1;
+      } else {
+        return y.count - x.count;
+      }
+    })
     .map(contributor => (
       <div class="inline-block relative">
-        <a href={contributor.html_url} class="p-0.5 inline-block">
-          <img class={`w-14 h-14 rounded-full p-0.5 border ${special.includes(contributor.login) ? "shadow-[0_0px_8px_1px_rgb(0_0_0/0.1)] border-amber-600 shadow-amber-500" : "shadow-md border-color-dim-2"} dark:shadow-purple-80`} src={contributor.avatar_url} alt={`Image of ${contributor.login}`} />
+        <a href={contributor.profileUrl} class="p-0.5 inline-block">
+          <img
+            class={`w-14 h-14 rounded-full p-0.5 border ${special.includes(contributor.login) ? "shadow-[0_0px_8px_1px_rgb(0_0_0/0.1)] border-amber-600 shadow-amber-500" : "shadow-md border-color-dim-2"} dark:shadow-purple-80`}
+            src={contributor.avatarUrl}
+            alt={`Image of ${contributor.login}`}
+          />
         </a>
         {special.includes(contributor.login) && (
-          <a href={contributor.html_url} class="absolute text-2xl bottom-0 right-0 text-yellow-500 [text-shadow:0_0_2px_#000]">🌾</a>
+          <a href={contributor.profileUrl} class="absolute text-2xl bottom-0 right-0 text-yellow-500 [text-shadow:0_0_2px_#000]">🌾</a>
         )}
       </div>
     ))}

src/components/CoreTeamMemberInfo.astro

@@ -53,7 +53,7 @@ const { profileImage, name, title, role, githubUsername } = Astro.props;
   <div class="-z-10 transition duration-300 opacity-0 peer-hover:opacity-100 absolute top-20 left-44 bg-color-blurb-3 w-36 h-[26rem] rounded-full rotate-[10deg] blur-3xl" data-desc="color-ellipsis" />
 
   <div class="px-2 mt-5">
-    <h2 class="text-2xl font-bold mb-2"><span class="align-middle">{name}</span> <a href={`https://github.com/${githubUsername}`}><GithubIcon class="inline w-6 h-6 ml-1 align-middle" /></a></h2>
+    <h2 class="text-2xl font-bold mb-2"><span class="align-middle">{name}</span> <a href={`https://github.com/${githubUsername}`} aria-label="GitHub link"><GithubIcon class="inline w-6 h-6 ml-1 align-middle" /></a></h2>
     <h3 class="text-lg">{title}</h3>
     <h3 class="text-lg text-gray-50">{role}</h3>
   </div>

src/components/DocLinkGroup.astro

@@ -1,6 +1,7 @@
 ---
 import type { CollectionEntry } from "astro:content";
 import DocLink from "./DocLink.astro";
+import path from "node:path";
 
 interface Props {
   title: string | null;
@@ -14,5 +15,14 @@ const { title, entries } = Astro.props;
   <h2 class="text-xl font-semibold mt-6 mb-2">{title}</h2>
 )}
 <div class="border-l-2 border-color-dim-3">
-  {entries.map(x => <DocLink id={x.id}>{x.data.title}</DocLink>)}
+  {entries.map(x => {
+    const pathParts = x.id.split(path.sep);
+    const pathPrefixes = pathParts.slice(1, -1);
+    return path.dirname(x.id) !== pathParts[0] && pathPrefixes.length > 0
+      ? (
+        <DocLink id={x.id}><span class="text-color-dim-1">{pathPrefixes.join("/")} / </span><span>{x.data.title}</span></DocLink>
+      ) : (
+        <DocLink id={x.id}>{x.data.title}</DocLink>
+      )
+  })}
 </div>