Frontmatter Standards¶

This document defines the required and optional frontmatter fields for each content type in the IT-Journey repository.

Overview¶

Frontmatter is YAML metadata at the beginning of each Markdown file, enclosed by triple dashes (---). It provides structured information that Jekyll uses to process and display content.

Universal Fields¶

These fields are applicable to all content types:

Required Universal Fields¶

title: "Your Content Title"

Recommended Universal Fields¶

description: "Brief description of the content"
author: "Author Name"
date: 2025-10-13T00:00:00.000Z
lastmod: 2025-10-13T00:00:00.000Z

Optional Universal Fields¶

draft: false                    # Set to true to mark as draft
slug: "custom-url-slug"        # Override default URL slug
permalink: "/custom/path/"      # Override default permalink
excerpt: "Short summary"        # Manual excerpt (auto-generated if not set)

Content Type Templates¶

Blog Posts (`_posts`)¶

File Naming: YYYY-MM-DD-title-slug.md

Required Fields:

---
title: "Post Title"
date: 2025-10-13T00:00:00.000Z
layout: articles
---

Complete Template:

---
title: "Understanding Jekyll Collections"
description: "A deep dive into Jekyll's collection system"
author: "Amr Abdel-Motaleb"
layout: articles
date: 2025-10-13T12:00:00.000Z
lastmod: 2025-10-13T15:30:00.000Z
categories:
  - development
  - jekyll
tags:
  - jekyll
  - collections
  - static-sites
slug: jekyll-collections-deep-dive
excerpt: "Explore how Jekyll collections organize content effectively"
image: /assets/images/posts/jekyll-collections.png
mermaid: false
mathjax: false
toc: true
toc_sticky: true
draft: false
---

Field Descriptions: - layout - Always "journals" for posts - categories - List of categories (affects URL structure) - tags - List of tags for filtering and search - image - Hero image or thumbnail - mermaid - Set to true to enable Mermaid diagrams - mathjax - Set to true to enable mathematical notation - toc - Set to true to generate table of contents - toc_sticky - Set to true for sticky TOC sidebar

Quests (`_quests`)¶

File Naming: descriptive-quest-title.md

Required Fields:

---
title: "Quest Title"
date: 2025-10-13T00:00:00.000Z
layout: default
---

Complete Template:

---
title: "The Link Guardian's Quest: Automated Hyperlink Validation"
description: "Master the art of automated link checking with AI-powered analysis"
author: "Amr Abdel-Motaleb"
layout: default
date: 2025-10-13T00:00:00.000Z
lastmod: 2025-10-13T00:00:00.000Z
categories:
  - automation
  - devops
tags:
  - python
  - github-actions
  - ai
  - testing
level: "0101"                   # Binary level (0000-1111)
difficulty: "intermediate"       # beginner, intermediate, advanced, expert
quest_type: "automation"         # automation, development, devops, data-science
xp: 500                         # Experience points
achievements:
  - "Link Guardian"
  - "CI/CD Master"
prerequisites:
  - "Basic Python knowledge"
  - "GitHub Actions familiarity"
estimated_time: "2-3 hours"
platforms:
  - macOS
  - Windows
  - Linux
slug: link-guardian-quest
excerpt: "Learn to implement automated link validation with AI analysis"
image: /assets/images/quests/link-guardian.png
toc: true
toc_sticky: true
mermaid: true
draft: false
---

Quest-Specific Fields: - level - Binary system (0000, 0001, 0010, etc.) indicating progression - difficulty - Difficulty rating: beginner, intermediate, advanced, expert - quest_type - Category of quest - xp - Experience points awarded upon completion - achievements - List of achievements earned - prerequisites - Required knowledge or previous quests - estimated_time - Expected completion time - platforms - Supported operating systems

Documentation (`_docs`)¶

File Naming: tool-topic-description.md

Required Fields:

---
title: "Jekyll - Liquid Templating"
date: 2025-10-13T00:00:00.000Z
---

Complete Template:

---
title: "Jekyll - Liquid Templating"
description: "Guide to using Liquid templating language in Jekyll"
author: "Amr Abdel-Motaleb"
layout: default
date: 2025-10-13T00:00:00.000Z
lastmod: 2025-10-13T00:00:00.000Z
subcategory: jekyll             # Grouping within docs
tags:
  - jekyll
  - liquid
  - templating
key: tutorial                   # Legacy field, optional
index: 8111                     # Legacy ordering, optional
sources:
  - https://shopify.github.io/liquid/
  - https://jekyllrb.com/docs/liquid/
slug: jekyll-liquid-templating
excerpt: "Master Liquid templating for Jekyll sites"
toc: true
toc_sticky: true
draft: false
---

Docs-Specific Fields: - subcategory - Used to group related docs (e.g., all Jekyll docs) - sources - List of external reference URLs - key - Legacy field from old system (optional) - index - Legacy numbering system (optional)

Notebooks (`_notebooks`)¶

File Naming: descriptive-notebook-name.md or notebook.ipynb

For Markdown (.md):

---
title: "Data Analysis with Pandas"
description: "Exploratory data analysis using Pandas library"
author: "Amr Abdel-Motaleb"
layout: default
date: 2025-10-13T00:00:00.000Z
lastmod: 2025-10-13T00:00:00.000Z
categories:
  - data-science
tags:
  - python
  - pandas
  - data-analysis
notebook_type: "tutorial"       # tutorial, analysis, visualization, ml
language: "python"              # python, r, julia, javascript
kernel: "python3"
packages:
  - pandas
  - numpy
  - matplotlib
slug: pandas-data-analysis
excerpt: "Learn data analysis fundamentals with Pandas"
draft: false
---

For Jupyter (.ipynb): Frontmatter is stored in the notebook metadata. When converting to markdown, extract and format appropriately.

Notebook-Specific Fields: - notebook_type - Type of notebook content - language - Programming language used - kernel - Jupyter kernel name - packages - Required Python/R packages

Notes (`_notes`)¶

File Naming: descriptive-note-name.md

Minimal Template:

---
title: "Feature Idea: AI-Powered Content Suggestions"
date: 2025-10-13T00:00:00.000Z
status: "draft"                 # draft, in-progress, complete, archived
---

Complete Template:

---
title: "Feature Idea: AI-Powered Content Suggestions"
description: "Exploring AI-driven content recommendations"
author: "Amr Abdel-Motaleb"
date: 2025-10-13T00:00:00.000Z
lastmod: 2025-10-13T00:00:00.000Z
status: "in-progress"           # draft, in-progress, complete, archived
categories:
  - development
  - ai
tags:
  - ai
  - features
  - ideas
visibility: "private"           # private, team, public
related_quest: "ai-integration-quest"
slug: ai-content-suggestions
---

Notes-Specific Fields: - status - Current state: draft, in-progress, complete, archived - visibility - Who can see this: private, team, public - related_quest - Link to related quest (if applicable)

About Pages (`_about`)¶

File Naming: descriptive-page-name.md

Required Fields:

---
title: "About IT-Journey"
layout: default
---

Complete Template:

---
title: "About IT-Journey"
description: "Learn about the IT-Journey learning platform"
layout: default
date: 2025-10-13T00:00:00.000Z
lastmod: 2025-10-13T00:00:00.000Z
permalink: /about/
categories:
  - about
sidebar:
  nav: about
toc: true
slug: about-it-journey
excerpt: "Discover the IT-Journey mission and vision"
---

Quickstart Guides (`_quickstart`)¶

File Naming: tool-quickstart.md

Required Fields:

---
title: "Jekyll Quickstart"
layout: default
---

Complete Template:

---
title: "Jekyll Quickstart"
description: "Quick reference for Jekyll commands and configuration"
layout: default
date: 2025-10-13T00:00:00.000Z
lastmod: 2025-10-13T00:00:00.000Z
categories:
  - quickstart
tags:
  - jekyll
  - reference
tool: "Jekyll"                  # Tool/technology name
version: "3.9.5"                # Tool version
sidebar:
  nav: quickstart
toc: true
slug: jekyll-quickstart
excerpt: "Essential Jekyll commands and tips"
---

Quickstart-Specific Fields: - tool - Name of tool/technology - version - Version number for reference

Date Formatting¶

ISO 8601 Format (Preferred)¶

date: 2025-10-13T12:30:00.000Z
lastmod: 2025-10-13T15:45:30.000Z

Alternative Formats (Also Supported)¶

date: 2025-10-13
date: 2025-10-13 12:30:00 -0600

Category and Tag Conventions¶

Categories¶

Use lowercase with hyphens
Limit to 2-3 categories per post
Categories affect URL structure
Be consistent across similar content

Examples:

categories:
  - development
  - jekyll
  - automation

Tags¶

Use lowercase with hyphens
More specific than categories
Can have many tags per post
Used for search and filtering

Examples:

tags:
  - python
  - github-actions
  - ci-cd
  - automation
  - testing

Boolean Values¶

Always use lowercase true and false:

draft: false
toc: true
toc_sticky: true
mermaid: false
mathjax: false

Lists and Arrays¶

Use YAML list syntax:

# Method 1: Dash notation
tags:
  - python
  - jekyll
  - automation

# Method 2: Inline array (less readable, not recommended)
tags: [python, jekyll, automation]

Multi-line Strings¶

Use YAML multi-line syntax:

# Literal block (preserves newlines)
description: |
  This is a longer description
  that spans multiple lines
  and preserves formatting.

# Folded block (joins lines)
excerpt: >
  This is a longer excerpt
  that will be joined into
  a single paragraph.

Special Characters¶

Escape or quote strings with special characters:

# Quotes required for colons
title: "Jekyll: A Static Site Generator"

# Quotes required for quotes
excerpt: 'He said, "Hello World"'

# Escape quotes within same quote type
excerpt: "He said, \"Hello World\""

Validation¶

Required Field Checklist¶

Before committing content, verify:

Title is present and descriptive
Date is in valid ISO 8601 format
Layout is specified (or uses collection default)
Categories/tags are lowercase with hyphens
No extra spaces or tabs (YAML is whitespace-sensitive)
Boolean values are lowercase
Special characters are properly escaped/quoted

Automated Validation¶

The repository includes automated frontmatter validation via GitHub Actions:

Runs on all commits to main branch
Checks required fields for each content type
Validates date formats
Ensures proper YAML syntax
Reports errors in workflow logs

See .github/workflows/frontmatter-validation.yml for details.

Common Mistakes¶

❌ Incorrect¶

# Missing quotes with colon
title: Jekyll: Static Site Generator

# Uppercase boolean
draft: True

# Mixed case tags
tags:
  - Python
  - GitHub-Actions

# Inconsistent date format
date: 10/13/2025

# Extra spaces in list
tags:
  -  python
  -   jekyll

✅ Correct¶

# Proper quoting
title: "Jekyll: Static Site Generator"

# Lowercase boolean
draft: true

# Lowercase tags
tags:
  - python
  - github-actions

# ISO 8601 date
date: 2025-10-13T00:00:00.000Z

# Consistent spacing
tags:
  - python
  - jekyll

Frontmatter Tools¶

VS Code Extensions¶

Front Matter CMS - Visual frontmatter editor
YAML - YAML syntax highlighting and validation

Validation Scripts¶

# Check frontmatter in a file
bundle exec jekyll doctor

# Build site (will show frontmatter errors)
bundle exec jekyll build --verbose

Migration Notes¶

Legacy Fields¶

Some content may have legacy fields from previous systems:

key: tutorial - Old categorization system (optional, can keep)
index: 8111 - Old numbering system (optional, can keep)
subcategory - Still used in docs collection

These fields don't break anything but can be cleaned up gradually.

Updating Old Content¶

When updating old content: 1. Add missing required fields 2. Standardize date formats to ISO 8601 3. Convert categories/tags to lowercase-hyphen format 4. Add description and excerpt if missing 5. Update lastmod date

Best Practices¶

Be Consistent - Use the same field names and formats across similar content
Be Descriptive - Write clear titles and descriptions
Be Complete - Include all recommended fields, not just required ones
Be Precise - Use accurate dates, especially for lastmod
Be Organized - Use categories and tags thoughtfully
Be Valid - Test with jekyll build before committing
Be Current - Update lastmod when making significant changes

Additional Resources¶

Last Updated: 2025-10-13 Version: 1.0.0

Frontmatter Standards¶

Overview¶

Universal Fields¶

Required Universal Fields¶

Recommended Universal Fields¶

Optional Universal Fields¶

Content Type Templates¶

Blog Posts (_posts)¶

Quests (_quests)¶

Documentation (_docs)¶

Notebooks (_notebooks)¶

Notes (_notes)¶

About Pages (_about)¶

Quickstart Guides (_quickstart)¶

Date Formatting¶

ISO 8601 Format (Preferred)¶

Alternative Formats (Also Supported)¶

Category and Tag Conventions¶

Categories¶

Tags¶

Boolean Values¶

Lists and Arrays¶

Multi-line Strings¶

Special Characters¶

Validation¶

Required Field Checklist¶

Automated Validation¶

Common Mistakes¶

❌ Incorrect¶

✅ Correct¶

Frontmatter Tools¶

VS Code Extensions¶

Validation Scripts¶

Migration Notes¶

Legacy Fields¶

Updating Old Content¶

Best Practices¶

Additional Resources¶

Blog Posts (`_posts`)¶

Quests (`_quests`)¶

Documentation (`_docs`)¶

Notebooks (`_notebooks`)¶

Notes (`_notes`)¶

About Pages (`_about`)¶

Quickstart Guides (`_quickstart`)¶