---
title: 'Writing Your First Blog Post'
description: 'Learn how to create and publish blog posts using MDX, including examples of all the content types you can include: images, videos, code blocks, and more.'
pubDate: 'Dec 15 2024'
heroImage: '../../assets/PENCIL_1.3.1_wipe.avif'
featured: false
category: 'Tutorial'
tags: ['Guide', 'MDX', 'Writing', 'Tutorial']
---

## Getting Started with MDX

MDX combines the simplicity of Markdown with the power of React components. This means you can write naturally in Markdown while embedding interactive elements when needed.

## Frontmatter

Every blog post starts with frontmatter - the YAML metadata at the top of the file:

```yaml
---
title: 'Your Post Title'
description: 'A brief description for SEO and previews'
pubDate: 'Dec 27 2024'
heroImage: '../../assets/your-image.avif'
featured: false
category: 'Tutorial'
tags: ['Tag1', 'Tag2', 'Tag3']
---
```

### Required Fields
- `title`: The post title (shown in browser tab, social shares, etc.)
- `description`: SEO description and preview text
- `pubDate`: Publication date (used for sorting)

### Optional Fields
- `heroImage`: Header image (relative path from `src/assets/` or absolute from `public/`)
- `featured`: Set to `true` to feature this post on the blog index
- `category`: Primary category for organization
- `tags`: Array of tags for discovery and related posts
- `updatedDate`: If you revise the post significantly

## Text Formatting

Standard Markdown formatting works as expected:

**Bold text** using `**bold**`
*Italic text* using `*italic*`
~~Strikethrough~~ using `~~strikethrough~~`

### Headings

Use `##` for main sections (h2), `###` for subsections (h3), and so on. The table of contents is automatically generated from your headings.

## Links and References

Create links using `[link text](URL)` syntax:
- [Internal page links](/contact)
- [External links](https://astro.build)
- [Link to another post](/blog/sample-case-study)

## Lists

### Unordered Lists
- First item
- Second item
  - Nested item
  - Another nested item
- Third item

### Ordered Lists
1. Step one
2. Step two
3. Step three

### Checklists
- [x] Completed task
- [ ] Pending task
- [ ] Another pending task

## Code Blocks

Inline code uses single backticks: `const example = true`

Multi-line code blocks use triple backticks with language specification:

```javascript
// JavaScript example
function greet(name) {
  console.log(`Hello, ${name}!`);
}

greet("World");
```

```css
/* CSS example */
.example {
  color: var(--color-primary);
  font-size: 1.125rem;
  transition: all 0.3s ease;
}
```

```bash
# Shell commands
pnpm dev
pnpm build
pnpm deploy
```

## Blockquotes

Use `>` for blockquotes:

> "This is a blockquote. Great for highlighting important points, testimonials, or notable quotes."

> Multi-line blockquotes work too.
> Just prefix each line with `>`.

## Images

Reference images from `src/assets/` (processed by Astro) or `public/` (served as-is):

```markdown
![Alt text](../../assets/your-image.avif)
![Alt text](/media/your-image.jpg)
```

Images in `src/assets/` get automatically optimized. Use the AVIF conversion utility for best results:

```bash
pnpm convert:avif:all
```

## Videos

Embed videos using HTML video tags:

```html
<video controls width="100%">
  <source src="/media/your-video.mp4" type="video/mp4" />
  Your browser does not support the video tag.
</video>
```

<video controls width="100%">
  <source src="/media/placeholder-video.mp4" type="video/mp4" />
  Your browser does not support the video tag.
</video>

## Tables

Create tables using pipe syntax:

| Feature | Supported | Notes |
|---------|-----------|-------|
| MDX | ✓ | Full support |
| Images | ✓ | AVIF recommended |
| Videos | ✓ | MP4/WebM |
| Components | ✓ | React components |

## Horizontal Rules

Create section dividers with three dashes:

---

Like that!

## Tips for Great Posts

1. **Use descriptive headings** - They create the table of contents
2. **Add hero images** - Visual appeal matters
3. **Tag appropriately** - Helps with discovery and related posts
4. **Write good descriptions** - They're used for SEO and previews
5. **Use code examples** - Share knowledge and demonstrate expertise
6. **Break up long sections** - Images, quotes, and code blocks add visual variety
7. **Proofread** - Typos undermine credibility

## Publishing Your Post

1. Create your `.mdx` file in `src/content/blog/`
2. Write your content with proper frontmatter
3. Add any images to `src/assets/` or `public/media/`
4. Preview with `pnpm dev`
5. Build and deploy with `pnpm deploy`

The blog index automatically updates, related posts are generated, and your RSS feed includes the new content.

## What's Next?

Now that you know the basics, start writing! Share your expertise, document your projects, or write tutorials to help others. Your unique perspective is valuable.

Happy writing!
