DevPortals.Tech | Blog

Building Custom Column Components for Text Comparisons

Wed, 04 Mar 2026 00:00:00 GMT

I needed a way to display text side-by-side for translation comparisons in blog posts. This post walks through the two component variants I shipped, the decisions behind them, and the pattern that kept the implementation simple and maintainable.

What I Asked For vs. What I Got

While Sanity CMS has a rich ecosystem of plugins, I couldn’t find anything specifically designed for parallel text display that would work seamlessly with our Astro + Sanity setup. I asked my AI pair programmer: “Let’s build a two-column component for text comparisons.”

What I had in mind: A simple, clean layout - just two columns of text side-by-side. Functional. Straightforward.

What the AI built: A boxed container with gray background, borders, visual separators, and styled like a callout component.

My first reaction was, “That’s not what I pictured.” But after reviewing it, the design was strong. It gave the comparison visual weight and emphasis. For formal translations or important side-by-side content, the container style made it stand out on the page.

This is where human-AI collaboration gets interesting.

Building Two Instead of One

Instead of asking the AI to redo it to match my original vision, I said: “I like this, but can we also make a second version? A plain newspaper-style layout without the container?”

We kept both. That was the real insight: AI does not replace your ideas, it augments them. Now I had two components where I originally planned for one:

Container Columns — The AI’s interpretation with emphasis styling
Newspaper Columns — The original vision of subtle, flowing text

Two different tools for different contexts.

Container Columns: The Creative Interpretation

The first implementation was more elaborate than my original ask:

Two text input fields (left and right columns)
50/50 split on desktop
Responsive stacking on mobile
Visual container with background and borders for emphasis
Optional label for headings like “English | Spanish”

Schema Definition

The schema was text-only to keep it simple:

src/sanity/schemaTypes/objects/containerColumns.ts

export default defineType({
  name: 'containerColumns',
  title: 'Container Columns',
  type: 'object',
  fields: [
    {
      name: 'leftText',
      type: 'text',
      rows: 10,
      validation: (Rule) => Rule.required(),
    },
    {
      name: 'rightText',
      type: 'text',
      rows: 10,
      validation: (Rule) => Rule.required(),
    },
    {
      name: 'label',
      type: 'string',
      description: 'Optional label (e.g., "English | Spanish")',
    },
  ],
});

The Renderer Component

The Astro component uses CSS Grid for the layout:

src/components/PortableTextContainerColumns.astro

<div class="container-columns-wrapper">
  {label && <div class="container-columns-label">{label}</div>}
  <div class="container-columns-container">
    <div class="column column-left">
      <p set:html={formatText(leftText)} />
    </div>
    <div class="column column-right">
      <p set:html={formatText(rightText)} />
    </div>
  </div>
</div>

<style>
  .container-columns-container {
    display: grid;
    grid-template-columns: 1fr 1fr;
    gap: 2rem;
    padding: 1.5rem;
    background-color: rgb(var(--gray-light));
    border-radius: 8px;
    border: 1px solid rgb(var(--gray));
  }

  @media (max-width: 768px) {
    .container-columns-container {
      grid-template-columns: 1fr;
    }
  }
</style>

Key design decisions:

Gray background and border for visual emphasis
Divider line between columns on desktop
Line breaks preserved with white-space: pre-wrap
Mobile-first responsive design

The Evolution: Newspaper Columns

After testing the boxed layout, I realized there was another use case — flowing text that did not need the heavy visual container. Think newspaper-style columns or subtle side-by-side comparisons that integrate more naturally with body text.

The “newspaper columns” variant would:

Remove the box styling entirely
Keep just the column structure
Be more subtle and versatile

Naming Matters

I initially called it twoColumnText, but “newspaper columns” felt more evocative and descriptive. The name instantly communicates the visual style.

The Second Component

The schema is nearly identical, but the renderer is much lighter:

src/components/PortableTextNewspaperColumns.astro

<div class="newspaper-columns-container">
  <div class="newspaper-column">
    <p set:html={formatText(leftText)} />
  </div>
  <div class="newspaper-column">
    <p set:html={formatText(rightText)} />
  </div>
</div>

<style>
  .newspaper-columns-container {
    display: grid;
    grid-template-columns: 1fr 1fr;
    gap: 3rem; /* Wider gap since there's no divider */
  }
  /* No background, no borders, no container styling */
</style>

Adding Text Alignment

With the cleaner newspaper columns, text alignment became more important. The question was: one alignment for both columns, or independent alignment per column?

The Decision: Independent Alignment

Independent alignment per column unlocks more use cases:

RTL languages: Arabic or Hebrew in the right column, right-aligned
Creative layouts: Centered poetry next to left-aligned prose
Visual balance: Match the text style to the content type

Implementation was straightforward:

// Added to newspaperColumns schema
{
  name: 'leftAlign',
  title: 'Left Column Alignment',
  type: 'string',
  options: {
    list: [
      { title: 'Left', value: 'left' },
      { title: 'Center', value: 'center' },
      { title: 'Right', value: 'right' },
    ],
  },
  initialValue: 'left',
},
{
  name: 'rightAlign',
  title: 'Right Column Alignment',
  type: 'string',
  options: {
    list: [
      { title: 'Left', value: 'left' },
      { title: 'Center', value: 'center' },
      { title: 'Right', value: 'right' },
    ],
  },
  initialValue: 'left',
},

Applied in the template with inline styles:

<div style={`text-align: ${leftAlign}`}>
  <p set:html={formatText(leftText)} />
</div>
<div style={`text-align: ${rightAlign}`}>
  <p set:html={formatText(rightText)} />
</div>

Technical Implementation Details

Why Custom Components?

Sanity has a plugin ecosystem, but custom components give you:

Full control over styling and behavior
No dependencies on third-party packages
Perfect integration with your design system
Exactly the features you need, nothing more

The Three-File Pattern

Every custom Sanity component in our setup requires three files:

Schema Definition (src/sanity/schemaTypes/objects/*.ts)
- Defines the data structure
- Field types, validation, preview
Renderer Component (src/components/PortableText*.astro)
- How it displays on the frontend
- Styling, layout, interactivity
Registry Updates
- src/sanity/schemaTypes/index.ts — Import and register schema
- src/sanity/schemaTypes/post.ts — Add to post body field
- src/components/PortableText.astro — Register renderer

Critical Implementation Notes

Must update post.ts body field:

defineField({
  name: 'body',
  type: 'array',
  of: [
    { type: 'block' },
    { type: 'image' },
    { type: 'containerColumns' },  // ADD HERE
    { type: 'newspaperColumns' },  // AND HERE
  ],
}),

This is easy to miss. The post schema defines its own body field inline, so you must explicitly add new component types there.

Sanity Studio deployment is separate:

# Frontend deploys automatically via GitHub Actions
git push origin main

# Studio must be deployed manually
npx sanity build
npx sanity deploy dist

The Studio is a separate React app hosted on Sanity’s infrastructure. Schema changes will not appear in production Studio until you deploy it.

Line Break Preservation

Text fields in Sanity preserve newlines, but they need special handling in HTML:

const formatText = (text: string) => {
  return text.replace(/\n/g, '<br>');
};

Then render with set:html:

<p set:html={formatText(leftText)} />

Combined with white-space: pre-wrap in CSS, this preserves the author’s intended formatting.

Lessons Learned

Complexity vs. Features

The initial thought was to support full Portable Text (rich text with nested blocks) in each column. That would have been significantly more complex — recursive rendering, nested component handling, edge cases galore.

Text-only was the right call. It covers most use cases and took a fraction of the development time.

Naming Is Design

“Two Column Layout” → Generic, unclear “Container Columns” → Describes the visual style “Newspaper Columns” → Instantly conveys the aesthetic

Good names make components discoverable and understandable in the Studio UI.

Start Simple, Add Features

Version 1: Just two text fields, 50/50 split Version 2: Add optional label Version 3: Create second variant (newspaper) Version 4: Add alignment options to newspaper columns

Each step was tested and working before moving to the next. Incremental development prevents half-finished features.

Use Cases

Container Columns (Boxed)

Translation comparisons that need emphasis
Code examples side-by-side
Before/after text
Formal comparisons (technical writing)

Newspaper Columns (Plain)

Poetry in multiple languages
Flowing parallel narratives
Subtle text comparisons
Academic citations with translations
RTL language support

Performance Considerations

These components are statically rendered at build time:

No client-side JavaScript
Pure HTML and CSS
Fast page loads
SEO-friendly

The only runtime work is CSS Grid layout, which is native and performant.

Future Enhancements

Potential additions (not implemented yet):

Font size controls per column
Column width ratio (60/40, 70/30)
Vertical divider toggle for newspaper columns
Background color picker for container columns
Rich text support (would be complex but powerful)

Conclusion

This project taught me something important about working with AI as a creative partner.

When I asked for “a two-column component,” I had a specific mental image. The AI gave me something different, and better, in its own way. Container Columns was not what I expected, but it solved use cases I had not considered. The boxed style gives emphasis and visual hierarchy that my simpler vision would have lacked.

Instead of discarding the AI’s interpretation and insisting on my original idea, we built both. This is the power of human–AI collaboration — it is not about the AI executing your exact specifications, it is about the AI providing perspectives and possibilities you would not have considered.

AI as Creative Augmentation

Working with an AI pair programmer does not mean:

The AI replaces your creativity
You fight to get exactly what you envisioned
You choose between your idea or the AI’s suggestion

It means:

The AI expands your catalogue of solutions
You get multiple perspectives on the same problem
You build more instead of choosing one
Creative friction becomes creative abundance

I started this session wanting to build one component. I ended with two, each serving different purposes, each valuable in its own context. That is not compromise — that is multiplication.

The Numbers

What I asked for: 1 component

What we built: 2 components

Total development time: ~2 hours

Lines of code: ~300

Dependencies added: 0

My perspectives: 1

Combined perspectives: 2

Problems solved: Many

Building custom Sanity components is not as daunting as it seems. With a clear understanding of the three-file pattern, careful incremental development, and a collaborative mindset with your AI pair programmer, you can create tailored solutions that not only fit your needs but expand beyond what you originally imagined.

Sometimes the best result is not getting exactly what you asked for — it is getting what you asked for plus something you did not know you needed.

Building a Chat Conversation Component for Sanity Studio (iMessage-Style Bubbles)

Sun, 22 Feb 2026 00:00:00 GMT

Ever wanted to embed a conversation or chat screenshot in your blog post, but pasting an image felt too static? What if you could recreate chat bubbles—complete with sender names, timestamps, and multiple visual styles—as structured content?

That’s what I built for my Astro + Sanity blog. And thanks to the documentation system I built, it only took 90 minutes from concept to production.

Here’s how it works, what design decisions went into it, and the complete implementation guide.

The Problem: Conversations Are Hard to Present

I wanted to share some ChatGPT conversations and WhatsApp exchanges in blog posts. My options were:

Screenshots - Static, not accessible, can’t copy text, breaks on different screen sizes
Blockquotes - Doesn’t convey the back-and-forth nature
Custom HTML - Works once, painful to reuse

What I really wanted:

Message bubbles that look like actual chat apps
Different colors for different speakers
Optional sender names and timestamps
Multiple visual styles (iMessage, WhatsApp, minimal)
Mobile-friendly and accessible
Easy to create in Sanity Studio (no code required per conversation)

The Solution: A Structured Chat Component

Here’s what the final component looks like in action:

┌─────────────────────────────────────────┐
│  Alice                                  │
│  ┌──────────────────────────────┐       │
│  │ Hey, did you finish the docs?│       │
│  │ 10:30 AM                     │       │
│  └──────────────────────────────┘       │
│                                         │
│                    ┌──────────────────┐ │
│                    │ Just pushed them!│ │
│                    │ 10:32 AM         │ │
│                    └──────────────────┘ │
│                                      Bob│
└─────────────────────────────────────────┘

Three visual styles:

Modern (iMessage-style): Blue bubbles on the right, gray on the left
Classic (WhatsApp-style): Green bubbles with borders
Minimal: No bubbles, just border lines and alignment

The Schema: Structured Conversation Data

First, I defined the Sanity schema in src/sanity/schemaTypes/objects/chatConversation.ts:

import { defineType } from 'sanity';

export default defineType({
  name: 'chatConversation',
  title: 'Chat Conversation',
  type: 'object',
  fields: [
    {
      name: 'messages',
      title: 'Messages',
      type: 'array',
      of: [
        {
          type: 'object',
          name: 'message',
          fields: [
            {
              name: 'text',
              title: 'Message Text',
              type: 'text',
              rows: 3,
              validation: (Rule) => Rule.required(),
            },
            {
              name: 'sender',
              title: 'Sender',
              type: 'string',
              description: 'Name of the sender (e.g., "User", "Assistant", "Alice")',
            },
            {
              name: 'side',
              title: 'Side',
              type: 'string',
              options: {
                list: [
                  { title: 'Left (Gray)', value: 'left' },
                  { title: 'Right (Blue)', value: 'right' },
                ],
              },
              initialValue: 'right',
            },
            {
              name: 'timestamp',
              title: 'Timestamp',
              type: 'string',
              description: 'Optional timestamp (e.g., "10:30 AM")',
            },
          ],
        },
      ],
      validation: (Rule) => Rule.min(1).required(),
    },
    {
      name: 'style',
      title: 'Chat Style',
      type: 'string',
      options: {
        list: [
          { title: 'Modern (Like iMessage)', value: 'modern' },
          { title: 'Classic (Like WhatsApp)', value: 'classic' },
          { title: 'Minimal', value: 'minimal' },
        ],
      },
      initialValue: 'modern',
    },
  ],
});

Design Decision: Why Three Styles?

Modern (iMessage):

Familiar to iOS users
High contrast with blue/gray
Clean, rounded bubbles

Classic (WhatsApp):

Green bubbles feel friendly
Border/shadow gives depth
Recognizable across platforms

Minimal:

Perfect for technical content
No visual clutter
Just colored border lines

This gives content creators flexibility depending on the tone of their post.

The Renderer: Astro Component with Dynamic Styling

Next, the Astro component (src/components/PortableTextChatConversation.astro):

---
const { node } = Astro.props;
const { messages, style = 'modern' } = node;
---

<div class={`chat-conversation chat-${style}`}>
  {messages.map((message: any) => {
    const { text, sender, side = 'right', timestamp } = message;

    return (
      <div class={`chat-message-wrapper ${side}`}>
        {sender && side === 'left' && (
          <div class="chat-sender-name">{sender}</div>
        )}
        <div class={`chat-bubble ${side}`}>
          <div class="chat-text">{text}</div>
          {timestamp && (
            <div class="chat-timestamp">{timestamp}</div>
          )}
        </div>
        {sender && side === 'right' && (
          <div class="chat-sender-name right">{sender}</div>
        )}
      </div>
    );
  })}
</div>

Key CSS Patterns

Modern Style (iMessage):

.chat-modern .chat-bubble.left {
  background: #e5e7eb;  /* Gray */
  color: #111827;
  border-bottom-left-radius: 4px;  /* Tail effect */
}

.chat-modern .chat-bubble.right {
  background: #3b82f6;  /* Blue */
  color: white;
  border-bottom-right-radius: 4px;
}

Classic Style (WhatsApp):

.chat-classic .chat-bubble.right {
  background: #dcf8c6;  /* Light green */
  color: #111827;
  border: 1px solid #c3e6a8;
}

Minimal Style:

.chat-minimal .chat-bubble.left {
  background: transparent;
  border-left: 3px solid #9ca3af;
  border-radius: 0;
}

The Mobile Experience

Chat bubbles need to work on phones. Here’s how:

@media (max-width: 768px) {
  .chat-bubble {
    max-width: 85%;  /* More screen space on mobile */
    padding: 0.65rem 0.85rem;
    font-size: 0.9rem;
  }
}

On desktop, bubbles max out at 75% width. On mobile, they expand to 85% to use the limited space better.

Dark Mode Support

Because people read blogs at night:

@media (prefers-color-scheme: dark) {
  .chat-conversation {
    background: #1f2937;  /* Dark container */
  }

  .chat-modern .chat-bubble.left {
    background: #374151;  /* Darker gray */
    color: #f3f4f6;
  }
}

The blue bubbles stay blue in dark mode—they already have good contrast.

Accessibility Considerations

Sender names above/below bubbles - Screen readers announce who’s speaking
Semantic HTML - Uses <div> with proper roles, not <ul> (conversations aren’t lists)
Color isn’t the only indicator - Side alignment also shows who’s speaking
Text is selectable - Users can copy conversation text

Using It in Sanity Studio

The editor experience is dead simple:

Click “Chat Conversation” in the body editor
Add messages one by one:
- Type the message text
- Choose “Left” or “Right”
- Optionally add sender name
- Optionally add timestamp
Select the chat style
Publish!

Preview in Studio:

Chat Conversation
2 messages

Each message shows a preview:

► User: Hey, did you finish the docs?

Real-World Example

Here’s how I used it to share a ChatGPT conversation:

Message 1 (Left):

Sender: “User”
Text: “How do I add custom components to Sanity?”
Timestamp: “2:30 PM”

Message 2 (Right):

Sender: “ChatGPT”
Text: “You’ll need to create a schema file, register it, and build a renderer component…”
Timestamp: “2:31 PM”

Message 3 (Left):

Sender: “User”
Text: “Wait, do I need to deploy twice?”

And so on. The result looks like an actual chat interface, but it’s structured data that’s:

Searchable
Accessible
Responsive
Copy-pasteable
Version-controlled

Performance Notes

Bundle Size:

No external dependencies
Pure CSS styling
~3KB compressed

Rendering:

Static HTML (built at compile time with Astro)
No JavaScript needed for display
No API calls

What I’d Do Differently

If I built this again, I’d add:

Avatar images - Small profile pics next to sender names
Typing indicator animation - For dramatic effect in tutorials
Read receipts - Blue checkmarks like WhatsApp
Reactions - Emoji reactions to messages
Group chat support - More than two participants

But for v1, the current feature set covers 90% of my use cases.

The 90-Minute Timeline

Thanks to my documentation system, here’s how the build broke down:

Schema design: 15 minutes
Basic renderer: 30 minutes
Three style variants: 25 minutes
Mobile/dark mode: 15 minutes
Testing & polish: 5 minutes

Total: 90 minutes from idea to production.

The guides eliminated all the “wait, how do I…” moments. I knew exactly:

Where to put the schema
How to structure the component
What the deployment steps were
Common pitfalls to avoid

Try It Yourself

Want to add this to your own Sanity + Astro blog?

Copy the schema from this post
Copy the Astro component
Register both following the Component Adding Guide
Deploy and enjoy!

Or customize it:

Change the bubble colors
Add your own style variant
Modify the border radius
Add animations

What Would You Build?

This chat component scratched my itch for displaying conversations. But the pattern works for tons of other use cases:

Email thread viewer (Gmail-style)
Comment sections (Reddit-style)
Code review threads (GitHub-style)
Twitter/X thread embeds (X-style)

What conversations do you want to display in your blog?

Full Code:

See it live:

peanutbutterandjelly.ai (check the latest posts)

Building custom Sanity components? Running into deployment gotchas? Let’s chat about it.

Self-Documenting Your Dev Workflow: How Writing Guides Made Me 3x Faster

Sun, 22 Feb 2026 00:00:00 GMT

There’s a moment in every developer’s journey when you finally realize: “I should have documented this the first time.”

Mine came after spending two hours debugging why my Sanity Studio components weren’t showing up in production—even though they worked perfectly on localhost. The problem? I had forgotten that my blog actually consists of two separate applications that need independent deployments.

This is the story of how writing documentation for “future me” accidentally made my development process 3x faster.

The Two-Site Confusion

My blog, peanutbutterandjelly.ai, is built with:

Astro for the static frontend (deployed to GitHub Pages)
Sanity Studio for content management (deployed to Sanity’s cloud)

When I added my first custom component (a table), I went through this painful cycle:

Write the schema
Create the Astro renderer
Test locally (works!)
Commit and push to GitHub
Component doesn’t appear in production Studio
Spend 30 minutes confused
Remember: “Oh right, I need to deploy the Studio separately!”
Run npx sanity deploy dist
Finally works

A week later, I added image sizing controls. Same exact confusion. Same 30-minute debugging session. Same forehead slap when I remembered the separate deployment.

The Breaking Point

After the third time making this mistake, I did what every developer should do more often: I stopped and wrote it down.

I created two documentation files:

1. How to Add Custom Components Guide

A step-by-step checklist for adding any custom component, including:

The critical post.ts file that everyone forgets
The difference between npx sanity dev and npx sanity start
Why you have to deploy twice (Astro + Studio)
Common pitfalls and debugging tips

2. Component Reference Library

A catalog of components we could build, complete with:

Schema examples
Use cases and complexity ratings
Implementation priorities
Copy-pasteable TypeScript code

The guides took me about 2 hours to write. I figured they’d save me maybe 30 minutes next time.

I was wildly wrong about the ROI.

The 3x Speed Multiplier

Fast forward one week. I decided to add three new components in one sitting:

Divider (visual separators between sections)
Accordion (collapsible FAQ sections)
Code Block (syntax-highlighted code with copy buttons)

Armed with my documentation, here’s what happened:

Without guides (previous attempts): ~3 hours per component

Schema: 20 min
Renderer: 40 min
Testing: 15 min
Debugging deployment issues: 90 min
Actually deploying correctly: 15 min

With guides (this time): ~20 minutes per component

Schema: 5 min (reference library had examples)
Renderer: 10 min (clearer patterns)
Testing: 3 min (knew what to look for)
Deployment: 2 min (checklist = no confusion)

Total time: 60 minutes for all three components. Time saved: ~8 hours.

But the speed wasn’t even the best part.

The Unexpected Benefits

1. Fearless Iteration

With a clear checklist, I wasn’t afraid to try complex components. The accordion has nested rich text content and JavaScript interactions—normally I’d save that for “later.” But with my guide, I knew exactly what steps to follow and could focus on the creative parts.

2. Better Code Quality

The documentation forced me to think about patterns. When I wrote “Step 5: Register the Renderer,” I realized I was registering components in slightly different ways each time. Documenting the process revealed the inconsistency.

3. AI Collaboration Gold

Here’s something I didn’t expect: the documentation became incredible context for working with AI coding assistants.

When I wanted to add the chat conversation component later, I just shared my guides with Claude. Instead of explaining the entire architecture, deployment process, and gotchas, I could say:

“Based on these two guides, let’s add a chat conversation component with message bubbles.”

The AI immediately understood:

It needed both a schema AND a renderer
The schema goes in src/sanity/schemaTypes/objects/
It must be added to post.ts (the critical file!)
Testing requires restarting Sanity Studio
Production requires a separate Studio deployment

We shipped the chat component—with three visual styles, sender names, timestamps, and full mobile responsiveness—in under 90 minutes. That would have taken me half a day without the guides.

The Documentation Architecture

Here’s what made these guides actually useful (unlike most documentation):

Checklist Format

□ Create schema file
□ Register in index.ts
□ Add to post.ts body field (CRITICAL!)
□ Create renderer component
□ Register in PortableText.astro
□ Restart Sanity Studio
□ Test in Studio
□ Test in Astro
□ Commit changes
□ Deploy Studio separately

No walls of text. Just: “Did you do this? Check. Next.”

The “Why” Explained Once

The guide has a whole section titled “Why Separate Deployment?” with ASCII diagrams showing the two-site architecture. I can reference it instead of re-learning it every time.

Real Code Examples

Every component type in the reference library has actual, copy-pasteable TypeScript. No “TODO: implement this” placeholders.

Troubleshooting Section

All my mistakes, documented:

“Component doesn’t appear in Studio” → Check post.ts
“Works locally but not in production” → Did you deploy the Studio?
“Schema loads but data doesn’t save” → Check validation rules

The ROI Calculation

Time invested in documentation: 2 hours
Time saved (so far): ~8 hours
Confidence gained: Immeasurable

But here’s the real ROI: Before the guides, I would avoid adding components because the process felt painful. Now I actively look for excuses to build new components because I know it’ll take less than an hour, not half a day.

Lessons for Your Own Projects

1. Document on the Second Time, Not the First

The first time you do something, you’re still learning. The second time, you know what actually matters. That’s when you should document.

2. Write for “3am Tired You”

Don’t write documentation for the smartest version of yourself. Write it for when you’re exhausted, distracted, or returning to the project after six months away.

3. Checklists > Prose

Dense paragraphs get skipped. Checklists get followed.

4. Make It Grep-able

Use specific error messages and keywords. When you Google “sanity component not appearing,” your own docs should show up.

5. Include the Deployment Architecture

This was my breakthrough. A simple diagram showing:

Sanity Studio (separate deploy)
      ↓
   Sanity API
      ↓
Astro Site (separate deploy)

Once I drew this, everything clicked.

What’s Next

These guides have become living documents. Every time I add a component, I update the reference library. Every time I hit a gotcha, I add it to the troubleshooting section.

Next up: I’m planning to add:

Video embed component (YouTube/Vimeo)
Callout boxes (warnings, tips, notes)
Two-column layouts for comparisons

And thanks to my documentation, each one should take about an hour instead of half a day.

Try It Yourself

If you’re building with a headless CMS (Sanity, Strapi, Contentful, etc.) or any two-part architecture, I challenge you to:

Document your deployment process (30 minutes)
Create a component checklist (30 minutes)
Build a reference library as you add components (10 minutes per component)

Then measure your speed on the 4th component vs. the 1st.

I bet you’ll see at least a 2x improvement.

Resources:

Full Component Adding Guide (on GitHub)
Component Reference Library (on GitHub)
peanutbutterandjelly.ai (the blog this is all for)

Want to see this in action? Next post, I’ll walk through building the chat conversation component—including the 3-style bubble system and why dark mode support matters.

Have you documented your deployment process? What was your “aha” moment that made you finally write it down?

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

Sat, 03 Jan 2026 00:00:00 GMT

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

I had two distinct applications:

Main documentation site: Built with Astro + Starlight, hosted at devportals.tech
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

I considered three approaches:

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`)

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`)

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.

Infrastructure Setup: DNS and Vercel Configuration

Setting Up the Subdomain in Vercel

The infrastructure setup was straightforward but required coordination between both Vercel projects:

Main site (devportals.tech): Already configured in Vercel project #1
Portfolio site: Deployed to Vercel project #2

In the portfolio project’s Vercel dashboard:

Navigate to Settings → Domains
Add portfolio.devportals.tech as a custom domain
Vercel provides DNS records to configure

DNS Configuration

In my DNS provider (where I registered devportals.tech), I added:

Type: CNAME
Name: portfolio
Value: cname.vercel-dns.com
TTL: Auto

This CNAME record directs portfolio.devportals.tech to Vercel’s infrastructure, which then routes to the correct project based on domain configuration.

Pro tip: DNS propagation can take up to 48 hours, but typically completes within an hour. Use dig portfolio.devportals.tech to verify the CNAME record has propagated.

With the infrastructure in place, the next challenge was making the portfolio accessible from the main site’s navigation. Users shouldn’t have to manually type in a subdomain—they should see a clear “Portfolio” link in the navigation bar.

Before diving into the Portfolio implementation, it’s worth noting that I was already using the starlight-blog plugin, which adds a “Blog” link to the navigation automatically. This plugin integrates seamlessly with Starlight’s architecture:

astro.config.mjs

plugins: [
  starlightBlog({
    metrics: {
      readingTime: true,
    },
  }),
],

The blog plugin has built-in permission to modify Starlight’s navigation—it hooks into Starlight’s plugin API and injects its navigation link without requiring any manual component overrides. This is the “blessed path” for extending Starlight: plugins can register navigation items, add routes, and modify behavior through official APIs.

But what if you need to add something custom that doesn’t have a plugin? That’s where component overrides come in. Unlike the blog plugin, my Portfolio site wasn’t integrated via a Starlight plugin—it’s a completely separate Next.js application. To add a Portfolio link, I needed to go beyond the plugin system and manually override the Header component.

This distinction highlights an important architectural concept: official plugins get convenient APIs, custom modifications require deeper integration.

Understanding Starlight’s Component Architecture

Starlight (the Astro documentation theme I’m using) has a modular component system. The header navigation is controlled by the Header.astro component, which orchestrates several subcomponents:

SiteTitle - Logo and site name
Search - Search functionality
SocialIcons - Social media links
ThemeSelect - Light/dark mode toggle
LanguageSelect - Language switcher

To add a custom “Portfolio” link, I needed to override the Header component.

Research Phase: Reading the Documentation

First, I consulted the Starlight overrides documentation. Key findings:

Component overrides are configured in astro.config.mjs via the components option
You can reuse built-in components while adding custom elements
The Header component doesn’t expose slots for injection—you must replace it entirely

I initially tried using a slot-based approach:

<!-- This didn't work - Header doesn't support slots -->
<Default {...Astro.props}>
  <div slot="before-social">
    <a href="https://portfolio.devportals.tech">Portfolio</a>
  </div>
</Default>

After testing without success, I checked the source code and confirmed: the Header component must be completely replaced.

Implementation: Creating a Custom Header Component

I created src/components/Header.astro with the full Header implementation:

---
import config from 'virtual:starlight/user-config';
import LanguageSelect from 'virtual:starlight/components/LanguageSelect';
import Search from 'virtual:starlight/components/Search';
import SiteTitle from 'virtual:starlight/components/SiteTitle';
import SocialIcons from 'virtual:starlight/components/SocialIcons';
import ThemeSelect from 'virtual:starlight/components/ThemeSelect';

const shouldRenderSearch =
  config.pagefind || config.components.Search !== '@astrojs/starlight/components/Search.astro';
---

<div class="header">
  <div class="title-wrapper sl-flex">
    <SiteTitle />
  </div>
  <div class="sl-flex print:hidden">
    {shouldRenderSearch && <Search />}
  </div>
  <div class="sl-hidden md:sl-flex print:hidden right-group">
    <div class="sl-flex social-icons">
      <SocialIcons />
    </div>
    <span class="divider"></span>
    <a href="https://portfolio.devportals.tech" target="_blank" rel="noopener noreferrer" class="portfolio-link">
      Portfolio
    </a>
    <ThemeSelect />
    <LanguageSelect />
  </div>
</div>

Key implementation details:

Import all necessary components from Starlight’s virtual modules
Preserve the search logic - check if Pagefind is enabled
Add the Portfolio link in the right-group section
Include a visual divider to separate sections
Maintain responsive behavior - hide on mobile with sl-hidden md:sl-flex

Styling the Portfolio Link

The styling needed to match Starlight’s design system:

<style>
  @layer starlight.core {
    .portfolio-link {
      color: var(--sl-color-text-accent);
      text-decoration: none;
      font-weight: 600;
      font-size: var(--sl-text-base);
    }
    .portfolio-link:hover {
      color: var(--sl-color-text-accent);
      text-decoration: underline;
    }
    .divider {
      height: 2rem;
      border-inline-end: 1px solid var(--sl-color-gray-5);
    }
    .social-icons {
      gap: 1rem;
      align-items: center;
    }
    /* ... rest of original Header styles ... */
  }
</style>

CSS considerations:

Use Starlight’s CSS custom properties (--sl-color-text-accent) for theme consistency
Wrap styles in @layer starlight.core to maintain specificity
Match the Blog link’s styling for visual consistency
Use var(--sl-text-base) for font size parity

Registering the Component Override

In astro.config.mjs, I registered the custom component:

export default defineConfig({
  integrations: [
    starlight({
      title: 'DevPortals.Tech',
      components: {
        Header: './src/components/Header.astro',
      },
      // ... rest of config
    }),
  ],
});

Troubleshooting Journey

Issue #1: Slot Approach Didn’t Work

Problem: Initial attempt to use slots resulted in no visible changes.

Investigation:

Checked browser dev tools - component wasn’t rendering
Reviewed Starlight docs - no mention of Header slots
Examined source code - confirmed Header doesn’t use slots

Solution: Complete component replacement instead of slot injection.

Issue #2: Double Dividers

Problem: Two vertical dividers appeared between social icons and Portfolio link.

Root cause: The original .social-icons::after pseudo-element was still creating a divider, and I added another <span class="divider">.

Solution: Removed the ::after pseudo-element CSS rule:

/* Removed this */
.social-icons::after {
  content: '';
  height: 2rem;
  border-inline-end: 1px solid var(--sl-color-gray-5);
}

/* Kept the standalone divider element */
.divider {
  height: 2rem;
  border-inline-end: 1px solid var(--sl-color-gray-5);
}

Issue #3: Cramped Layout

Problem: Portfolio link was initially placed inside the social-icons div, causing cramped spacing.

Solution: Moved the link outside the social icons container into the right-group parent, allowing proper flex gap spacing.

Testing and Validation

I validated the implementation across multiple dimensions:

Visual Testing

✅ Portfolio link displays on desktop viewports
✅ Link hides on mobile (uses mobile menu instead)
✅ Color matches Blog link and theme accent
✅ Spacing is consistent with other nav elements
✅ Single divider between sections

Functional Testing

✅ Link opens in new tab (target="_blank")
✅ Security attributes present (rel="noopener noreferrer")
✅ Hover state shows underline
✅ All original header functionality preserved (search, theme, language)

Responsive Testing

✅ Desktop: Full navigation visible
✅ Tablet: Portfolio link present
✅ Mobile: Falls back to Starlight’s mobile menu (portfolio link hidden)

Once I had the Header component override working for Portfolio, I realized there was a UX gap: users on the landing page had no clear way to navigate to the documentation sections without clicking on specific content cards. The site logo redirected to the landing page, but there was no “Docs” entry point in the navigation bar.

Since I’d already invested the effort to understand and override the Header component, adding another navigation link was straightforward—just another anchor element with the same styling:

<a href="/about/" class="nav-link">
  Docs
</a>
<a href="https://portfolio.devportals.tech" target="_blank" rel="noopener noreferrer" class="nav-link">
  Portfolio
</a>

The “Docs” link points to /about/, which serves as a natural entry point—introducing who I am and what the site covers before diving into technical content.

Navigation structure after enhancement:

Social icons
Divider
Docs (new!)
Portfolio (with external link indicator ↗)
Blog (from starlight-blog plugin)
Theme toggle
Language selector

This change demonstrates an important principle: once you understand a system deeply enough to extend it, additional enhancements become significantly easier. The initial investment in learning Starlight’s component architecture paid dividends when identifying and fixing a second UX issue.

Maintenance Considerations

Keeping Up with Starlight Updates

Challenge: This override copies Starlight’s internal Header implementation. When Starlight updates, the Header component might change.

Mitigation strategies:

Pin Starlight version in package.json to avoid unexpected breakages
Monitor releases: Watch Starlight’s changelog for Header changes
Test after updates: Run visual regression tests when upgrading Starlight
Consider upstreaming: If this pattern is useful, consider proposing Header slots to the Starlight project

Alternative Approach for the Future

If Starlight adds proper slot support to Header, this could be simplified to:

---
import Default from '@astrojs/starlight/components/Header.astro';
---

<Default {...Astro.props}>
  <a slot="before-theme" href="https://portfolio.devportals.tech">
    Portfolio
  </a>
</Default>

This would be more maintainable and less likely to break with updates.

Results and Lessons Learned

What Worked Well

Subdomain architecture: Clean separation, independent deployments, easy DNS setup
Component override pattern: Full control over layout and styling
Design system integration: Using Starlight’s CSS variables ensures consistency
Iterative debugging: Testing after each change helped isolate issues quickly

Key Takeaways for Documentation Engineers

Read the source code: When documentation is unclear, the source is the ultimate truth
Start simple, iterate: Begin with minimal implementation, add complexity incrementally
Respect the design system: Use framework-provided variables for maintainability
Document your overrides: This blog post itself is part of the solution—future me will thank current me
Understand plugin vs. override patterns: Plugins get blessed APIs, custom work requires deeper integration

Skills Demonstrated

This project showcases several skills critical for senior technical writers and documentation engineers:

Technical architecture: Understanding DNS, subdomains, and deployment strategies
Framework expertise: Deep dive into Astro, Starlight, and component systems
Plugin system understanding: Recognizing when to use plugins vs. manual overrides
Research methodology: Finding answers through docs, source code, and experimentation
Problem-solving: Systematic debugging and iterative refinement
Code implementation: Writing production-ready Astro components
Cross-framework integration: Connecting Next.js and Astro applications
Documentation: Creating a comprehensive guide for future reference

Conclusion

Integrating a Next.js portfolio site as a subdomain and adding it to Starlight’s navigation required a combination of infrastructure knowledge, component architecture understanding, and systematic troubleshooting. The subdomain approach provides deployment flexibility while maintaining brand cohesion, and the component override pattern—though more complex than ideal—gives complete control over the navigation experience.

For documentation engineers and technical writers building their own sites, this pattern demonstrates how to think architecturally about content delivery while maintaining the hands-on technical skills to implement custom solutions.

The complete code for this integration is available in my devportals-starlight repository on the feature-portfolio-label branch.

Want to see it in action? Visit devportals.tech and check out the Portfolio link in the navigation bar, or go directly to portfolio.devportals.tech.

Building a GitHub Contribution Graph with Next.js Server Components

Thu, 01 Jan 2026 00:00:00 GMT

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?

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.

The Technical Approach

1. Setting Up GitHub’s GraphQL API

GitHub’s GraphQL API is more efficient than the REST API for fetching contribution data. Here’s why:

Single Request: Get all the data you need in one query
Precise Fields: Request only what you need, reducing payload size
Strongly Typed: GraphQL schemas provide built-in documentation

First, create a Personal Access Token with read:user scope:

# Visit https://github.com/settings/tokens
# Generate a new token with read:user scope
# Store it in .env.local
GITHUB_TOKEN=ghp_your_token_here

2. TypeScript Types for Type Safety

One of the keys to maintainable code is proper typing. Here’s our contribution data structure:

interface ContributionDay {
  date: string;
  contributionCount: number;
  contributionLevel: 'NONE' | 'FIRST_QUARTILE' |
    'SECOND_QUARTILE' | 'THIRD_QUARTILE' | 'FOURTH_QUARTILE';
}

GitHub provides contribution levels in quartiles, which we’ll map to color intensities in our visualization.

3. The Fetch Function

Here’s the core function that talks to GitHub’s API:

export async function fetchGitHubContributions(
  username: string
): Promise<ContributionCalendar | null> {
  const query = `
    query($username: String!) {
      user(login: $username) {
        contributionsCollection {
          contributionCalendar {
            totalContributions
            weeks {
              contributionDays {
                date
                contributionCount
                contributionLevel
              }
            }
          }
        }
      }
    }
  `;

  const response = await fetch('https://api.github.com/graphql', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer \${process.env.GITHUB_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ query, variables: { username } }),
    // ISR: Cache for 1 hour
    next: { revalidate: 3600 },
  });

  // Error handling omitted for brevity
  const result = await response.json();
  return result.data.user.contributionsCollection.contributionCalendar;
}

The next: { revalidate: 3600 } option enables Incremental Static Regeneration (ISR), caching the data for one hour. This reduces API calls and improves performance.

4. Supporting Multiple Accounts

Many developers have separate personal and work GitHub accounts. Let’s aggregate them:

export async function aggregateContributions(
  usernames: string[]
): Promise<{ totalContributions: number; byAccount: Record<string, number> }> {
  const results = await Promise.allSettled(
    usernames.map(username => fetchGitHubContributions(username))
  );

  let totalContributions = 0;
  const byAccount: Record<string, number> = {};

  results.forEach((result, index) => {
    if (result.status === 'fulfilled' && result.value) {
      const count = result.value.totalContributions;
      byAccount[usernames[index]] = count;
      totalContributions += count;
    }
  });

  return { totalContributions, byAccount };
}

Using Promise.allSettled ensures that if one account fails, we still get data from the others.

5. The Visual Component

Now for the fun part—rendering the contribution calendar:

export default async function GitHubContributions({
  username,
  days = 90
}: GitHubContributionsProps) {
  const usernames = Array.isArray(username) ? username : [username];
  const aggregated = await aggregateContributions(usernames);
  const primaryCalendar = await fetchGitHubContributions(usernames[0]);

  const recentDays = getRecentContributions(primaryCalendar, days);
  const weeks = Math.ceil(recentDays.length / 7);

  return (
    <div className="grid gap-1" style={{
      gridTemplateColumns: `repeat(\${weeks}, minmax(10px, 1fr))`,
      gridTemplateRows: 'repeat(7, minmax(10px, 1fr))',
      gridAutoFlow: 'column',
    }}>
      {recentDays.map((day) => (
        <div
          key={day.date}
          className={`w-3 h-3 rounded-sm \${levelColors[day.contributionLevel]}`}
          title={`\${day.contributionCount} contributions`}
        />
      ))}
    </div>
  );
}

The CSS Grid layout automatically flows contributions from top to bottom, left to right, just like GitHub’s native visualization.

Performance Optimizations

Server-Side Rendering - Data fetched before the page reaches the client
ISR Caching - One-hour cache reduces API calls by 99%
Minimal JavaScript - Server Component means zero client-side JS for this feature
Optimized Query - GraphQL fetches only required fields

Dark Mode Support

Using Tailwind’s dark mode variants:

const levelColors = {
  NONE: 'bg-neutral-100 dark:bg-neutral-800',
  FIRST_QUARTILE: 'bg-green-200 dark:bg-green-900',
  // ... more levels
};

Error Handling

Always handle API failures gracefully:

if (!primaryCalendar) {
  return (
    <div className="p-4 border rounded-lg">
      <p className="text-sm text-neutral-600">
        Unable to load contribution data.
        Please check your GitHub token configuration.
      </p>
    </div>
  );
}

Lessons Learned

GraphQL > REST for Nested Data - One query beats multiple REST calls
Server Components Are Powerful - Keep secrets secure, improve performance
Type Safety Matters - TypeScript caught several bugs during development
Cache Strategically - ISR balances freshness with performance
Fail Gracefully - Always provide fallback UI for API errors

As a Documentation Engineer, building this feature taught me how developers actually use our API docs. The disconnect between reference documentation and real-world implementation patterns became clear, a lesson I’ll carry into future docs work. When you write the integration guide yourself, you discover which concepts need more explanation, which error messages are confusing, and where examples would save hours of debugging.

Future Enhancements

Some ideas for taking this further:

Interactive Tooltips - Show detailed contribution breakdown on hover
Commit Message Analysis - Display most-used technologies/keywords
Contribution Streaks - Highlight longest streak of consecutive days
Organization Contributions - Include work from private repos (with proper scoping)

Conclusion

This implementation demonstrates the power of Next.js Server Components for building interactive, data-driven portfolio features. By combining GitHub’s GraphQL API with TypeScript and modern React patterns, we’ve created a performant, maintainable solution that showcases both engineering and content skills.

Tech Stack: Next.js 14, TypeScript, Tailwind CSS, GitHub GraphQL API

Live Demo: View on my portfolio

Source Code: github.ts on GitHub

Why Redirect Management is Critical for Developer Portals

Thu, 18 Dec 2025 00:00:00 GMT

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.

Why URLs Break (and Why It Matters)

Content evolves. Files get renamed, directories get reorganized, documentation gets restructured. Every change risks breaking URLs that someone, somewhere, has bookmarked, shared, or embedded.

On this site, I recently merged two sparse sections—frameworks and tools—into a single frameworks-and-tools directory. Simple change, but any existing links to /frameworks/* would now return 404s. On a larger developer portal, these changes happen constantly: version branches, content restructures, product renamings.

The impact differs by scale:

Small sites: Broken bookmarks, lost SEO ranking
Developer portals: Broken Stack Overflow answers, tutorial videos with dead links, CI/CD scripts that can’t fetch docs
Any site: Lost trust when links don’t work

A broken documentation link isn’t just bad UX—it’s a broken promise.

Two Projects, Two Approaches

This Site: Simple Structural Change on Vercel

After consolidating my frameworks and tools sections, I needed one redirect rule in vercel.json:

{
  "redirects": [
    {
      "source": "/frameworks/:path*",
      "destination": "/frameworks-and-tools/:path*",
      "permanent": true
    }
  ]
}

That’s it. Vercel’s syntax is JSON-based, uses :path* for wildcards, and permanent: true for 301 redirects. Deploy and done.

Enterprise Developer Portal: Complex Version Management on Netlify

At work, the redirect needs are more complex. Managing multiple documentation versions requires wildcard patterns and catch-all rules in netlify.toml:

Version redirects:

[[redirects]]
from = "/docs/v2.12/*"
to = "/docs/current/:splat"
status = 302

Catch-all for SPA routing:

[[redirects]]
from = "/docs/api/v2.11/*"
to = "/docs/api/v2.11/:splat"
status = 200

Global fallback:

[[redirects]]
from = "/docs/api/*"
to = "/docs/api/current/:splat"

Netlify uses TOML configuration, :splat instead of :path*, and supports status 200 rewrites for single-page applications. The syntax differs, but the goal is the same: keep URLs working.

Platform Differences: Same Goal, Different Syntax

Here’s what I learned working across both platforms:

Vercel (JSON)

Configuration: vercel.json in repository root
Wildcard: :path* captures remaining path segments
Status codes: permanent: true (301) or permanent: false (302)
Best for: Simple redirects, modern frameworks, multiple wildcards per rule

Netlify (TOML)

Configuration: netlify.toml in repository root
Wildcard: :splat captures remaining path segments
Status codes: Explicit status = 301/302/200
Special feature: Status 200 rewrites (serve different content without changing URL)
Limitation: One wildcard per rule
Best for: Complex versioned docs, SPA routing with rewrites

The Common Patterns

Despite syntax differences, redirect strategies are universal:

Wildcard redirects - One rule handles entire directory trees
Permanent (301) vs Temporary (302) - Choose based on whether the change is forever
Catch-all patterns - Fallback rules prevent 404s
Order matters - Most platforms process rules sequentially, first match wins
Version control - Both platforms treat redirects as code, reviewed in pull requests

Practical Lessons from Both Projects

1. Redirects Are Infrastructure, Not Afterthoughts

For this site, I created the redirect rule in the same commit as the directory rename. At work, redirect configuration lives in version control alongside content—every pull request that changes URLs includes the corresponding redirect rules.

This treats redirects as first-class infrastructure:

project-repo/
├── src/content/
├── vercel.json     ← Vercel redirects
└── netlify.toml    ← Or Netlify redirects

2. Order Matters: Specific Before General

Redirect platforms process rules sequentially—first match wins. This is critical for catch-all patterns:

Wrong order (catch-all first):

# This will match everything, specific rules never trigger
[[redirects]]
from = "/docs/*"
to = "/docs/current/:splat"

[[redirects]]
from = "/docs/old-guide"
to = "/docs/new-guide"  # Never reached!

Correct order (specific first):

[[redirects]]
from = "/docs/old-guide"
to = "/docs/new-guide"  # Matches first

[[redirects]]
from = "/docs/*"
to = "/docs/current/:splat"  # Catches everything else

3. Choose the Right Status Code

301 (Permanent): I used this for my directory rename—it’s permanent
302 (Temporary): Better for version aliases that might change
200 (Rewrite): Netlify-specific, for SPA routing without changing browser URL

The status code tells search engines whether to update their indexes (301) or keep the original URL (302).

4. Test Before Production

Both Vercel and Netlify offer deploy previews—every PR gets a preview URL to test redirects before merging. Essential for catching issues early.

5. Documentation Helps Future You

When I implemented my redirect, I referenced our comprehensive technical guide. Six months from now, I won’t remember the syntax differences between :splat and :path*—but the documentation will still be there.

Choosing the Right Platform for Redirect Management

Different hosting platforms handle redirects differently. The platform I work with uses file-based configuration that lives in version control alongside the documentation source. This approach fits naturally into docs-as-code workflows:

Configuration as code: Redirect rules are reviewed in pull requests like any other change
Deploy preview testing: Test redirects before they reach production
No server management: Focus on documentation, not infrastructure maintenance
Readable syntax: Technical writers can understand and modify redirect rules

Other platforms offer different tradeoffs—more powerful regex capabilities, multiple wildcards per rule, or programmatic control through serverless functions. The “best” platform depends on your specific needs:

Simple docs-as-code workflow? File-based configuration platforms (Netlify, Vercel) work well
Complex pattern matching needs? Traditional servers (Apache/Nginx) offer full regex power
High-scale distributed systems? Cloud solutions (AWS CloudFront/Lambda@Edge) provide programmability

The key is choosing a platform that matches your team’s workflow and technical capabilities, not necessarily the most feature-rich option.

📚 Want the technical details? Check out our comprehensive Redirect Configuration Guide comparing syntax, features, and implementation across platforms.

What Good Redirects Enable

Whether managing a small portfolio site or a large developer portal, redirects provide the same benefits:

Restructure confidently - reorganize content without worrying about breaking bookmarks or SEO
Iterate faster - make improvements without coordinating with everyone who’s linked to your content
Maintain trust - users land on the right page, even from years-old links
Sustainable growth - sites can evolve without accumulating technical debt from fear of breaking URLs
True docs-as-code - content changes flow through Git with redirect rules reviewed like any other code

Key Takeaways for Developer Portal Teams

If you’re building or migrating a developer portal, treat redirects as critical infrastructure:

Plan redirects before restructuring - don’t wait until after migration
Version control your redirect config - redirects are code, not server config
Use wildcard patterns - one rule can handle hundreds of URLs
Implement catch-alls - ensure users never hit 404s
Test in preview environments - catch problems before production
Monitor redirect metrics - 404 rates, redirect hits, chains
Choose platforms that support docs-as-code - file-based config beats UI-based config
Document your redirect strategy - future team members will thank you

Final Thoughts

Redirect management isn’t glamorous work. It’s invisible when it works correctly—which is exactly the point. Users shouldn’t think about redirects. They should just land where they need to go, regardless of which old URL they clicked.

The platforms differ—Vercel’s JSON vs Netlify’s TOML, :path* vs :splat—but the principles are universal. Whether you’re redirecting one renamed directory or managing hundreds of versioned documentation pages, the strategy remains the same: keep URLs stable, handle changes gracefully, and treat redirects as infrastructure.

I just implemented my first redirect on this site. At work, I work with complex multi-version redirect strategies. Both serve the same fundamental purpose: keeping promises to users who depend on links working.

Building a developer portal or migrating documentation platforms? I’d love to hear about your redirect challenges and strategies. Connect with me on LinkedIn to continue the conversation.

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

Mon, 15 Dec 2025 00:00:00 GMT

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

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.

The Solution: Strategic Cherry-Picking

Rather than attempting to merge the entire bloated branch, I created a clean feature branch from main and selectively cherry-picked the commits that contained our team’s actual work. This surgical approach allowed us to:

Cherry-picked 30+ commits from the old feature branch, each representing a discrete piece of work
Resolved conflicts systematically as they appeared, one commit at a time, rather than facing a wall of conflicts
Fixed multiple build errors including toctree references, YAML indentation issues, and duplicate reference labels
Synced with 2 weeks of main branch updates to ensure our work integrated cleanly with the latest changes
Successfully merged into main with zero conflicts at the end, delivering the complete documentation revamp

GitHub Copilot’s terminal output showing the successful cherry-pick workflow recap.

The Senior Technical Writer’s Role

This experience highlighted several aspects of a Senior Technical Writer’s role that go beyond writing:

1. Technical Problem-Solving

Understanding git workflows deeply enough to propose and execute a cherry-picking strategy, rather than following the “obvious” merge path that would have failed.

2. Risk Management

Identifying when a situation requires a different approach and having the confidence to advocate for it, even when it means more upfront work.

3. Team Coordination

Managing a complex migration that affected multiple team members’ work while ensuring nothing was lost in the process.

4. Quality Assurance

Systematically addressing build errors, validating changes, and ensuring the final product met our standards before merging.

5. Persistence and Attention to Detail

Maintaining focus through dozens of commits, each requiring conflict resolution and validation, without losing sight of the ultimate goal.

Technical Learnings: Git Commands That Made the Difference

This project deepened my understanding of git beyond the basics. Here are the key commands and concepts I mastered:

Checking for Merge Conflicts Before Merging

git merge-tree $(git merge-base origin/main feature-branch) origin/main feature-branch | grep -E "^(<<<<<|=====|>>>>>)" | wc -l

This command simulates a merge without actually performing it, returning the count of conflict markers. Zero means you’re clear to merge!

Monitoring Branch Divergence

git fetch origin main && git merge-tree $(git merge-base HEAD origin/main) HEAD origin/main | grep -c "^changed in both" || echo "0"

This powerful one-liner fetches the latest main and checks how many files have conflicting changes between your branch and main—essential for planning your merge strategy.

Cherry-Picking Workflow

Starting the cherry-pick:

git cherry-pick <commit-hash>

When conflicts occur:

# Review conflicts, fix them manually, then:
git add <resolved-files>
git cherry-pick --continue

If you need to bail out:

git cherry-pick --abort

Handling empty commits (useful when a commit’s changes already exist in your branch):

git cherry-pick --allow-empty <commit-hash>
# Or during conflict resolution:
git commit --allow-empty

Examining Commits

Quick one-line view of recent commits:

git log --oneline -1

Detailed view of what changed in a specific commit:

git show --stat <commit-hash> 2>/dev/null | head -20

This shows file statistics (additions/deletions) without overwhelming you with full diffs.

Keeping Your Branch Up-to-Date

The three-step sync:

# 1. Fetch latest changes from remote
git fetch origin

# 2. Merge main into your feature branch
git merge origin/main

# 3. Push your updated branch
git push origin feature-branch

Machine-Readable Git Status

git status --porcelain

The --porcelain flag provides stable, script-friendly output with status codes:

M = modified
A = added
D = deleted
UU = both modified (conflict)
AA = both added (conflict)

Perfect for automation or quickly identifying conflict types.

AI as a Force Multiplier: GitHub Copilot in Action

One of the most significant factors in completing this project efficiently was my strategic use of GitHub Copilot as an AI pair-programming partner. Far from replacing the technical writer’s role, AI tools like Copilot enhanced my capabilities and accelerated problem-solving in ways that would have been impossible just a few years ago.

How GitHub Copilot Transformed the Workflow

1. Real-Time Error Diagnosis

When build errors appeared—and they appeared frequently—I could immediately share the error message with Copilot and get targeted suggestions. For example:

YAML indentation errors: Copilot identified that a .. tabs:: directive needed exactly 5 spaces of indentation to match sibling tabs, not the 4 I had initially used.
reStructuredText syntax issues: When I encountered “Unexpected indentation” errors, Copilot explained that content: | blocks in YAML require a blank line after the pipe character when followed by reStructuredText directives.
Duplicate reference labels: Copilot quickly located duplicate .. _reference: labels across files and suggested the appropriate fix.

2. Git Command Expertise On-Demand

Rather than constantly searching Stack Overflow or git documentation, I could ask Copilot:

“How do I simulate a merge to check for conflicts?”
“What does git status --porcelain do?”
“How do I handle empty commits during cherry-picking?”

The responses were contextual, accurate, and saved hours of research time.

3. Pattern Recognition Across Files

When I discovered one YAML formatting error, Copilot helped me identify similar issues in related files. Instead of fixing errors reactively as the build system found them, I could proactively search for and fix patterns.

For example, Copilot suggested searching for similar patterns:

grep -r "content: | " --include="*.yaml" documentation/source/includes/

4. Batch Operations and Automation

Copilot helped me construct complex one-liners that would have taken significant time to craft manually, like the branch divergence checker or the conflict counter. These commands became part of my toolkit for future projects.

Technical Writers Are Not Disadvantaged by AI—We’re Empowered

There’s a common misconception that AI tools will diminish the role of technical writers. My experience proves the opposite:

AI handles the tedious, writers handle the critical:

Copilot helped me syntax-check YAML and identify file patterns
I made the strategic decisions about which commits to cherry-pick, how to resolve conflicts, and what the documentation structure should be

AI accelerates learning, writers apply knowledge:

Copilot explained git commands and their options
I chose which commands to use, when to use them, and understood their implications for the team

AI suggests, writers validate:

Copilot proposed fixes for indentation and formatting errors
I reviewed each suggestion, tested the builds, and ensured the fixes were correct in context

AI answers questions, writers ask the right questions:

Knowing what to ask Copilot required deep understanding of the problem space
Interpreting and applying Copilot’s responses required expertise in documentation systems, build tools, and git workflows

The Augmented Technical Writer

The future of technical writing isn’t about competing with AI—it’s about leveraging AI as a powerful tool in our arsenal. Just as we adopted spell-checkers, version control, and static site generators, AI coding assistants are the next evolution in our toolkit.

Technical writers who embrace AI tools like GitHub Copilot will:

Solve problems faster by having instant access to technical expertise
Learn continuously through interactive exploration of commands and tools
Focus on higher-value work by offloading syntax checking and pattern matching
Deliver better results through the combination of AI efficiency and human judgment

The key is understanding that AI doesn’t replace the technical writer’s expertise—it amplifies it. My knowledge of documentation systems, content strategy, and user needs guided every decision. Copilot was my assistant, not my replacement.

Lessons Learned

1. Regular Integration Prevents Drift

Feature branches that live for months accumulate technical debt. Regular merges from main keep conflicts manageable and prevent the kind of crisis we faced.

2. Cherry-Picking Is Not Always Harder

While cherry-picking individual commits seems more tedious than a single merge, it provides granular control that can actually save time when dealing with heavily diverged branches.

3. Build Validation Is Critical

After every few cherry-picks, running a build and fixing errors immediately is far more efficient than waiting until the end and facing dozens of cascading issues.

4. Documentation of Process Matters

Keeping notes on which commits were cherry-picked, which conflicts were resolved, and what decisions were made creates an invaluable audit trail.

5. AI Tools Are Essential, Not Optional

Using AI assistants like GitHub Copilot transformed a potentially week-long ordeal into a manageable, two-day project. Technical writers who resist these tools will find themselves at a significant disadvantage.

6. Human Expertise Remains Irreplaceable

AI provided suggestions and information, but every critical decision—which commits to include, how to resolve conflicts, when to merge—required human judgment and domain expertise.

Conclusion

This exercise transformed a potential disaster—months of work trapped in an unmergeable branch—into a successful delivery. More importantly, it reinforced that Senior Technical Writers must be technologists first, capable of solving complex technical problems to unblock their teams.

The git commands I learned aren’t just theoretical knowledge—they’re practical tools that will serve me in future projects. The experience of systematically working through 30+ commits, resolving conflicts, fixing build errors, and ultimately delivering clean, integrated documentation has made me a more effective technical writer and a more valuable team member.

And perhaps most importantly, this project demonstrated that AI tools like GitHub Copilot don’t diminish the technical writer’s role—they elevate it. By handling the mechanical aspects of syntax, pattern matching, and information retrieval, AI frees us to focus on what humans do best: strategic thinking, creative problem-solving, and making judgment calls that require deep domain expertise.

To my fellow technical writers: embrace the technical challenges. Learn the tools deeply. Don’t shy away from complex git workflows or build systems. And absolutely use AI assistants—they’re not your competition, they’re your superpower. These skills and tools make us more than writers—they make us technical leaders who can guide our teams through any challenge.

Have you faced similar challenges with long-lived feature branches? How are you incorporating AI tools into your technical writing workflow? Share your experiences in the comments below.

From Forks to Branches: Streamlining Team Git Workflows

Mon, 01 Dec 2025 00:00:00 GMT

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

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.

Fork-Based Workflow: Pros and Cons

Pros

Permission isolation: Contributors don’t need write access to the main repository
Safety net: Mistakes in personal forks don’t affect the main repo
Open-source standard: Familiar pattern for external contributors
Experimentation space: Break things without consequences

Cons

Cognitive overhead: Managing two remotes (origin for fork, upstream for main repo)
Complex tracking: Feature branches track upstream/main, not origin/main
Push/pull confusion: Easy to push to wrong remote
Sync maintenance: Keeping forks updated requires extra steps
Limited benefit: For trusted team members with write access, forks add complexity without security gains

Centralized Branching: Pros and Cons

Pros

Simpler mental model: One remote (origin), straightforward push/pull
Consistent workflow: All team members follow identical patterns
Reduced friction: Create branch, push, open PR—done
Better visibility: All work visible in main repository
Easier collaboration: Team members can push to each other’s branches
Natural for internal teams: Aligns with typical corporate git usage

Cons

Requires repository access: All contributors need write permissions
Branch proliferation: Main repo contains everyone’s feature branches
Less isolation: No fork-level separation between contributors
Not suitable for open-source: External contributors can’t use this model

The Migration Process

Transitioning from forks to branches required careful planning to avoid disrupting in-flight work. Here’s the approach we took:

1. Timing Considerations

Existing pull requests from forks remain unaffected on GitHub
PR merges happen server-side, independent of local configuration
Safe to reconfigure during active PR reviews

2. Repository Reconfiguration

Preserve fork as backup:

git remote rename origin fork

Promote main repository to primary remote:

git remote rename upstream origin

Update branch tracking:

git branch —set-upstream-to=origin/main main

3. New Workflow

Start new work:

git checkout main git pull origin main git checkout -b TICKET-123-feature

Push with tracking:

git push -u origin TICKET-123-feature

Open PR: same repo, branch → main

Key Insights from the Working Group

Context matters: Forks excel for open-source projects with external contributors. Internal teams with repository access benefit from simpler branching models.
Change management: Clear communication about the transition reduced confusion. We provided documentation and supported team members through the migration.
Tooling adaptation: Some team members had scripts and tools configured for fork workflows. We identified these dependencies early and provided migration guidance.
No one-size-fits-all: Different teams have different needs. Our analysis showed that for our use case—a private repository with trusted contributors—the fork overhead wasn’t justified.

Results

Post-migration, our team experienced:

Reduced onboarding time for new technical writers
Fewer git-related questions in team channels
More consistent practices across sub-teams
Faster PR workflows without fork sync issues

Conclusion

The fork versus branch decision isn’t about which approach is objectively better—it’s about matching your workflow to your team structure and needs. For our internal documentation team with repository write access, moving to a centralized branching model eliminated unnecessary complexity while maintaining code review quality and collaboration practices.

As technical writers increasingly manage documentation as code, understanding git workflow trade-offs becomes essential. This migration taught me that technical leadership means not just documenting tools, but critically evaluating whether those tools serve your team’s actual needs.

Have you transitioned between fork and branch workflows? I’d love to hear about your experience. Connect with me on LinkedIn to continue the conversation.

How I'm Using MDX Frontmatter to Scale devportals.tech

Wed, 24 Sep 2025 00:00:00 GMT

Building devportals.tech has been an exercise in practicing what I preach about documentation engineering. One of the most impactful decisions I made early was leveraging MDX frontmatter not just for basic metadata, but as the foundation for scalable content workflows. Here’s how it’s working in practice.

Starting Simple, Scaling Smart

When I first set up this Astro Starlight site, I could have just used basic Markdown. But knowing I wanted to build something that demonstrates professional documentation practices, I started with structured frontmatter from day one:

---
title: "Content Branching Strategy for Documentation Teams"
description: "How to manage documentation releases, staging, and quality control using Git workflows"
date: 2025-09-23
authors:
  - name: Joaquin Romo
tags:
  - git-workflow
  - content-management
  - documentation-strategy
  - staging
---

Simple, but it’s already paying dividends.

The Content Strategy That’s Emerging

As I’ve added more content to the site, patterns are emerging that I never planned but are incredibly valuable:

Tagging for Discovery

My tags are becoming a taxonomy that helps visitors (and me) understand the content landscape:

content-strategy for high-level planning topics
git-workflow for technical implementation details
documentation-strategy for process and methodology
astro-starlight for platform-specific insights

The Starlight Blog plugin automatically generates tag pages, so this creates navigation paths I didn’t have to manually build.

Authors for Accountability

Even as the only author right now, having structured author metadata sets me up for:

Future collaboration - The schema is ready when I invite guest writers
Professional presentation - It shows I think about authorship professionally
Content attribution - If I repurpose content elsewhere, attribution is baked in

Dates for Content Lifecycle

Every piece has a clear publication date, and I’m starting to add lastUpdated fields for major revisions. This helps me:

Track content freshness - I can see what might need updates
Show visitors currency - Recent dates build confidence
Plan maintenance - I can query for older content that needs review

Real Workflow Benefits

Branch-Based Content Development

The structured metadata makes my Git workflow much more manageable. When I’m working on new content in feature branches, I can easily see:

What’s ready to publish (clean frontmatter)
What needs more work (missing descriptions, placeholder content)
How content fits into the overall site structure

Quality Control Through Structure

Having consistent frontmatter forces me to think about each piece:

What’s the actual value proposition? (title and description)
Who benefits from reading this? (tags and implicit audience)
How does this fit the larger narrative? (category and relationships)

It’s like having a checklist that ensures I’m not just writing, but creating strategic content.

The Technical Implementation

I’m using Astro’s content collections with a schema that validates my frontmatter:

const blogSchema = z.object({
  title: z.string(),
  description: z.string(),
  date: z.date(),
  authors: z.array(z.object({
    name: z.string()
  })),
  tags: z.array(z.string())
});

This catches mistakes early and ensures consistency. When I tried to publish a post with malformed dates or missing descriptions, the build failed with clear error messages.

What’s Next

As devportals.tech grows, I’m planning to leverage this metadata foundation for:

Automated Content Analysis

I want to build scripts that analyze my content patterns:

Which topics get the most tags (showing my focus areas)
Content gaps where I have few posts
Author productivity metrics (just for fun as a solo creator)

Better Discovery Features

The structured data opens possibilities for:

“Related content” sections based on tag similarity
Topic clustering for themed reading paths
Content recommendations based on visitor interests

Rich metadata makes automated social media posts more meaningful. Instead of generic “new post” notifications, I can generate contextual descriptions that highlight the specific value each piece provides.

The Bigger Picture

What I’m really doing is treating my personal documentation site like a product. The frontmatter discipline forces me to:

Think strategically about each piece of content
Build systems that scale beyond manual management
Demonstrate professionalism in how I approach documentation

For anyone building their own documentation site, I’d recommend starting with structured frontmatter even if you’re not sure how you’ll use it all. The discipline of thinking about metadata makes you a better content creator, and the flexibility enables capabilities you haven’t thought of yet.

The question isn’t whether you need metadata - it’s whether you want to build something that can grow intelligently or just accumulate content randomly.

Have you found creative ways to use frontmatter in your own documentation projects? I’d love to hear about approaches that have worked well for you.

Content Branching Strategy for Documentation Sites

Wed, 17 Sep 2025 00:00:00 GMT

When building a professional documentation site like DevPortals.tech, maintaining content quality while enabling rapid development requires a strategic approach to version control. Here’s the branching strategy I’ve implemented for managing documentation content lifecycle.

The Challenge

Building a portfolio-quality documentation site presents unique challenges:

Quality vs. Speed: You want to publish frequently but maintain professional standards
Work-in-Progress Content: Some sections need extensive research and iteration
Professional Presentation: Your live site represents your expertise to potential employers
Development Flexibility: You need space to experiment without affecting production

The Solution: Feature Branches for Content Sections

Instead of treating all documentation as a single unit, I organize content development around feature branches that correspond to major site sections.

Current Branch Structure

main                 # Production-ready content only
├── docs-markup      # Individual markup language deep-dives
├── docs-frameworks  # Next.js vs Docusaurus detailed guides
├── docs-migration   # Advanced migration case studies
├── docs-ai-tools    # AI integration strategies
├── docs-resources   # Curated tools and resources
└── docs-templates   # Template library development

Real-World Example: Markup Languages Section

Here’s how I recently implemented this strategy:

Problem

I had created overview content for markup languages (Markdown, MDX, reStructuredText, AsciiDoc) but the individual deep-dive pages weren’t production-ready. I needed to:

Keep the excellent overview page live
Remove incomplete individual pages from production
Maintain development access to work on detailed content

Solution

# 1. Create feature branch
git checkout -b docs-markup

# 2. Move non-production files to staging
mkdir docs-markup-staging
mv src/content/docs/markup/{asciidoc,markdown,mdx,restructuredtext}.mdx docs-markup-staging/

# 3. Commit to feature branch
git add . && git commit -m "Move non-production markup files to staging"

# 4. Clean up main branch
git checkout main
rm src/content/docs/markup/{asciidoc,markdown,mdx,restructuredtext}.mdx
git add . && git commit -m "Keep only overview page in production"

Development Workflow

When I want to work on the markup content:

# Switch to development branch
git checkout docs-markup

# Copy staging files for preview
cp docs-markup-staging/* src/content/docs/markup/

# Start development server
npm run dev

# Edit content with full preview capability
# Save changes back to staging when done
cp src/content/docs/markup/* docs-markup-staging/

# Commit progress
git add . && git commit -m "Improve markdown deep-dive content"

Benefits of This Approach

Quality Control

Production site stays clean: No placeholder or incomplete content
Professional presentation: Every live page meets publication standards
Confidence in sharing: Safe to include site URL in job applications

Development Flexibility

Experimental freedom: Try different approaches without consequences
Local preview capability: See changes before committing
Iterative improvement: Refine content over multiple sessions

Portfolio Value

Demonstrates workflow proficiency: Shows understanding of professional development practices
Version control expertise: Reflects enterprise-level Git knowledge
Content lifecycle management: Critical skill for platform roles

Quick Branch Workflow Cheatsheet

Creating a New Content Section

# Create and switch to feature branch
git checkout -b docs-[section-name]

# Develop content
# ... create and edit files ...

# Commit progress
git add . && git commit -m "Add [section] content framework"

# Push feature branch (optional, for backup)
git push origin docs-[section-name]

Working on Existing Feature Branch

# Switch to feature branch
git checkout docs-[section-name]

# Copy staging content for preview (if applicable)
cp docs-[section]-staging/* src/content/docs/[section]/

# Start development
npm run dev

# Edit content...

# Save changes back to staging
cp src/content/docs/[section]/* docs-[section]-staging/

# Commit changes
git add . && git commit -m "Update [section] content"

Publishing to Production

# Ensure you're on main
git checkout main

# Merge feature branch
git merge docs-[section-name]

# Push to production
git push origin main  # → Triggers deployment to live site

# Clean up (optional)
git branch -d docs-[section-name]

Emergency Fixes

# For quick fixes to live content
git checkout main
# ... make changes ...
git add . && git commit -m "Fix typo in migration guide"
git push origin main

When to Use This Strategy

Good Fit

Professional portfolio sites: Where quality matters more than speed
Technical documentation: Content requiring research and iteration
Multi-author projects: Where review cycles are important
Long-form content: Guides, tutorials, comprehensive references

Consider Alternatives

Simple blogs: Where immediate publishing is preferred
News sites: Where timeliness trumps perfection
Internal documentation: Where informal content is acceptable

Implementation Tips

Branch Naming Convention

Use descriptive prefixes that match your content structure:

docs- for documentation sections
feature- for new site functionality
fix- for bug fixes
content- for major content restructuring

Staging Directory Strategy

For content that needs extensive development:

mkdir docs-[section]-staging
# Move incomplete files here
# Copy back for preview as needed

Automation Opportunities

Consider shell scripts or aliases for common workflows:

# ~/.bashrc or ~/.zshrc
alias docs-preview="cp docs-*-staging/* src/content/docs/*/; npm run dev"
alias docs-save="cp src/content/docs/*/* docs-*-staging/"

Conclusion

This branching strategy transforms documentation development from a chaotic process into a professional workflow. It enables rapid iteration while maintaining production quality, demonstrates version control proficiency, and provides the confidence to share your work at any stage.

The key insight: treat your documentation site like enterprise software, with proper development, staging, and production environments. This approach not only improves your content quality but also showcases the systematic thinking that platform teams value.

This strategy has transformed how I approach documentation development, enabling both quality control and development velocity. How do you manage content lifecycle in your documentation projects?

Starlight Sidebar Configuration Strategies: Manual vs Autogenerate

Wed, 17 Sep 2025 00:00:00 GMT

While building DevPortals.tech, I ran into a common documentation site challenge: how do you organize sidebar navigation when you want some content to appear in a specific order (like overview pages) while still automatically including new files as you create them?

This is the kind of practical problem that comes up constantly when building documentation sites, and the solution isn’t always obvious from the docs.

The Problem

I had a “Markup Languages” section with several files:

overview.mdx (should appear first)
asciidoc.mdx
markdown.mdx
mdx.mdx
restructuredtext.mdx

Using Starlight’s autogenerate feature, the sidebar was ordering files alphabetically, putting “overview” in the 4th position instead of first. Not ideal for user experience.

Strategy 1: Manual Items Array

The most straightforward approach is to manually specify all sidebar items:

astro.config.mjs

{
  label: 'Markup Languages',
  items: [
    { label: 'Overview', link: '/markup/overview/' },
    { label: 'AsciiDoc', link: '/markup/asciidoc/' },
    { label: 'Markdown', link: '/markup/markdown/' },
    { label: 'MDX', link: '/markup/mdx/' },
    { label: 'reStructuredText', link: '/markup/restructuredtext/' },
  ],
}

Pros:

Complete control over order and labels
Can customize link text independently of file names
Clear and explicit configuration

Cons:

Manual maintenance required for new files
Easy to forget updating sidebar when adding content
More verbose configuration

Best for: Sections with stable content that rarely changes, or when you need custom labels.

Strategy 2: Filename Prefix for Ordering

Force alphabetical ordering by prefixing your overview file:

# Rename the file
mv src/content/docs/markup/overview.mdx src/content/docs/markup/00-overview.mdx

Then use autogenerate normally:

{
  label: 'Markup Languages',
  autogenerate: { directory: 'markup' },
}

Set the display title in frontmatter:

---
title: Overview  # This shows in sidebar, not the filename
description: ...
---

Pros:

Maintains autogenerate benefits
Guaranteed ordering for important files
Simple implementation

Cons:

Ugly filenames with prefixes
Not semantically clean
Prefix strategy needs to be documented for team

Best for: Sections where you want mostly automatic management but need to pin a few key files.

Strategy 3: Index File Convention

Rename your overview to follow index file conventions:

mv src/content/docs/markup/overview.mdx src/content/docs/markup/index.mdx

Pros:

Semantic file naming
Works with autogenerate in Starlight
Follows web conventions (index files appear first)
Clean, professional approach

Cons:

Only works for one “special” file per directory
Less obvious what the file contains from filename alone

Best for: Sections where you have a clear introduction/overview page and the rest can be auto-managed.

Strategy 4: Mixed Manual + Autogenerate (Theoretical)

This would be ideal but isn’t currently supported by Starlight:

// This doesn't work in Starlight (yet)
{
  label: 'Markup Languages',
  items: [
    { label: 'Overview', link: '/markup/overview/' },
    {
      label: 'Languages',
      autogenerate: {
        directory: 'markup',
        exclude: ['overview.mdx']
      },
    },
  ],
}

Why it would be great:

Best of both worlds
Explicit control for key pages
Automatic inclusion of new content

Reality: Starlight doesn’t support exclude in autogenerate, so this approach isn’t available.

My Recommendation

After testing all approaches, here’s my decision framework:

For Overview/Landing Pages

Use the index.mdx convention (Strategy 3). It’s semantic, clean, and works perfectly with autogenerate. This is what I implemented for the markup section.

For Stable Sections

Use manual items arrays (Strategy 1) when you have a well-defined set of content that rarely changes and you want custom labels.

For Growing Sections

Use filename prefixes (Strategy 2) when you’re actively adding content but need some ordering control. Accept the ugly filenames as a temporary trade-off.

For Pure Auto-Management

Use straight autogenerate when alphabetical ordering is acceptable and you prioritize ease of maintenance.

Real-World Impact

This might seem like a small detail, but navigation organization directly impacts:

User experience: Can readers find what they need?
Content discoverability: Do overview pages get seen?
Maintenance overhead: How much work is adding new content?
Team adoption: Will other writers follow your patterns?

In my case, the index.mdx approach solved the immediate problem while keeping the configuration clean and maintainable.

Looking Forward

Documentation tooling continues to evolve. I’d love to see Starlight add:

exclude patterns for autogenerate
Custom sorting functions
Mixed manual/auto approaches
Priority/weight-based ordering

Until then, these strategies provide good workarounds for common navigation challenges.

This post documents a real configuration challenge from building DevPortals.tech. What sidebar organization strategies have worked for your documentation sites?

From reST to MDX: Why Documentation Frameworks Are Evolving

Sun, 10 Aug 2025 00:00:00 GMT

Documentation frameworks are not just technical choices — they reflect cultural shifts in how we think about developer experience.

For years, reStructuredText (reST) powered serious technical documentation, especially in the Python and scientific communities.
Today, Markdown and MDX dominate modern developer portals. Why? Let’s explore this shift.

The Legacy of reStructuredText (reST)

Origins:

Created for the Python ecosystem.
Strict, extensible, and great for generating reference documentation.
Closely tied to tools like Sphinx and ReadTheDocs.

Strengths:

Rigid grammar and semantic markup → consistency across docs.
Mature auto-documentation pipelines (e.g., autodoc with Sphinx).
Widely used in academic and scientific projects.

Challenges:

Verbose and harder to learn.
Contributions from non-experts can be intimidating.
Limited support for modern interactive or component-driven docs.

Markdown and the Rise of Docs-as-Code

Why Markdown won:

Lightweight, readable, and easy to learn.
GitHub popularized it as the default for READMEs.
Perfect fit for docs-as-code workflows (PRs, reviews, version control).

Tradeoffs:

Less expressive than reST.
Needed extensions (like frontmatter, tables, or fenced code blocks) to catch up.

MDX: Markdown Meets React

What it is:
MDX lets you write Markdown, but embed JSX (React components) directly into your docs.

Why it matters for dev portals:

Live code samples and sandboxes.
Reusable UI components inside content.
Docs can behave more like apps than static manuals.

In the wild:

Docusaurus (Meta’s framework).
Next.js with MDX plugins.
Astro Starlight (content-first with React/Vue/Svelte integrations).

Cultural Shifts in Documentation

Role Evolution: Technical writers → Documentation engineers.
Docs Evolution: Static reference → Dynamic experience.
Collaboration Evolution: Gatekeeping → Community contribution.

MD/MDX directly supports these cultural shifts by making docs easier to contribute to and more engaging for developers.

Why reST Still Matters

Despite the momentum of MD/MDX, reST continues to thrive in:

Python projects like Django, NumPy, and SciPy.
Scientific communities that value its rigor.
Legacy pipelines built around Sphinx extensions.

For many orgs, rewriting entire docsets is costly, so reST will persist in specialized contexts.

Looking Forward

Momentum: MD/MDX frameworks are the present and future of dev portals.
Niche longevity: reST will survive in Python and academia.
Your takeaway: Framework choice isn’t only about syntax. It’s about workflows, interactivity, and alignment with developer expectations.

Conclusion

reST gave us rigor.
Markdown gave us accessibility.
MDX gives us interactivity.

This evolution mirrors the shift in developer portals themselves:
From manuals → to platforms → to experiences.

If you’re building a modern developer portal, understanding this history helps you make smarter choices today.

Building DevPortals.tech: From Idea to Live Site

Sun, 20 Jul 2025 00:00:00 GMT

As a senior technical writer who’s spent years managing enterprise documentation platforms, I’ve seen the pain points that drive teams to migrate from proprietary solutions to open-source alternatives.

This site chronicles that journey and provides practical guidance for teams making similar transitions.

Why Astro Starlight?

After evaluating multiple documentation frameworks, Starlight stood out for several reasons:

Performance: Static site generation with minimal JavaScript
Developer Experience: Excellent TypeScript support and hot reload
Flexibility: Easy to extend and customize
Modern: Built for the current web ecosystem

What’s Next?

I’m building additional demos in Next.js and Docusaurus to provide comprehensive framework comparisons for teams evaluating their options.

Stay tuned for more practical migration strategies and platform evaluations!

DevPortals.Tech | Blog

Building Custom Column Components for Text Comparisons

What I Asked For vs. What I Got

Building Two Instead of One

Container Columns: The Creative Interpretation

Schema Definition

The Renderer Component

The Evolution: Newspaper Columns

Naming Matters

The Second Component

Adding Text Alignment

The Decision: Independent Alignment

Technical Implementation Details

Why Custom Components?

The Three-File Pattern

Critical Implementation Notes

Line Break Preservation

Lessons Learned

Complexity vs. Features

Naming Is Design

Start Simple, Add Features

Use Cases

Container Columns (Boxed)

Newspaper Columns (Plain)

Performance Considerations

Future Enhancements

Conclusion

AI as Creative Augmentation

The Numbers

Related Documentation

Building a Chat Conversation Component for Sanity Studio (iMessage-Style Bubbles)

The Problem: Conversations Are Hard to Present

The Solution: A Structured Chat Component

The Schema: Structured Conversation Data

Design Decision: Why Three Styles?

The Renderer: Astro Component with Dynamic Styling

Key CSS Patterns

The Mobile Experience

Dark Mode Support

Accessibility Considerations

Using It in Sanity Studio

Real-World Example

Performance Notes

What I’d Do Differently

The 90-Minute Timeline

Try It Yourself

What Would You Build?

Self-Documenting Your Dev Workflow: How Writing Guides Made Me 3x Faster

The Two-Site Confusion

The Breaking Point

1. How to Add Custom Components Guide

2. Component Reference Library

The 3x Speed Multiplier

The Unexpected Benefits

1. Fearless Iteration

2. Better Code Quality

3. AI Collaboration Gold

The Documentation Architecture

Checklist Format

The “Why” Explained Once

Real Code Examples

Troubleshooting Section

The ROI Calculation

Lessons for Your Own Projects

1. Document on the Second Time, Not the First

2. Write for “3am Tired You”

3. Checklists > Prose

4. Make It Grep-able

5. Include the Deployment Architecture

What’s Next

Try It Yourself

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

Introduction

The Challenge: Two Sites, One Domain

Architecture Decision: Subdomain vs. Subdirectory

Option 1: Separate Domain

Option 2: Subdirectory (devportals.tech/portfolio)

Option 3: Subdomain (portfolio.devportals.tech)

Infrastructure Setup: DNS and Vercel Configuration

Setting Up the Subdomain in Vercel

Option 2: Subdirectory (`devportals.tech/portfolio`)

Option 3: Subdomain (`portfolio.devportals.tech`)