What I Learned While Trying My First Open-Source Contribution

Hello World

Welcome to my portfolio blog. I built this blog using MDX, which basically lets me write posts in Markdown while still being able to use React components whenever I need them. Before this, my plan was to build a blog system using a database or even a simple JSON file.

But while trying to make an open-source contribution to Weaviate.io, I noticed something interesting: they manage all their blog posts using MDX files.

Since I had never used MDX before, I had no idea how it worked. So I spent time experimenting with Claude and ChatGPT, trying to understand what exactly was happening. That’s when I realized MDX is just React at its core. It lets you mix Markdown content with components, layouts, imports, and more. Once this clicked, the architecture they used made a lot more sense.

Understanding the Folder Structure

Here’s the folder structure I found inside the Weaviate.io repo:

/public
  /blog
    /blog-name
    images (blog images)
/blog
  /blog-name
  index.mdx   (the full blog content)

Each blog gets its own folder. Inside it, they store an index.mdx file that holds the actual blog content. It's clean, simple, and surprisingly scalable. This is the same structure I’m now using for my own posts.

A Small Guilty Admission

This blog post itself uses the exact same architecture I discovered while digging through the Weaviate.io repository. Since my blog is private, you won’t see the internal structure from the outside. But going forward, I’ll be adding my own images instead of relying on external ones.

If you're curious about the original inspiration or want to learn more, check out the Weaviate.io GitHub repository here:
Weaviate GitHub Repo

Final Thoughts

I wrote this blog while attempting my first open-source contribution over a weekend. To be honest, the codebase looked intimidating at first. But I tried anyway, and I ended up learning something completely new.

That’s really the point—don’t hold yourself back just because something feels out of reach. Exploring is how you grow.