comments

Author: andy-sorge

app/(main)/blog/[slug]/page.tsx

@@ -3,9 +3,12 @@ import { join } from "path"
 
 export const dynamicParams = false
 
+// runs at build time, generates a list of all possible dynamic routes, REQUIRED for static export
 export function generateStaticParams() {
+  // list all blog post files
   const posts = readdirSync(join(process.cwd(), "/blog-posts"))
-  
+
+  // generate slugs from filename by stripping extension
   const slugs = posts.map((post) => ({
     slug: post.split(".")[0]
   }))
@@ -14,8 +17,12 @@ export function generateStaticParams() {
 }
 
 export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
+  // get url segment
   const { slug } = await params
+
+  // dynamically import post content based on slug as react component
   const { default: Post } = await import(`@/blog-posts/${slug}.mdx`)
-  
+
+  // render content as react component
   return <Post />
 }

app/(main)/blog/client-page.tsx

@@ -5,6 +5,8 @@ import Link from "next/link";
 import styles from "@/styles/blog.module.css"
 import { useState } from "react";
 
+
+// component to display information about a single post
 const Post = ({ data }: { data: PostMeta & { slug: string } }) => (
   <div className={styles.post}>
     <div style={{ width: "50%" }}>
@@ -24,13 +26,17 @@ const Post = ({ data }: { data: PostMeta & { slug: string } }) => (
 )
 
 const ClientPage = ({ posts }: { posts: (PostMeta & { slug: string })[] }) => {
-  
+
+  // stateful search query var
   const [query, setQuery] = useState("")
-  
+
+  // post data from server component
   let results = posts
-  
+
+  // filter posts if a search query is present
   if (query && query.trim().length > 0) {
     const lcQuery = query.toLowerCase();
+    // check for substring matches in post titles and in post tags
     results = posts.filter((post) => post.title.toLowerCase().includes(lcQuery) || post.tags.some(tag => tag.toLowerCase().includes(lcQuery)));
   }
 

app/(main)/blog/page.tsx

@@ -1,29 +1,17 @@
-import { readdirSync } from "fs";
-import { join } from "path";
-import { PostMeta } from "./types";
 import ClientPage from "./client-page";
+import {indexBlogPosts} from "@/lib/blog";
 
+// server component, executed at build time to use filesystem APIs in indexBlogPosts()
 const Page = async () => {
-  
-  const files = readdirSync(join(process.cwd(), "/blog-posts"))
-  
-  const posts = await Promise.all(files.map(async (file) => {
-    const { meta } = await import(`@/blog-posts/${file}`) as { meta: PostMeta }
-    
-    return {...meta, slug: file.split(".")[0]}
-  }))
-  
-  const sortedPosts = posts.sort((a, b) => {
-    const dateA = new Date(a.published).getTime()
-    const dateB = new Date(b.published).getTime()
-    
-    return dateB - dateA
-  })
+
+  // get blog posts
+  const posts = await indexBlogPosts()
 
   return (
     <main>
       <h1>Palouse RoboSub Blog</h1>
-      <ClientPage posts={sortedPosts} />
+      {/* pass post data to client component */}
+      <ClientPage posts={posts} />
     </main>
   )
 }

app/(main)/blog/types.ts

@@ -1,3 +1,4 @@
+// required metadata for all blog posts in order to index correctly
 export type PostMeta = {
   title: string,
   author: string,

app/(main)/layout.tsx

@@ -4,6 +4,7 @@ import "./main.css";
 import Header from "@/components/header";
 import Footer from "@/components/footer";
 
+// preload fonts
 const montserrat = Montserrat({
   subsets: ["latin"],
   weight: "variable"
@@ -15,6 +16,8 @@ const jetBrainsMono = JetBrains_Mono({
   variable: "--font-jetbrains"
 })
 
+
+// html head data
 export const metadata: Metadata = {
   title: "Palouse RoboSub",
   description: "The official Palouse RoboSub team website, run by WSU",

app/(main)/main.css

@@ -1,3 +1,4 @@
+/* prism.js syntax highlight stylesheet */
 @import "prismjs/themes/prism-tomorrow.css";
 
 * {
@@ -44,6 +45,7 @@ h2 {
     position: relative;
 }
 
+/* header accent mark */
 h2::before {
     content: "";
     height: 6px;
@@ -57,6 +59,7 @@ h3 {
     position: relative;
 }
 
+/* header accent mark */
 h3::before {
     content: "";
     height: 4px;
@@ -72,6 +75,7 @@ a {
     text-decoration: none;
 }
 
+/* underline animation for links */
 a::before {
     content: "";
     position: absolute;
@@ -112,6 +116,7 @@ tr:nth-child(even) {
     background-color: #ffffff;
 }
 
+/* override default monospace font in code blocks */
 code, pre {
     font-family: "JetBrains Mono" !important;
 }

app/(main)/page.tsx

@@ -2,26 +2,12 @@ import Image from "next/image";
 import styles from "@/styles/home.module.css"
 import Link from "next/link";
 import { ArrowRight } from "lucide-react";
-import { readdirSync } from "fs";
-import { join } from "path";
-import { PostMeta } from "./blog/types";
+import {indexBlogPosts} from "@/lib/blog";
 
 const Page = async () => {
 
-  const files = readdirSync(join(process.cwd(), "/blog-posts"))
-
-  const posts = await Promise.all(files.map(async (file) => {
-    const { meta } = await import(`@/blog-posts/${file}`) as { meta: PostMeta }
-
-    return {...meta, slug: file.split(".")[0]}
-  }))
-
-  const sortedPosts = posts.sort((a, b) => {
-    const dateA = new Date(a.published).getTime()
-    const dateB = new Date(b.published).getTime()
-
-    return dateB - dateA
-  })
+  // get blog posts
+  const posts = await indexBlogPosts()
 
   return (
     <main className={styles.main}>
@@ -50,18 +36,19 @@ const Page = async () => {
             <Link href="/blog" className={styles.link}>Check the blog out here <ArrowRight/></Link>
           </div>
           <div>
+            {/* show 3 newest blog posts */}
             <h4 style={{ margin: "0" }}>Recent Posts</h4>
             <div className={styles.post}>
-              <Link href={`/blog/${sortedPosts[0].slug}`}>{sortedPosts[0].title}</Link>
-              <div>{sortedPosts[0].published}</div>
+              <Link href={`/blog/${posts[0].slug}`}>{posts[0].title}</Link>
+              <div>{posts[0].published}</div>
             </div>
             <div className={styles.post}>
-              <Link href={`/blog/${sortedPosts[1].slug}`}>{sortedPosts[1].title}</Link>
-              <div>{sortedPosts[1].published}</div>
+              <Link href={`/blog/${posts[1].slug}`}>{posts[1].title}</Link>
+              <div>{posts[1].published}</div>
             </div>
 			{/*<div className={styles.post}>
-              <Link href={`/blog/${sortedPosts[2].slug}`}>{sortedPosts[2].title}</Link>
-              <div>{sortedPosts[0].published}</div>
+              <Link href={`/blog/${posts[2].slug}`}>{posts[2].title}</Link>
+              <div>{posts[0].published}</div>
             </div>*/}
           </div>
         </div>

lib/blog.ts

@@ -0,0 +1,27 @@
+import {PostMeta} from "@/app/(main)/blog/types";
+import {readdirSync} from "fs";
+import {join} from "path";
+
+const indexBlogPosts = async () => {
+  // get all post files
+  const files = readdirSync(join(process.cwd(), "/blog-posts"))
+
+  // collect metadata from all posts
+  const posts = await Promise.all(files.map(async (file) => {
+    const { meta } = await import(`@/blog-posts/${file}`) as { meta: PostMeta }
+
+    return {...meta, slug: file.split(".")[0]}
+  }))
+
+  // sort posts by date published
+  const sortedPosts = posts.sort((a, b) => {
+    const dateA = new Date(a.published).getTime()
+    const dateB = new Date(b.published).getTime()
+
+    return dateB - dateA
+  })
+
+  return sortedPosts;
+}
+
+export {indexBlogPosts};

mdx-components.tsx

@@ -1,9 +1,12 @@
 import type { MDXComponents } from "mdx/types";
 
 const components: MDXComponents = {
+  // wrap the default export of an MDX file in <main>
   wrapper: ({ children }) => <main>{children}</main>,
+  // override input elements from MDX files
   input: (props) => {
     if (props.type === "checkbox" && props.disabled) {
+      // add color to disabled checkboxes
       return (
         <input
           type="checkbox"
@@ -12,6 +15,7 @@ const components: MDXComponents = {
         />
       );
     }
+    // leave all other input elements unaffected
     return <input {...props} />;
   },
 };

next.config.ts

@@ -3,23 +3,33 @@ import createMDX from "@next/mdx"
 
 const nextConfig: NextConfig = {
   images: {
-    remotePatterns: [
-      {
-        protocol: "https",
-        hostname: "picsum.photos",
-        pathname: "**"
-      }
-    ],
+    // disable automatic image optimization, REQUIRED for static export
     unoptimized: true
   },
-  pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
+
+  // add mdx to list of valid page extensions
+  pageExtensions: ['js', 'jsx', 'mdx', 'ts', 'tsx'],
+
+  // builds generate static files
   output: "export",
 };
 
 const withMDX = createMDX({
-  extension: /\.(md|mdx)$/,
+  extension: /\.(mdx)$/,
   options: {
+    /*
+    * remark-gfm enables github flavored markdown parsing
+    *
+    * remark-prism enables language-aware syntax highlighting in code blocks using prismjs
+    */
     remarkPlugins: ["remark-gfm", "remark-prism"],
+    /*
+    * rehype-slug automatically adds id attributes to headings
+    *
+    * rehype-autolink-headings automatically generates links to headings, which are currently
+    *   overwritten by my css. this will be fixed in the future
+    *
+    */
     rehypePlugins: ["rehype-slug", "rehype-autolink-headings"]
   }
 })