Documentation

How to Create Blog Posts in Next.js Portfolio

·3 min read
How to Create Blog Posts in Next.js Portfolio

Creating Blog Posts in Next.js Portfolio

This guide will walk you through the process of creating and publishing blog posts in this Next.js portfolio site. We'll cover everything from file structure to MDX features.

File Structure and Naming

All blog posts are stored in the content/blog directory and must follow these conventions:

  1. Use .mdx file extension
  2. Filename should be kebab-case (e.g., my-blog-post.mdx)
  3. Filename should be descriptive and URL-friendly

Frontmatter Structure

Every blog post requires a frontmatter section at the top of the file:

---
title: "Your Blog Post Title"
date: "YYYY-MM-DD"
description: "A concise description of your post (used for SEO and previews)"
coverImage: "/blog/your-image.jpg"
category: "One of the predefined categories"
tags: ["Tag1", "Tag2", "Tag3"]
---

Required Fields:

  • title: The main title of your blog post
  • date: Publication date in "YYYY-MM-DD" format
  • description: A brief summary (150-200 characters)
  • coverImage: Path to the cover image (store in public/blog/)
  • category: Main category (Development, Documentation, etc.)
  • tags: Array of relevant tags

Content Writing

Markdown Features

The blog supports standard markdown syntax plus MDX features:

# H1 Heading

## H2 Heading

### H3 Heading

- Bullet points
- Support nested
  - Like this

1. Numbered lists
2. Are supported

**Bold text** and _italic text_

[Links](https://example.com)

![Images](/path/to/image.jpg)

Code Blocks

Code blocks support syntax highlighting:

function example() {
  return "Hello, World!";
}

MDX Components

You can import and use React components:

import { CustomComponent } from '@/components/custom';

<CustomComponent prop="value" />

SEO Optimization

The blog automatically handles SEO through:

  • Meta descriptions from your frontmatter
  • Open Graph images from your cover image
  • Proper heading hierarchy
  • Structured data for blog posts

Publishing Process

  1. Create your MDX file in content/blog/
  2. Add required frontmatter
  3. Write your content using Markdown/MDX
  4. Add cover image to public/blog/
  5. Preview locally using npm run dev
  6. Commit and push to deploy

Best Practices

  1. Images

    • Optimize images before adding
    • Use descriptive alt text
    • Store in public/blog/
  2. Content Structure

    • Start with an introduction
    • Use clear headings
    • Include code examples when relevant
    • End with a conclusion or call-to-action
  3. Formatting

    • Use proper heading hierarchy
    • Keep paragraphs concise
    • Include code comments in examples
    • Use lists for better readability

Testing Your Post

Before publishing:

  1. Run the development server
  2. Check all links work
  3. Verify images load correctly
  4. Test responsive layout
  5. Validate code examples
  6. Check category and tag links

Troubleshooting

Common issues and solutions:

  1. Images not loading

    • Verify path is correct
    • Check file exists in public directory
    • Ensure proper file permissions
  2. MDX syntax errors

    • Check component imports
    • Verify frontmatter format
    • Escape special characters
  3. Category/Tags not working

    • Use existing categories
    • Check tag formatting
    • Verify frontmatter syntax

Need Help?

If you encounter any issues or need clarification:

  1. Check existing blog posts for examples
  2. Review the project documentation
  3. Open an issue on GitHub

Remember to follow the established style guide and maintain consistency with existing content. Happy blogging!