How to Write Blog Posts Using Markdown: A Complete Guide

Writing blog posts doesn’t have to be complicated. With Markdown, you can create beautifully formatted content without knowing HTML. This guide focuses on standard Markdown (if you’re curious about MDX, check out our article on MDX vs Markdown differences). Here’s your complete guide to writing blog posts using Markdown syntax.

Basic Text Formatting

Headers

Use # symbols for headers. More # means smaller headers:

# Main Title (H1)
## Section Title (H2)
### Subsection (H3)

Text Styling

• Bold: Use **double asterisks** or __double underscores__
• Italic: Use *single asterisks* or _single underscores_
• Strikethrough: Use ~~double tildes~~

Lists

For bullet points, use -, *, or +:

- First item
- Second item
  - Sub-item (indent with 2 spaces)
  - Another sub-item

For numbered lists:

1. First step
2. Second step
3. Third step

Adding Links

Regular Links

Format: [Link Text](URL)

Example:

Check out [June Web Design](https://www.junewebdesign.com)

External Links (Opening in New Tab)

Format: <a href="URL" target="_blank" rel="noopener noreferrer">Link Text</a>

Example:

Visit our <a href="https://www.junewebdesign.com" target="_blank" rel="noopener noreferrer">website</a>

Working with Images

Best Practices for Images

1. Use descriptive filenames (e.g., business-meeting.jpg instead of IMG001.jpg)
2. Keep image sizes under 200KB for optimal loading
3. Use WebP format when possible
4. Include descriptive alt text

Adding Images

Format: ![Alt Text](/assets/images/your-image.webp)

Example:

![Team meeting discussion](/assets/images/team-meeting.webp)

Embedding YouTube Videos

To embed a YouTube video, follow these steps:

1. Go to your YouTube video
2. Click “Share”
3. Click “Embed”
4. Copy the iframe code
5. Paste it into your markdown file

Example:

<iframe width="560" height="315" 
  src="https://www.youtube.com/embed/VIDEO_ID" 
  title="YouTube video player" 
  frameborder="0" 
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" 
  referrerpolicy="strict-origin-when-cross-origin"
  allowfullscreen>
</iframe>

Replace VIDEO_ID with your actual YouTube video ID (found in the video’s URL after v=).

Quotes and Code Blocks

Blockquotes

Use > for quotes:

> This is a blockquote. It's great for highlighting important points or testimonials.

Code Blocks

For inline code, use single backticks: `code`

For code blocks, use triple backticks:

```javascript
console.log("Hello World!");
```

Best Practices for Blog Writing

1. Use Headers Wisely

   • Break content into logical sections
   • Don’t skip header levels (e.g., don’t go from H2 to H4)

2. Keep Paragraphs Short

   • Aim for 2-3 sentences per paragraph
   • Use line breaks to improve readability

3. Optimize Images

   • Compress images before uploading
   • Always include alt text
   • Use meaningful file names

4. Link Responsibly

   • Use descriptive link text (avoid “click here”)
   • Add target="_blank" for external links
   • Include rel="noopener noreferrer" for security

5. Format for Readability

   • Use lists for easy scanning
   • Include white space between sections
   • Break up long text with images or quotes

Common Mistakes to Avoid

1. Don’t skip alt text for images
2. Don’t forget to optimize images
3. Don’t use excessive formatting (bold, italic, etc.)
4. Don’t forget to use rel="noopener noreferrer" for external links

Need Help?

If you’re ever stuck or need assistance with your blog posts, don’t hesitate to reach out. We’re here to help you create content that looks great and engages your readers effectively.

Remember, the goal is to communicate clearly with your readers. Markdown is just a tool to help you format your message effectively. Focus on your content first, and let Markdown handle the styling.