Skip to content

Building My Portfolio with Docs as Code (an adventure in trial-and-error vibecoding)

January 19, 2026

Why this site exists

I’ve owned my domain for a long time.

Over the years, I’ve used it for a few different experiments: a WordPress site, a half-finished documentation setup, and a couple of “I’ll come back to this later” ideas that never quite turned into a portfolio I was proud of. What I wanted this time was simple and specific:

  • A lightweight personal site
  • A place to publish technical writing samples
  • A blog where I could write about process, tooling, and learning
  • A docs as code workflow, so the site itself reflects how I work

I’m a technical writer, not a developer. I don’t build websites for a living, and I’ve never set one up end to end without help. This project wasn’t about becoming a web developer, it was about choosing the right tools and using them thoughtfully.

My first attempt at vibecoding didn’t quite go the way I expected.

The Hugo phase: vibecoding, but stuck in a loop

My first approach was to build the site using Hugo with the PaperMod theme, deployed via GitHub Pages and connected to my custom domain.

I worked through this setup with the help of ChatGPT, and on paper, everything looked right. Locally, the site would render correctly. But getting it deployed was another story.

Here’s a high-level summary of what I tried:

  • Verified Hugo configuration and theme setup
  • Checked GitHub Pages deployment settings
  • Investigated missing CSS and JavaScript output
  • Ran multiple clean rebuilds
  • Compared the theme structure against the official repo

Despite all of this, I kept hitting the same pattern:

  • I’d get the layout working locally, but the site wouldn’t deploy correctly
  • Then the site would deploy, but the layout and styling would disappear
  • I’d fix one issue, only for the other one to come back again

Each time, ChatGPT would tell me I was almost there. Technically, that was probably true, but after a couple of days of this back-and-forth, I hit a wall. I started wondering whether this whole vibecoding idea just wasn’t for me. Maybe I didn’t have the instincts for it. Maybe this was a sign I should stick to the old familiar tools.

But the docs-as-code setup that we use at work involves an expensive MadCap Flare license, and that would be overkill for my personal portfolio. I couldn't give up just yet!

Starting fresh: moving on from Hugo

Instead of continuing down the same path, I scrapped the entire chat and started over with a different question:

What can I use to build a docs-as-code site that isn’t Hugo?

And that's when ChatGPT recommended MK Docs. I've also heard of this option around the field, so I thought why not give it a try.

I got ChatGPT to walk me through setting things up from scratch, step by step:

  • Created a new MkDocs project
  • Structured the site around Markdown files
  • Deployed to GitHub Pages
  • Connected the site to my existing domain

This time, it all worked and I'd say it was even pretty straightforward!

The site built correctly. The styling appeared. Deployments worked. I could finally focus on the content.

At this point, I felt excited, a little bit relieved, and hopeful once again that I could get vibecoding to work for me!

What vibecoding actually looks like (for me)

One of the biggest takeaways from this process is that vibecoding isn’t about asking AI to “do it all for you.”

It still requires understanding:

  • How the site is structured
  • Where content lives
  • How deployments work
  • What to change — and what not to touch

AI helped me get unstuck, reduce cognitive load, and make better decisions faster, but I still had to learn enough to keep the site running and updated.

Now, I’m writing posts in Obsidian, editing real Markdown files, and deploying changes myself. I’m comfortable looking under the hood, tweaking things when needed, and iterating over time.

That’s what feels empowering about this approach.

In conclusion

This site isn’t just a portfolio. It’s proof that I can:

  • Evaluate tooling realistically
  • Understand when to abandon a tool or process when it stops serving the goal
  • Use AI as a collaborator, not a crutch
  • Ship something that works and keep it maintained

I didn’t become a developer overnight. But I did build a system I understand well enough to own.