Back to Help Center
Customization

Blog Guide

Blog System Guide

This guide covers creating, editing, and managing blog posts in your SaaS application.

Overview

The blog system uses MDX (Markdown + JSX), which lets you write content in Markdown while embedding React components. Blog posts are stored as .mdx files in the /content/blog/ directory.

Quick Start: Creating a New Blog Post

Step 1: Create a New File

Create a new file in /content/blog/ with the .mdx extension:

content/
  blog/
    my-new-post.mdx    <-- Create this file
    getting-started.mdx
    why-choose-us.mdx

Important: The filename becomes the URL slug. For example:

  • my-new-post.mdx → yoursite.com/blog/my-new-post
  • how-to-get-started.mdx → yoursite.com/blog/how-to-get-started

Step 2: Add Frontmatter

Every blog post starts with frontmatter (metadata between --- lines):

---
title: "Your Blog Post Title"
description: "A brief description that appears in previews and SEO"
date: "2025-01-15"
author:
  name: "Your Name"
  avatar: "/images/authors/your-avatar.jpg"  # Optional
tags: ["tutorial", "guide"]
image: "/images/blog/featured-image.jpg"  # Optional cover image
published: true
---

Your content starts here...

Step 3: Write Your Content

After the frontmatter, write your content in Markdown:

---
title: "10 Tips for SaaS Success"
description: "Learn the top strategies for building a successful SaaS business."
date: "2025-01-15"
author:
  name: "Jane Smith"
tags: ["business", "tips", "saas"]
published: true
---

Building a successful SaaS business requires strategy, patience, and the right tools.

## Tip 1: Focus on Customer Problems

Start by identifying real problems your customers face...

## Tip 2: Keep It Simple

Don't over-engineer your solution. Start with the core features...

Frontmatter Reference

| Field | Required | Type | Description | |-------|----------|------|-------------| | title | Yes | String | The post title (appears on page and in listings) | | description | Yes | String | Short description for SEO and previews (150-160 chars ideal) | | date | Yes | String | Publication date in YYYY-MM-DD format | | author.name | Yes | String | Author's display name | | author.avatar | No | String | Path to author's avatar image | | tags | No | Array | List of tags for categorization | | image | No | String | Featured/cover image path | | published | No | Boolean | Set to false to hide the post (default: true) |

Markdown Formatting Guide

Headings

# Heading 1 (Don't use - reserved for title)
## Heading 2
### Heading 3
#### Heading 4

Text Formatting

**Bold text**
*Italic text*
~~Strikethrough~~
`inline code`
[Link text](https://example.com)

Lists

Unordered list:
- Item one
- Item two
  - Nested item
  - Another nested

Numbered list:
1. First step
2. Second step
3. Third step

Code Blocks

Inline code: `const x = 1`

Code block with syntax highlighting:
```javascript
function greet(name) {
  console.log(`Hello, ${name}!`);
}
```

Supported languages: javascript, typescript, python, bash, json, html, css, sql, and more.

Images

![Alt text](/images/blog/my-image.jpg)

With caption (using HTML):
<figure>
  <img src="/images/blog/my-image.jpg" alt="Description" />
  <figcaption>Image caption here</figcaption>
</figure>

Where to put images:

  1. Add images to /public/images/blog/
  2. Reference them as /images/blog/filename.jpg

Blockquotes

> This is a quote from someone important.
> It can span multiple lines.

Tables

| Feature | Free | Pro | Enterprise |
|---------|------|-----|------------|
| Projects | 3 | Unlimited | Unlimited |
| Storage | 1GB | 10GB | Unlimited |
| Support | Community | Priority | Dedicated |

Horizontal Rule

Content above

---

Content below

Complete Example: Full Blog Post

Here's a complete example of a well-structured blog post:

---
title: "How to Launch Your SaaS in 30 Days"
description: "A step-by-step guide to taking your SaaS idea from concept to launch in just one month."
date: "2025-01-20"
author:
  name: "Alex Johnson"
  avatar: "/images/authors/alex.jpg"
tags: ["launch", "startup", "guide"]
image: "/images/blog/launch-guide.jpg"
published: true
---

Launching a SaaS product doesn't have to take years. With the right approach and tools, you can go from idea to launch in 30 days.

## Week 1: Validation and Planning

Before writing any code, validate your idea with potential customers.

### Talk to Potential Users

Schedule calls with at least 10 potential users. Ask them:

1. What's your biggest challenge with [problem area]?
2. How are you currently solving this?
3. What would your ideal solution look like?

> "The best products are built on real customer insights, not assumptions." - Eric Ries

### Define Your MVP

List the absolute minimum features needed:

| Priority | Feature | Time Estimate |
|----------|---------|---------------|
| Must have | User authentication | 2 days |
| Must have | Core functionality | 5 days |
| Nice to have | Analytics dashboard | 3 days |

## Week 2: Building the Core

With a clear plan, start building.

### Set Up Your Stack

We recommend starting with a proven stack:

```bash
# Clone the boilerplate
git clone https://github.com/example/saas-boilerplate
cd saas-boilerplate
npm install

Focus on One Thing

Don't try to build everything at once. Focus on the one feature that delivers the most value.

MVP Diagram

Week 3: Polish and Test

Now refine what you've built.

Test with Real Users

Invite 5-10 beta users to try your product. Watch them use it and take notes on:

  • Where do they get confused?
  • What features do they ask about?
  • What would make them pay for this?

Week 4: Launch!

You're ready to launch. Here's your checklist:

  • [ ] Landing page is live
  • [ ] Payment integration tested
  • [ ] Transactional emails working
  • [ ] Error monitoring set up
  • [ ] Launch announcement drafted

Launch Day Tips

  1. Announce on Product Hunt - Submit the night before
  2. Email your waitlist - Personal notes work best
  3. Share on social media - LinkedIn, Twitter, relevant communities

Conclusion

Launching in 30 days is ambitious but achievable. The key is staying focused on what matters: solving a real problem for real users.

Ready to start? Get the boilerplate and begin building today.


## Managing Blog Posts

### Editing an Existing Post

1. Open the `.mdx` file in `/content/blog/`
2. Make your changes
3. Save the file
4. Changes appear immediately in development (hot reload)
5. Deploy to see changes in production

### Hiding a Post (Draft Mode)

To hide a post without deleting it, set `published: false`:

```mdx
---
title: "My Draft Post"
published: false   # This post won't appear in listings
---

Deleting a Post

Simply delete the .mdx file from /content/blog/.

Scheduling Posts

To schedule a post for the future:

  1. Set published: true
  2. Set a future date
  3. The post will appear with the future date

Note: The post will be visible immediately. For true scheduling, set published: false until you're ready.

SEO Best Practices

Title (50-60 characters)

title: "How to Launch Your SaaS in 30 Days"  # 39 chars - Good!

Description (150-160 characters)

description: "A step-by-step guide to taking your SaaS idea from concept to launch in just one month. Includes templates and checklists."

URL Slugs

  • Use lowercase letters, numbers, and hyphens
  • Keep it short but descriptive
  • Include primary keyword
Good:  launch-saas-30-days.mdx
Bad:   how-to-launch-your-saas-in-30-days-complete-guide.mdx

Images

  • Always include alt text
  • Compress images before uploading (use tinypng.com or similar)
  • Use descriptive filenames: saas-launch-checklist.png not image1.png

Adding Images to Blog Posts

Step 1: Add Image Files

Place your images in the /public/images/blog/ directory:

public/
  images/
    blog/
      my-post-hero.jpg
      my-post-diagram.png

Step 2: Reference in Your Post

![Launch checklist diagram](/images/blog/my-post-diagram.png)

Image Size Recommendations

| Image Type | Recommended Size | Max File Size | |------------|------------------|---------------| | Cover/Hero | 1200 x 630 px | 200KB | | In-content | 800 x 600 px | 150KB | | Thumbnail | 400 x 300 px | 50KB |

Troubleshooting

Post not appearing in blog listing

  1. Check that published: true is set
  2. Verify the file extension is .mdx (not .md)
  3. Check for YAML syntax errors in frontmatter
  4. Ensure the file is in /content/blog/ (not a subdirectory)

Formatting looks wrong

  1. Check for missing blank lines before/after code blocks
  2. Verify Markdown syntax
  3. Check for special characters that need escaping

Images not loading

  1. Verify image is in /public/images/blog/
  2. Check the path starts with /images/blog/ (not public/images/blog/)
  3. Check filename matches exactly (case-sensitive)
  4. Ensure image file isn't corrupted

Date showing incorrectly

Use the format YYYY-MM-DD:

date: "2025-01-15"   # Correct
date: "01/15/2025"   # Wrong
date: "January 15, 2025"  # Wrong

Blog File Locations Summary

| What | Where | |------|-------| | Blog posts | /content/blog/*.mdx | | Blog images | /public/images/blog/ | | Author avatars | /public/images/authors/ | | Blog listing page | /app/blog/page.tsx | | Blog post page | /app/blog/[slug]/page.tsx | | Blog components | /components/blog/ | | MDX utilities | /lib/mdx.ts |