Blog Post Development & Publishing Workflow

Overview

This site uses a draft-based workflow with scheduled publishing capabilities for blog posts.

Creating Draft Posts

Method 1: Using _drafts Folder (Recommended for Development)

1. Create your post in the _drafts/ folder without a date prefix:

   _drafts/my-awesome-post.md
   

2. Add frontmatter with a publish_date field:

   ---
   layout: post
   title: "My Awesome Post"
   description: "Brief description for SEO"
   publish_date: 2025-02-15  # When to auto-publish
   categories: [AI, n8n]
   tags: [workflow-automation, ai]
   author: john-doe
   image:
     path: /assets/img/blog/post-image.jpg
     alt: "Image description"
   ---
   

3. Preview drafts locally:

   bundle exec jekyll serve --drafts
   

Method 2: Future-Dated Posts

1. Create posts in _posts/ with future dates:

   _posts/2025-03-01-future-post.md
   

2. These won’t appear on the live site until the date passes (due to future: false in config)

Local Development

Preview Drafts

# Start server with drafts visible
bundle exec jekyll serve --drafts

# Or use the rake task
bundle exec rake serve:drafts

Convert Draft to Post Manually

# Move and rename with today's date
mv _drafts/my-post.md _posts/$(date +%Y-%m-%d)-my-post.md

Scheduled Publishing

The site includes a GitHub Action that runs daily to automatically publish drafts.

How It Works

1. Daily Check: The action runs at 9 AM UTC daily
2. Publish Logic:
   • Checks _drafts/ for posts with publish_date in the past
   • Moves them to _posts/ with proper date prefix
   • Commits and pushes changes

Setting Up a Scheduled Post

1. Create draft with publish_date:

   ---
   title: "Scheduled Post"
   publish_date: 2025-02-20
   ---
   

2. Commit to the prod branch
3. The post will auto-publish on the specified date

Manual Trigger

You can manually run the scheduled publisher:

1. Go to Actions tab in GitHub
2. Select “Scheduled Post Publisher”
3. Click “Run workflow”

Best Practices

1. Draft Naming

• Use descriptive names without dates
• Keep filenames URL-friendly (lowercase, hyphens)

2. Frontmatter Standards

Always include:

• title: Clear, SEO-friendly title
• description: 150-160 character summary
• categories: 1-2 main categories
• tags: 3-5 relevant tags
• author: Reference from _authors/
• image: Featured image with alt text

3. Content Guidelines

• Start with a compelling introduction
• Use headers (H2, H3) for structure
• Include code examples with syntax highlighting
• Add images with descriptive alt text
• End with clear call-to-action

4. Review Process

1. Write in _drafts/
2. Preview locally with --drafts flag
3. Get feedback (share preview link)
4. Set publish_date when ready
5. Commit to prod branch

5. Image Optimization

Before publishing:

bundle exec rake convert_to_webp

Workflow Examples

Quick Post (Publish Today)

# Create post directly in _posts
touch _posts/$(date +%Y-%m-%d)-quick-update.md

Planned Series

1. Create all drafts at once
2. Set staggered publish_date values
3. They’ll publish automatically over time

Emergency Unpublish

# Move back to drafts
mv _posts/2025-02-06-problem-post.md _drafts/problem-post.md
git add -A
git commit -m "Revert post to draft"
git push origin prod

Troubleshooting

Draft Not Publishing?

• Check publish_date format (YYYY-MM-DD)
• Ensure committed to prod branch
• Check Actions tab for errors
• Verify time zone (uses UTC)

Preview Not Working?

• Use bundle exec jekyll serve --drafts
• Check for syntax errors in frontmatter
• Ensure draft is in _drafts/ folder

Future Post Visible?

• Verify future: false in _config.yml
• Clear Jekyll cache: bundle exec jekyll clean