Getting Started with Our Blog System

Introduction

Welcome to the blog system! This guide will walk you through everything you need to know about creating, formatting, and publishing blog posts. Whether you’re writing tutorials, announcements, or long-form articles, this system has you covered.

Understanding Blog Layouts

Our blog system offers three distinct layouts, each optimized for different content types:

Standard Layout (Default)

The standard layout is the most versatile option, perfect for tutorials, guides, and general blog posts. It features:

• Full-width hero image at the top
• Sidebar table of contents on desktop (sticky scroll)
• Collapsible table of contents on mobile
• Author bio section at the bottom
• Related posts section with tag-based matching
• Social sharing buttons

When to use: General purpose posts, how-to guides, educational content

Magazine Layout

The magazine layout is designed for feature-rich, long-form content like case studies and in-depth articles. It includes:

• Two-column layout for better content flow
• Inline table of contents within the content area
• Floating social share sidebar (desktop only)
• Related posts in a dedicated sidebar
• Enhanced typography for readability

When to use: Long-form articles, case studies, feature stories, image-heavy content

Minimal Layout

The minimal layout focuses on typography and clean design, ideal for announcements and short reads:

• Centered content (max-width 680px)
• Collapsible table of contents
• Minimal UI elements to reduce distraction
• Simple text-based related posts
• No hero image emphasis

When to use: Announcements, quick updates, text-heavy posts, minimalist content

Frontmatter Configuration

Every blog post starts with frontmatter - the YAML section at the top of your markdown file between the --- delimiters. This metadata controls how your post is displayed and routed.

Required Fields

title: 'Your Post Title'
description: 'Brief summary for SEO and social sharing'
pubDate: 2025-01-15
author: 'Your Name'

These four fields are mandatory. Without them, your post won’t build correctly.

Optional Fields

layout: 'standard' # standard, magazine, or minimal
heroImage: '/images/hero.jpg'
heroImageAlt: 'Image description'
tags: ['tutorial', 'astro']
featured: true
updatedDate: 2025-01-20
excerpt: 'Custom excerpt text'

See the frontmatter at the top of this file for detailed explanations of each field!

Custom URL Routing

By default, blog posts use the /blog/{slug}/ URL pattern. But you can customize this using three approaches:

Option 1: Single Category

category: 'tutorials'
# Creates URL: /tutorials/getting-started-guide/

Option 2: Nested Categories

category: 'tutorials'
subcategory: 'astro'
# Creates URL: /tutorials/astro/getting-started-guide/

Option 3: Full Custom Path

categoryPath: 'guides/beginner'
# Creates URL: /guides/beginner/getting-started-guide/

Priority order: categoryPath > category + subcategory > category > default /blog/

Writing Markdown Content

Below the frontmatter, write your content using standard Markdown syntax:

Headings

Use ## for main sections, ### for subsections. These automatically appear in the table of contents!

Code Blocks

// Syntax highlighting is built-in
const greeting = 'Hello, world!';
console.log(greeting);

Lists

• Bullet points work as expected
• Just use - or * at the start of each line
• Nested lists are supported too

Links and Images

Link text

Tag Filtering and Related Posts

Tags serve two important purposes:

1. Archive filtering: Readers can filter posts by tag using ?tag=tutorial URL parameter
2. Related posts: The system automatically finds posts with matching tags to show at the bottom

Tag best practices:

• Use 3-5 tags per post
• Keep tags consistent (lowercase, hyphenated)
• Be specific: astro-tutorial is better than just tutorial

RSS Feed

All blog posts are automatically included in the RSS feed at /rss.xml. Readers can subscribe using their favorite RSS reader to get updates when you publish new content.

The RSS feed is auto-discovered by browsers through the <link rel="alternate"> tag in the page head.

SEO and Schema Markup

Every blog post automatically generates:

• Schema.org BlogPosting markup for rich search results
• Open Graph tags for social media sharing
• Twitter Card tags for Twitter/X previews
• Canonical URLs to prevent duplicate content issues
• Meta descriptions from your frontmatter

No manual SEO configuration needed - it’s all automated!

Dark Mode Support

All blog layouts fully support dark mode using Tailwind’s dark: variant system. The color scheme automatically adapts based on user preference.

Best Practices

Here are some tips for creating great blog posts:

1. Write descriptive titles: Clear, specific titles perform better in search
2. Optimize images: Keep hero images under 200KB, use WebP format
3. Use headings strategically: Break content into scannable sections
4. Add alt text: Always describe images for accessibility
5. Keep descriptions concise: 150-160 characters for meta descriptions
6. Tag consistently: Use the same tag names across related posts
7. Update old posts: Use updatedDate field to show freshness

Conclusion

You now have all the knowledge you need to create amazing blog posts! Experiment with different layouts, customize your URLs, and leverage tags for better organization.

Check out the /docs/blog-system.md file for even more detailed documentation, or explore /docs/blog-examples.md for copy-paste-ready examples.

Happy blogging!