I'd been neglecting my GitHub blog for a while. I kept telling myself "I'll clean it up someday," but then I realized I actually needed a proper space to document and share what I was learning. So I decided to rebuild the blog from scratch.
Why I Chose Next.js#
Svelte was gaining momentum at the time, but I figured Next.js was the better choice if I wanted to get the blog done quickly. The learning curve was much shorter sticking with just Next.js rather than learning Svelte from scratch, picking up SvelteKit, and hunting for the right libraries.
My old blog was on Next.js 12, and when I tried upgrading via npx, it weirdly wouldn't work properly. So I ended up creating a new project and applying shadcn from there. Now I'm running a static blog with the Next.js 14 + Contentlayer combo.
Setting Up the Dev Environment#
Since the iMac I was using at the time didn't have Node installed, I used Next.js's Docker example. I chose pnpm as the package manager — installing it via Homebrew is dead simple.
pnpm create next-app --example with-docker nextjs-dockerThis single command creates a Docker-based Next.js project.
Features a Blog Needs#
I put together a list of features the blog would need. Most of them can be built by combining Next.js's built-in features with external libraries.
- Routing — Page navigation handled by Next.js App Router
- Image rendering — External images in markdown optimized to data URIs
- Comments — A GitHub-based comment system
Blog Layout#
Here's how the blog is currently structured:
| Page | Role |
|---|---|
| Home | Latest posts, search, post list |
| Books | Book list and detail views |
| Tags | Browse posts by tag |
| About | About me |
Home handles both the post list and search, so there's no need for a separate Posts page. On the Books page, I decided to include the most memorable quotes from each book at the bottom.
Converting Markdown to HTML#
To display blog posts, markdown files need to be converted to HTML. Currently Contentlayer handles this, but I originally built the conversion pipeline manually.
The approach was to grab all posts from the posts folder in generateStaticParams, read each one, convert markdown to HTML with unified, and extract metadata from the frontmatter to create Post objects.
Here's a comparison of popular tools for markdown conversion:
| Library | Characteristics |
|---|---|
| gray-matter | Specialized for frontmatter parsing |
| marked | Lots of GitHub stars, battle-tested for 10+ years |
| unified | Rich plugin ecosystem with excellent extensibility |
I went with the unified family, prioritizing extensibility. Even now, I'm combining remark/rehype plugins inside Contentlayer for syntax highlighting, math rendering, external link handling, and more.
This article (Japanese) was really helpful when working with the unified package.
Visualizing the Learning Journey with a Mind Map#
While building the blog, another idea came to mind. I was inspired by the notion that attaching meaning to learning helps with retention.
What if I created a page where each tag could be viewed as a mind map? Take the things I've studied and posted about, turn them into dots, and connect those dots with lines.
For example, if I studied Docker, I could visually track the process: how I came to understand what Docker is, what perspective I developed, and what I'll study next.
Being able to see these connections visually is motivating in itself.
Looking Back#
Rebuilding the blog wasn't just about switching up the tech stack. It was about creating a system for organizing what I've learned and sharing that process with others.
Rather than waiting for the perfect blog, just building it and improving one thing at a time is the best way to start.
No man can succeed in a line of endeavor which he does not like.
— Napoleon Hill
