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:
- Use
.mdx
file extension - Filename should be kebab-case (e.g.,
my-blog-post.mdx
) - 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 postdate
: Publication date in "YYYY-MM-DD" formatdescription
: A brief summary (150-200 characters)coverImage
: Path to the cover image (store inpublic/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) 
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
- Create your MDX file in
content/blog/
- Add required frontmatter
- Write your content using Markdown/MDX
- Add cover image to
public/blog/
- Preview locally using
npm run dev
- Commit and push to deploy
Best Practices
-
Images
- Optimize images before adding
- Use descriptive alt text
- Store in
public/blog/
-
Content Structure
- Start with an introduction
- Use clear headings
- Include code examples when relevant
- End with a conclusion or call-to-action
-
Formatting
- Use proper heading hierarchy
- Keep paragraphs concise
- Include code comments in examples
- Use lists for better readability
Testing Your Post
Before publishing:
- Run the development server
- Check all links work
- Verify images load correctly
- Test responsive layout
- Validate code examples
- Check category and tag links
Troubleshooting
Common issues and solutions:
-
Images not loading
- Verify path is correct
- Check file exists in public directory
- Ensure proper file permissions
-
MDX syntax errors
- Check component imports
- Verify frontmatter format
- Escape special characters
-
Category/Tags not working
- Use existing categories
- Check tag formatting
- Verify frontmatter syntax
Need Help?
If you encounter any issues or need clarification:
- Check existing blog posts for examples
- Review the project documentation
- Open an issue on GitHub
Remember to follow the established style guide and maintain consistency with existing content. Happy blogging!