Style Guide and Content Patterns

This post serves as the definitive style guide for writing content on this blog. It covers markdown syntax, MDX capabilities, content structure patterns, and the conventions that ensure consistency across all posts.

Content Architecture Overview

This blog is built with Astro and uses a hybrid approach combining Markdown and MDX for content creation. The content system is designed to be simple and extensible, allowing for rich formatting while maintaining consistency.

File Structure

All blog posts are stored in src/content/blog/ and follow this structure:

src/content/blog/
├── post-title.md          # Standard markdown posts
├── post-title.mdx         # MDX posts with React components
└── assets/                # Post-specific images

Frontmatter Schema

Every post must include specific frontmatter fields defined in src/content.config.ts:

---
title: 'Your Post Title'
description: 'A compelling description for SEO and social sharing'
pubDate: 'Dec 19 2024'
updatedDate: 'Dec 20 2024'  # Optional - for updated posts
heroImage: '../../assets/blog-placeholder-1.jpg'  # Optional
---

Frontmatter Requirements

  • title: String - The main heading of your post
  • description: String - Used for meta tags and social sharing (keep under 160 characters)
  • pubDate: Date - Publication date in ‘MMM DD YYYY’ format
  • updatedDate: Date (optional) - For posts that have been revised
  • heroImage: Image path (optional) - Hero image displayed at the top

Markdown Syntax Guide

Headings

Use heading hierarchy properly for SEO and accessibility:

# H1 - Main title (handled by frontmatter)
## H2 - Section headings
### H3 - Subsection headings
#### H4 - Minor sections
##### H5 - Rarely used
###### H6 - Very rarely used

Best Practice: Never skip heading levels (e.g., H1 → H3). Always use H2 after H1, H3 after H2, etc.

Text Formatting

**Bold text** for emphasis
*Italic text* for subtle emphasis
`inline code` for technical terms
~~strikethrough~~ for deprecated content
[Link text](https://example.com)
[Internal link](../other-post.md)
[GitHub](https://github.com/jarriagad)

Best Practice: Use descriptive link text, not “click here” or “read more.”

Images

![Alt text describing the image](../../assets/image-name.jpg)

Best Practice:

  • Always include meaningful alt text
  • Use relative paths from the post location
  • Store images in src/assets/ for global use
  • Optimize images before adding them

Code Blocks

Inline Code

Use `npm install package-name` to install dependencies.

Code Blocks with Syntax Highlighting

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

Lists

Unordered Lists

- First item
- Second item
  - Nested item
  - Another nested item
- Third item

Ordered Lists

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

Blockquotes

> This is a blockquote for highlighting important information.
> 
> You can have multiple paragraphs in a blockquote.

Tables

Althought column lines don’t have to line up, for when possible, line uniformity must be maintained.

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |
| Data 4   | Data 5   | Data 6   |

MDX Capabilities

MDX files (.mdx extension) allow you to use React components within your markdown content. This is useful for:

Interactive Components

import { CodeBlock } from '../components/CodeBlock.astro';

# My Post

Here's an interactive code example:

<CodeBlock language="javascript" filename="example.js">
{`function example() {
  return "Hello World";
}`}
</CodeBlock>

Custom Components

import { Callout } from '../components/Callout.astro';

<Callout type="warning">
  This is an important warning message.
</Callout>

Technical Writing

  • Code examples: Always include working, tested code
  • Screenshots: Use when showing UI or complex outputs
  • Step-by-step guides: Break complex processes into numbered steps
  • Error handling: Include common errors and solutions

Image Guidelines

Hero Images

  • Dimensions: 1200x630px (16:9 ratio) for optimal social sharing
  • Format: JPG or PNG
  • File size: Under 500KB for fast loading
  • Content: Relevant to the post topic, not generic

Inline Images

Avoid at all costs

Image Naming Convention

blog-post-title-image-1.jpg
blog-post-title-diagram.png
blog-post-title-screenshot.jpg

Code Example Standards

Inline Code

Install the package using `npm install package-name`.

Code Blocks

Always specify the language for syntax highlighting:

```bash
npm install package-name
```

```javascript
const example = require('package-name');
console.log(example);
```

File References

When showing code from files, include the filename:

```javascript:src/components/Example.js
function Example() {
  return <div>Hello World</div>;
}
```

Consistency Checklist

Before publishing, ensure your post follows these standards:

  • Proper frontmatter with all required fields
  • Correct heading hierarchy (H1 → H2 → H3)
  • Descriptive link text
  • Meaningful image alt text
  • Code examples are tested and working
  • Grammar and spelling checked
  • Internal links to related posts (if applicable)
  • Meta description under 160 characters
  • Hero image is relevant and properly sized

Resource Lists

## Additional Resources

- [Official Documentation](https://example.com/docs)
- [Related Blog Post](../related-post.md)
- [GitHub Repository](https://github.com/example/repo)

Warning/Note Blocks

> **Note**: This approach works best for small to medium-sized projects. For larger applications, consider using a more robust solution.

> **Warning**: Make sure to backup your data before running these commands.

Conclusion

Following these guidelines ensures that all content on this blog maintains a consistent, professional appearance while being accessible and useful to readers. The combination of Markdown and MDX provides the flexibility needed for technical content while keeping the writing process straightforward.

Remember, the goal is to create content that is both informative and enjoyable to read. When in doubt, prioritize clarity and usefulness over perfect adherence to every rule.

For questions about this style guide or suggestions for improvements, feel free to reach out on GitHub or LinkedIn.