Journey Mapper Blog Contribution Guide

By Journey Mapper Team • March 31, 2025 • 4 min read
documentation developer guide
Journey Mapper Blog Contribution Guide

Journey Mapper Blog Contribution Guide

This guide explains the blog system architecture and how to create new articles for the Journey Mapper blog.

Blog System Architecture

The Journey Mapper blog uses a hybrid approach with:

  1. Article Metadata Registry: blog/src/content/config.ts contains the content collection config
  2. Content Files: MDX files in blog/src/content/blog/ contain the actual article content
  3. Image Assets: Webp images stored in public/blog/images/

This architecture allows for optimized loading, caching, and SEO benefits while maintaining a clean separation between content and presentation.

How to Add a New Blog Post

Step 1: Create the MDX Content File

First, create a new .mdx file in the public/blog/content/ directory with your article’s slug as the filename:

public/blog/content/your-article-slug.mdx

Each MDX file must include frontmatter at the top with the following format:

---
title: "Your Article Title"
customSlug: "your-article-slug"
date: "YYYY-MM-DD"
author: "Your Name"
authorPosition: "Your Position"
authorImage: "/images/authors/your-photo.jpg"
coverImage: "/blog/images/your-cover-image.webp"
excerpt: "A compelling 1-2 sentence summary of your article (150-160 characters)"
tags: ["relevant-tag", "another-tag"]
---

Your article content in Markdown format starts here...

Step 2: Register the Article in the Registry

Ensure your article’s frontmatter contains all necessary metadata. The blog system will automatically process this through the Astro content collections API.

// Your MDX frontmatter contains all necessary metadata
---
title: "Your Article Title"
customSlug: "your-article-slug"
date: "YYYY-MM-DD"
author: "Your Name"
authorPosition: "Your Position"
authorImage: "/images/authors/your-photo.jpg"
coverImage: "/blog/images/your-cover-image.webp"
excerpt: "A compelling 1-2 sentence summary of your article (150-160 characters)"
tags: ["relevant-tag", "another-tag"]
---

Step 3: Prepare Your Images

  1. Create image assets as .webp files for optimal loading performance
  2. Save all images to the public/blog/images/ directory
  3. Use a naming convention that includes your article slug for organization
  4. Ensure your cover image is 1200×630px for optimal social sharing
  5. In-article images should be properly sized and optimized

Reference images in your MDX using the pattern:

![Descriptive alt text](/blog/images/your-image-name.webp)

Step 4: Article Writing Guidelines

  • Headings: Use hierarchical structure (H2 for main sections, H3 for subsections)
  • Images: Include descriptive alt text for accessibility
  • Formatting: Use bold for emphasis, code blocks for code samples
  • Links: Use relative paths for internal links, full URLs for external links
  • SEO: Include primary keyword in first paragraph, use naturally throughout

Frontmatter Processing

The blog system uses frontmatter (the section between --- marks at the top of MDX files) for article metadata. Here’s how it works:

  1. Content Schema: The frontmatter in your MDX file must conform to the schema defined in blog/src/content/config.ts
  2. Frontmatter Stripping: The system automatically strips frontmatter before rendering content
  3. Required Fields: All fields in the frontmatter example above are required
  4. Syntax: Be careful with quotes and formatting in the frontmatter section

If you see raw frontmatter displayed in your article, it might indicate an issue with the frontmatter processor. Common issues include:

  • Missing closing --- delimiter
  • Incorrect indentation or formatting within the frontmatter
  • Special characters in frontmatter values that aren’t properly escaped

Image Placeholders and Development Flow

During development, you can create placeholder images with:

touch public/blog/images/your-image-name.webp

This creates empty files that will be replaced with actual images later.

Testing Your Article

  1. Start the development server: npm run dev
  2. Visit http://localhost:5173/blog to see your article in the listing
  3. Click your article to view the full content
  4. Test all images and links to ensure they work properly

Common Issues and Troubleshooting

  • Article not appearing: Check that the slug in the MDX frontmatter is correct
  • Images not loading: Verify path is /blog/images/ not /images/blog/
  • Formatting issues: Ensure your MDX syntax is correct
  • Broken links: Check relative paths are correct
  • Frontmatter visible: Ensure your frontmatter has proper opening and closing --- delimiters

SEO Best Practices

  • Title: 50-60 characters with primary keyword
  • Excerpt: 150-160 characters with primary and secondary keywords
  • URL: Use kebab-case, include primary keyword
  • Images: Always include descriptive alt text

Example Article Structure

---
title: "How to Optimize Your Customer Journey Map"
customSlug: "optimize-customer-journey-map"
date: "2025-04-15"
author: "Jane Smith"
authorPosition: "Customer Experience Lead"
authorImage: "/images/authors/jane-smith.jpg"
coverImage: "/blog/images/optimize-journey-cover.webp"
excerpt: "Learn proven strategies to enhance your customer journey maps for better user experience and business outcomes."
tags: ["optimization", "customer-experience", "journey-mapping"]
---

## Introduction

Start with a compelling hook and overview of what readers will learn...

## Main Section One

Content with key points, examples, and supporting image:

![Journey optimization dashboard example](/blog/images/optimization-dashboard.webp)

## Main Section Two

More valuable content with practical advice...

## Conclusion

Summarize key takeaways and include a call to action.