Article Management Guide
This document outlines the structure, publication process, and best practices for managing articles on the joshuamichaelhall.github.io site.
Article Structure
All blog posts should be stored in the _posts
directory (directly under the repository root) following the Jekyll naming convention:
YYYY-MM-DD-title-with-hyphens.md
For example:
2025-05-20-strategic-approach-to-devops-skills.md
Required Frontmatter
Every article must include the following frontmatter at the top of the file:
---
layout: post
title: "Your Article Title Here"
date: YYYY-MM-DD
categories: category1 category2
tags: tag1 tag2 tag3
excerpt: "A brief summary of the article (1-2 sentences)"
published: true
---
Article text starts immediately after the frontmatter closing delimiter without a blank line.
- layout: Should be
post
for all blog articles - title: The full title of your article
- date: Publication date in YYYY-MM-DD format
- categories: Space-separated list of categories (usually 1-3)
- tags: Space-separated list of tags relevant to the content
- excerpt: A brief summary that will appear in article listings
- featured: (Optional) Set to
true
for the main highlighted article that best represents your expertise - published: Set to
true
for all public articles (default is true if omitted)
Publication Control
To control whether an article is published:
- For published articles: Include the frontmatter as shown above
- For draft/unpublished articles: Add
published: false
to the frontmatter
---
layout: post
title: "Draft Article"
date: YYYY-MM-DD
categories: category1 category2
published: false
---
Current Article Status
As of the latest update, the site includes the following articles:
Published Articles
- “Terminal-Based Development with Neovim, tmux, and CLI Tools” (2025-03-23)
- “Infrastructure as Code Best Practices for Financial Services” (2025-05-05) - Featured Article 🌟
Published Articles (continued)
- “Setting Up a Secure AWS Learning Environment for DevOps Practice” (2025-05-20)
Build Process
Articles are processed during the Jekyll build process. To verify that an article will be published correctly:
- Run a local build:
bundle exec jekyll build
- Check the
_site/blog/
directory to confirm your article appears there - If the article doesn’t appear, check the frontmatter and ensure
published: false
is not present
Troubleshooting
If your articles are not appearing in the built site:
- Check article location: Ensure the file is directly in the
_posts
directory, not in a subdirectory - Verify frontmatter: Make sure frontmatter is formatted correctly with proper YAML syntax
- Check file name: Ensure the file follows the YYYY-MM-DD-title.md pattern
- Check publication status: Remove
published: false
if you want the article to appear
Best Practices
- Use descriptive file names that match the article content
- Include relevant categories and tags to improve discoverability
- Write meaningful excerpts that accurately summarize the content
- Add images to the
assets/images
directory and reference them in articles - Preview locally before pushing changes to production
Updating This Document
When adding new articles or changing the publication process, please update this document to keep it current.
Last updated: May 21, 2025 (removed “Why I’m Transitioning to DevOps/SRE” and “Strategic Approach to DevOps Skills” articles)