Skip to content
DevPortals.Tech
Docs Portfolio
Blog

Blog

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

- 4 min read
Joaquin Romo

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

Section titled “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.

Content Branching Strategy for Documentation Sites

- 3 min read
Joaquin Romo

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

Section titled “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

Starlight Sidebar Configuration Strategies: Manual vs Autogenerate

- 4 min read
Joaquin Romo

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.

From reST to MDX: Why Documentation Frameworks Are Evolving

- 3 min read
Joaquin Romo

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.

Building DevPortals.tech: From Idea to Live Site

- 1 min read
Joaquin Romo

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.