IT-Journey Developer Documentation¶

Welcome to the IT-Journey developer documentation. This directory contains comprehensive technical information for contributors, maintainers, and AI agents working on the IT-Journey repository.

📚 Documentation Structure¶

Architecture¶

Repository Structure - Complete directory tree and organization
Jekyll Implementation - Jekyll configuration, collections, and build process
About Reorganization - _about directory restructuring between repositories

Standards¶

Frontmatter Standards - Content metadata requirements and templates
Content Guidelines - Writing style, formatting, and conventions
Quest Template Enhancement - Quest template system improvements

Setup & Development¶

Development Environment - Local setup and configuration
Installation Updates - Theme installation and deployment

Workflows & Automation¶

GitHub Actions - CI/CD workflows and automation
Dependency Updates - Dependency management and build checking
Link Checker Resolution - Link health monitoring fixes
Link Checker Validation - Validation test results
Link Consolidation - Link checker workflow consolidation

Scripts & Tools¶

Scripts Guide - Automation scripts overview and usage
PRD Machine - Autonomous PRD generation and maintenance
Cleanup Summary - Script consolidation results
Consolidation Plan - Script organization strategy

Notes¶

Notes Workbench - The interactive /notes/ board: local notes, site-wide snippet clipping, and the public/private split

Testing¶

Testing Frameworks - Test infrastructure and validation tools

Contributing¶

Developer Contribution Guide - Technical contribution workflow

🎯 Quick Start for Contributors¶

1. Environment Setup¶

# Clone the repository
git clone https://github.com/bamr87/it-journey.git
cd it-journey

# Install dependencies
bundle install

# Run local development server
bundle exec jekyll serve --config _config_dev.yml

2. Understanding the Structure¶

pages/ - All content collections (_posts, _docs, _quests, _notebooks, etc.)
_config.yml - Main Jekyll configuration
scripts/ - Automation and development tools
test/ - Testing frameworks and validators
.github/workflows/ - CI/CD automation

3. Making Contributions¶

Read CONTRIBUTING_DEVELOPER.md
Review Content Guidelines
Follow Frontmatter Standards
Test locally before submitting PR

🔑 Key Concepts¶

Collections System¶

IT-Journey uses Jekyll collections for content organization: - _posts - Blog posts and journal entries - _docs - Learning resources and reference documentation - _quests - Gamified learning experiences - _notebooks - Jupyter notebooks and interactive content - _notes - Personal development notes - _about - About pages and site information - _quickstart - Quick reference guides

Content Types¶

Each content type has specific frontmatter requirements and conventions. See Frontmatter Standards for details.

Automation¶

The repository includes extensive automation: - Link Health Guardian - Automated link validation with AI analysis - Content Organization - Automated post organization and cleanup - Build Validation - Jekyll build verification - Dependency Checking - Security and version monitoring

🛠️ Development Tools¶

Local Development¶

# Development server with live reload
bundle exec jekyll serve --config _config_dev.yml --livereload

# Docker development
docker-compose up

# Build only (no server)
bundle exec jekyll build

Testing¶

# Run link checker locally
python3 scripts/validation/link-checker.py --scope website

# Validate frontmatter
# (Automated via GitHub Actions)

# Test quest validator
cd test/quest-validator && python validator.py

Scripts¶

# Core scripts
scripts/core/environment-setup.sh
scripts/core/version-manager.sh

# Development scripts
scripts/development/build/build-site.sh
scripts/development/content/jupyter-to-markdown.sh

🤖 AI Agent Guidelines¶

Context for AI Assistants¶

When working with this repository, AI agents should: 1. Read architecture docs first - Understand structure before making changes 2. Follow standards strictly - Adhere to frontmatter and content guidelines 3. Check existing patterns - Review similar content before creating new 4. Test locally - Verify builds succeed before committing 5. Reference documentation - Use these docs for authoritative information

Key Files for AI Context¶

_config.yml - Site configuration and collection definitions
docs/architecture/REPOSITORY_STRUCTURE.md - Complete directory layout
docs/standards/FRONTMATTER_STANDARDS.md - Content metadata requirements
docs/architecture/JEKYLL_IMPLEMENTATION.md - Build system details

Common AI Tasks¶

Creating new content → Follow Frontmatter Standards
Modifying scripts → Review Scripts Guide
Updating workflows → Check GitHub Actions
Fixing broken links → See Link Checker Resolution

📖 Additional Resources¶

External Documentation¶

Learning Resources¶

The pages/_docs/ directory contains educational content for learners: - Jekyll usage tutorials (specific to this repo) - Tool and technology references - External documentation links

These are separate from developer documentation and focus on the learning journey.

🆘 Getting Help¶

Documentation Issues¶

If documentation is unclear or incorrect, open an issue
Suggest improvements via pull requests
Ask questions in GitHub Discussions

Development Issues¶

Check Common Setup Issues
Review Workflow Troubleshooting
Search existing issues before creating new ones

Contact¶

GitHub Issues - Bug reports and feature requests
GitHub Discussions - Questions and community support
Pull Requests - Code and documentation contributions

📝 Documentation Maintenance¶

This documentation is maintained alongside the codebase. When making changes: - Update relevant documentation in the same PR as code changes - Keep examples current and tested - Follow the established documentation structure - Add new sections as needed for new features

Last Updated: 2025-11-26 Documentation Version: 1.1.0