Skip to content
DevPortals.Tech
Docs Portfolio
Blog

Blog

Integrating a Next.js Portfolio as a Subdomain: A Technical Deep Dive

- 9 min read
Joaquin Romo

Introduction

Section titled “Introduction”

As a documentation engineer and technical writer, I needed a way to showcase both my technical writing work and my development projects. I had already built a documentation site using Astro and Starlight at devportals.tech, and I wanted to add my Next.js portfolio site without disrupting the existing architecture.

This post walks through the technical decisions, implementation challenges, and solutions I encountered while integrating these two separate applications into a cohesive experience.

The Challenge: Two Sites, One Domain

Section titled “The Challenge: Two Sites, One Domain”

I had two distinct applications:

  1. Main documentation site: Built with Astro + Starlight, hosted at devportals.tech
  2. Portfolio site: Built with Next.js, deployed separately on Vercel

The question was: how do I connect these two sites in a way that feels unified to visitors while maintaining deployment independence?

Architecture Decision: Subdomain vs. Subdirectory

Section titled “Architecture Decision: Subdomain vs. Subdirectory”

I considered three approaches:

Option 1: Separate Domain

Section titled “Option 1: Separate Domain”
  • Pros: Complete independence, simplest DNS setup
  • Cons: Weakens brand cohesion, splits SEO authority, requires users to remember two URLs

Option 2: Subdirectory (devportals.tech/portfolio)

Section titled “Option 2: Subdirectory (devportals.tech/portfolio)”
  • Pros: Single domain, better for SEO, unified URL structure
  • Cons: Requires complex proxy/rewrite rules, complicates deployments, potential routing conflicts

Option 3: Subdomain (portfolio.devportals.tech)

Section titled “Option 3: Subdomain (portfolio.devportals.tech)”
  • Pros: Deployment independence, clean separation, simple DNS, maintains brand
  • Cons: Splits SEO slightly, requires DNS configuration

I chose the subdomain approach because it provided the best balance of deployment flexibility and brand cohesion. Each application can be deployed independently, use different frameworks, and scale separately while still feeling like part of the same ecosystem.

Building a GitHub Contribution Graph with Next.js Server Components

- 3 min read
Joaquin Romo

When building a portfolio, showing your GitHub activity tells a story about your consistency, the technologies you work with, and how you balance personal and professional projects. In this guide, I walk you through building a production-ready GitHub contribution graph using Next.js 14 Server Components and TypeScript.

Why Server Components?

Section titled “Why Server Components?”

Unlike client-side rendering, Server Components allow us to fetch data directly on the server, keeping our GitHub API token secure and improving initial page load performance. This is especially important for portfolio sites where first impressions matter.

Why Redirect Management is Critical for Developer Portals

- 7 min read
Joaquin Romo

Redirects are one of those infrastructure pieces you don’t think about until you need them. I’ve worked with them in two different contexts: a large-scale developer portal using Netlify with complex wildcard patterns and catch-all rules, and now this personal portfolio site on Vercel where I just implemented my first redirect after renaming a directory.

What struck me is how different platforms handle the same fundamental problem—keeping URLs stable when content moves—but with vastly different syntax and approaches. Whether you’re managing hundreds of versioned documentation pages or just reorganizing a small site, the principles remain the same.

From Chaos to Clarity: A Technical Writer's Journey Through Git Cherry-Picking and Team Collaboration

- 9 min read
Joaquin Romo

Introduction

Section titled “Introduction”

As a Senior Technical Writer, my role extends beyond crafting clear documentation—it involves navigating complex technical challenges to help my team achieve our objectives. Recently, I led an effort to salvage months of work from a stale feature branch, teaching me valuable lessons about git workflows, team collaboration, AI-assisted development, and the resilience required in technical documentation work.

The Challenge

Section titled “The Challenge”

Our team had been working on a major documentation revamp for several months. Multiple writers contributed to a shared feature branch, building a comprehensive update to our product’s documentation. However, as weeks turned into months, our feature branch became increasingly disconnected from the main branch—912 commits behind, to be exact.

The branch had contributions from numerous team members, each adding valuable content, but the cumulative drift from main created an untenable situation. When we finally attempted to merge, we faced hundreds of merge conflicts. The traditional merge approach would require untangling conflicts across dozens of files, risking the loss of carefully crafted content or introducing errors that could take days to identify.

We needed a different strategy: cherry-picking.

From Forks to Branches: Streamlining Team Git Workflows

- 4 min read
Joaquin Romo

As part of a GitHub working group within a 50-person technical writing team, I recently helped lead our transition from a fork-based workflow to a centralized branching strategy. This shift simplified our collaboration model and reduced friction across four sub-teams. Here’s what we learned.

The Challenge

Section titled “The Challenge”

Our team of technical writers was using personal forks of our main documentation repository. While this approach worked, we identified several pain points:

  • Extra complexity for common operations
  • Confusion about which remote to push/pull from
  • Inconsistent workflows across team members
  • Limited value for our use case compared to open-source projects

The GitHub working group formed with representatives from each sub-team to evaluate whether forks still made sense for our internal collaboration model.