Content Management Guide

This guide explains how to create, organize, and manage content for the johnoct.github.io website.

Content Types

The site supports two main content categories:

1. Technical Blog Posts (categories: blog)
2. GitHub Stars Collections (categories: github-stars)

Creating Technical Blog Posts

File Naming Convention

All blog posts must follow the Jekyll naming pattern:

YYYY-MM-DD-descriptive-title.md

Examples:

• 2024-12-06-aws-cost-optimization-strategies.md
• 2025-07-10-ecs-image-resolution-pull-through-cache.md

Front Matter Template

---
title: "Your Post Title"
date: 2024-12-06
layout: post
categories: blog
tags: [aws, cloud, devops, kubernetes]
---

Required Front Matter Fields

• title: Descriptive, SEO-friendly title
• date: Publication date in YYYY-MM-DD format
• layout: Always use post
• categories: Always use blog for technical posts
• tags: Array of relevant keywords

Content Structure

Follow this recommended structure for technical posts:

---
title: "Your Post Title"
date: 2024-12-06
layout: post
categories: blog
tags: [relevant, tags]
---

# Brief Introduction

Start with a personal experience, realization, or problem you encountered.

## The Problem

Clearly explain the challenge or issue you faced.

## The Solution

Present your approach with practical, actionable details.

### Code Examples

```bash
# Include relevant code snippets
kubectl get pods --namespace=production

Configuration Details

Provide specific implementation steps.

Key Learnings

• Use bullet points for main takeaways
• Focus on practical insights
• Share what you’d do differently
• Highlight important gotchas ```

Creating GitHub Stars Posts

Automated Daily Posts

Use the automation script for daily collections:

./scripts/daily-stars.sh

This creates posts with the format:

YYYY-MM-DD-daily-github-stars.md

Manual Weekly Roundups

For curated weekly collections, create files manually:

File Name

YYYY-MM-DD-github-stars-of-the-week.md

Front Matter

---
title: "GitHub Stars of the Week: Month DD-DD, YYYY"
date: 2024-12-06
layout: post
categories: github-stars
tags: [automation, open-source, github, weekly-roundup]
---

Content Format

This week's most interesting repository discoveries:

## 1. [Repository Name](https://github.com/user/repo)

**Author:** username | **Language:** Go | **Stars:** ⭐ 1,234

_Repository description explaining what it does._

**Topics:** topic1, topic2, topic3

**Why it's interesting:** Personal note about why you starred it.

---

## 2. [Another Repository](https://github.com/user/repo2)

[Continue with same format...]

Content Guidelines

Writing Style

Tone and Voice

• Use first-person narrative (“I discovered”, “I ran into”)
• Maintain conversational yet technical tone
• Be authentic and share real experiences
• Avoid generic advice - focus on specific insights

Structure

• Start with personal context or problem
• Explain the issue clearly and concisely
• Present solution with actionable details
• End with “Key Learnings” bullet points
• Keep posts focused and avoid elaboration

Technical Details

• Include specific commands, configurations, or code
• Provide enough context for others to follow
• Explain the “why” behind technical decisions
• Share troubleshooting steps when relevant

Formatting Standards

Headers

• Use # for main title (automatically generated from front matter)
• Use ## for major sections
• Use ### for subsections
• Maintain consistent hierarchy

Code Blocks

# Use language-specific syntax highlighting
aws s3 ls s3://my-bucket

# YAML configuration examples
apiVersion: v1
kind: Service
metadata:
  name: my-service

Links

• Use descriptive link text: [AWS Documentation](https://docs.aws.amazon.com)
• Avoid “click here” or generic text
• Link to relevant external resources

Images

![Descriptive alt text](/assets/images/filename.jpg)

• Place images in assets/images/ directory
• Use descriptive alt text for accessibility
• Optimize images for web (< 500KB recommended)

Tags and Categories

Category Usage

• blog: All technical articles and tutorials
• github-stars: All repository collections and discoveries

Tag Best Practices

• Use 3-6 relevant tags per post
• Include primary technology (aws, kubernetes, docker)
• Add topic areas (devops, cloud, infrastructure)
• Use consistent tag names across posts

Common Tags

• Technologies: aws, kubernetes, docker, terraform, ansible
• Topics: devops, cloud, infrastructure, automation, monitoring
• Concepts: cost-optimization, security, performance, troubleshooting

Content Organization

File Management

Directory Structure

_posts/
├── 2024-12-06-aws-cost-optimization.md      # Technical blog
├── 2025-07-25-github-stars-of-the-week.md   # Manual roundup
├── 2025-07-26-daily-github-stars.md         # Automated daily
└── 2025-07-27-new-technical-post.md         # Technical blog

Naming Consistency

• Use lowercase for all filenames
• Replace spaces with hyphens
• Keep titles concise but descriptive
• Avoid special characters except hyphens

Content Discovery

Blog Page (blog.md)

• Shows only posts with categories: blog
• Displays in reverse chronological order
• Includes post excerpts and dates
• Filtered view for technical content

GitHub Stars Page (github-stars.md)

• Shows only posts with categories: github-stars
• Displays both daily and weekly posts
• Includes post tags for filtering
• Automated and manual content mixed

Workflow

Creating a New Technical Post

1. Plan the post
   • Identify the problem or experience to share
   • Outline key points and learnings
   • Gather code examples and screenshots
2. Create the file

   touch _posts/$(date +%Y-%m-%d)-your-post-title.md
   

3. Add front matter
   • Choose descriptive title
   • Set correct date
   • Add relevant tags
   • Use categories: blog
4. Write content
   • Follow the established structure
   • Include personal context
   • Provide actionable details
   • End with key learnings
5. Test locally

   bundle exec jekyll serve
   

6. Review and publish
   • Check formatting and links
   • Verify mobile responsiveness
   • Commit and push to GitHub

Managing GitHub Stars Content

1. Daily automation (recommended)
   • Run ./scripts/daily-stars.sh manually or via cron
   • Review generated content before committing
   • Edit descriptions if needed
2. Weekly roundups (manual)
   • Select most interesting repositories from the week
   • Add personal commentary about why they’re notable
   • Include context about how you might use them

Best Practices

Content Quality

• Focus on practical, actionable insights
• Share real experiences and learnings
• Include enough detail for others to follow
• Provide context for technical decisions

SEO Optimization

• Use descriptive, keyword-rich titles
• Include relevant tags for discoverability
• Write clear, scannable content
• Add internal links between related posts

Maintenance

• Review and update outdated technical information
• Fix broken links periodically
• Ensure consistent formatting across posts
• Monitor site performance and loading times

Next Steps: Review the Style Guide for detailed writing guidelines and the GitHub Stars Automation for automation details.