workflow

2 posts with the tag “workflow”

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

Sep 24, 2025

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

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

Sep 17, 2025

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

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?