Learning Journey Repository

This repository contains 427+ project-based learning guides published as a static website via GitHub Pages.

For detailed documentation about the learning guides format, skills, and content structure, see: project_based_ideas/CLAUDE.md

GitHub Pages Deployment

Live Site: https://ideas4projects.douglascorrea.io

How It Works

The site is built with Jekyll and automatically deployed via GitHub Actions when changes are pushed to master.

project_based_ideas/*/    --|
                            |--> GitHub Actions --> Jekyll Build --> GitHub Pages
docs/ (theme/layouts)     --|

Deployment Triggers

The workflow (.github/workflows/deploy.yml) runs on push to master when these paths change:

  • project_based_ideas/** - Any learning guide
  • docs/** - Theme, layouts, or configuration
  • .github/workflows/deploy.yml - The workflow itself

Build Process

  1. Copy Content: Uppercase .md files from project_based_ideas/<CATEGORY_FOLDER>/ are copied to docs/
  2. Add Front Matter: Jekyll metadata is injected (title, description, category, date_added)
  3. Category Assignment: Files are categorized using docs/_data/categories.yml
  4. Expanded Projects: Detail folders (P01-*.md, etc.) are copied and linked
  5. Asset Copy: Images from project_based_ideas/assets/ are copied to docs/assets/
  6. Jekyll Build: Site is built and deployed to GitHub Pages

Directory Structure

.
|-- project_based_ideas/          # Source content (learning guides)
|   |-- *.md                      # Main learning guides (UPPERCASE_NAMES.md)
|   |-- */                        # Expanded project folders
|   |   `-- P01-*.md, P02-*.md    # Individual project deep-dives
|   |-- assets/                   # Generated images from ASCII diagrams
|   `-- 00_system_prompts_and_skills/  # Prompts for content generation
|
|-- docs/                         # Jekyll site (theme and config)
|   |-- _config.yml               # Jekyll configuration
|   |-- _layouts/                 # Page layouts (default, project, project-detail)
|   |-- _data/categories.yml      # Category mappings for all files
|   |-- assets/                   # CSS, JS, and site assets
|   |-- index.html                # Homepage with search/filter
|   `-- CNAME                     # Custom domain config
|
`-- .github/workflows/deploy.yml  # GitHub Actions deployment workflow

Adding New Content

  1. Create a new UPPERCASE_NAME.md inside the correct project_based_ideas/<CATEGORY_FOLDER>/
  2. Ensure the category exists in docs/_data/categories.yml with a matching folder: entry
  3. Push to master - deployment is automatic

Category System

Categories are defined in docs/_data/categories.yml. Each category has:

  • id - Short identifier used in URLs
  • name - Display name on the website
  • description - Brief description
  • folder - Subdirectory name under project_based_ideas/ that holds the guides

Current categories: Systems Programming, Hardware/CPU, Compilers, Languages, Concurrency, Networking, Distributed Systems, Databases, ML/AI, Security, DevOps, Tooling, Architecture, Graphics/Games, Web Development, Data Engineering, Algorithms/Math, Blockchain, Desktop/GUI, IoT, Automation, Enterprise, Education

Local Development

To run the site locally:

cd docs
bundle install
bundle exec jekyll serve

Site will be available at http://localhost:4000

User Features

Playlist System

The site includes a comprehensive playlist system allowing users to organize learning guides into custom collections.

Features:

  • Create unlimited playlists with names and descriptions
  • Add guides via card button or bulk selection mode
  • Navigate to dedicated playlist pages (hash-based routing: #/playlist/{id})
  • Reorder guides within playlists (drag-and-drop)
  • Track completion progress per playlist
  • Remove guides from playlists
  • Edit/delete playlists

Implementation:

  • Storage: localStorage with split storage pattern
    • ideas4projects-playlists - Playlist metadata (all playlists)
    • ideas4projects-playlist-{id} - Individual playlist contents
  • Modules:
    • docs/assets/js/playlist-manager.js (500+ lines) - Data layer, CRUD operations
    • docs/assets/js/playlist-ui.js (750+ lines) - UI rendering and interactions
    • docs/assets/js/playlist-router.js (160+ lines) - Hash-based SPA routing
  • Limits: 50 playlists max, 100 guides per playlist
  • Sync: Changes sync across browser tabs via storage events

User Flow:

  1. Click “Create Playlist” in playlist section
  2. Add guides via “+” button on cards or bulk selection
  3. Click playlist card to navigate to playlist page
  4. Reorder guides via drag handles
  5. Track progress as guides are completed

Data Export/Import

Users can backup and restore all their preferences across browsers or devices.

Features:

  • Export all localStorage data as JSON file
  • Import from JSON file with validation
  • Confirmation dialog showing import preview
  • Automatic page reload after import
  • Visual notifications for success/error

Data Included:

  • All playlists (metadata and contents)
  • Completion tracking (completed projects)
  • Theme preference
  • Typography settings (font, size, spacing)
  • Pinned projects
  • Custom ordering (global and per-category)

Implementation:

  • Module: docs/assets/js/data-export-import.js (360 lines)
  • UI Location: Reading Preferences panel (gear icon in navbar)
  • Export Format: JSON with version and timestamp
  • Storage Keys: All keys starting with ideas4projects-

User Flow:

  1. Open Reading Preferences panel
  2. Click “Export” to download backup file
  3. Click “Import” to select and restore from backup file
  4. Confirm import after reviewing what will be restored
  5. Page reloads with restored preferences

Removed Features

Learning Paths Dropdown (Removed 2025-12-29)

  • Replaced by playlist system for better user control
  • Dropdown navigation removed from navbar
  • Users can now create custom learning paths via playlists

Technical Architecture

localStorage Schema

All user data is stored in browser localStorage with these keys:

Playlists:

  • ideas4projects-playlists - Object mapping playlist IDs to metadata
  • ideas4projects-playlist-{id} - Array of guide slugs for each playlist

Progress Tracking:

  • ideas4projects-completed - Object mapping guide IDs to arrays of completed project IDs

User Preferences:

  • ideas4projects-theme - Selected theme name
  • ideas4projects-font-family - Font choice (sans/serif/mono/dyslexic)
  • ideas4projects-font-size - Font size in pixels
  • ideas4projects-line-height - Line spacing (compact/normal/relaxed)
  • ideas4projects-pinned - Array of pinned project slugs
  • ideas4projects-order-global - Global custom project order
  • ideas4projects-order-{category} - Per-category custom order

JavaScript Modules

Core Functionality:

  • theme-switcher.js - Theme management (30+ themes)
  • user-preferences.js - Typography, pinning, drag-drop ordering
  • project-completion.js - Completion tracking and progress calculation

Playlist System:

  • playlist-manager.js - CRUD operations, progress integration
  • playlist-ui.js - DOM manipulation, modals, bulk selection
  • playlist-router.js - Hash-based routing for playlist pages

Data Management:

  • data-export-import.js - Backup and restore functionality

Module Pattern:

  • All modules use IIFE (Immediately Invoked Function Expression)
  • Global API exposed via window.{ModuleName}
  • Event-driven architecture with custom events
  • No external dependencies (vanilla JavaScript)

Routing System

Hash-based SPA Routing:

  • Default view: /# or / - Shows all guides with filters
  • Playlist view: /#/playlist/{id} - Shows single playlist page

Benefits:

  • No page reload required
  • Browser back/forward support
  • Works with static hosting (no server-side routing)
  • Clean URLs for sharing playlists

Quick Reference

Action Command/Location
Add new learning guide Create project_based_ideas/NEW_TOPIC.md
Assign category Edit docs/_data/categories.yml
Modify site layout Edit docs/_layouts/*.html
Change site config Edit docs/_config.yml
Manual deploy Trigger workflow in GitHub Actions
View deploy logs .github/workflows/deploy.yml runs

Skills

These skills are discovered at startup from multiple local sources. Each entry includes a name, description, and file path so you can open the source for full instructions.

  • acp: Add/commit/push workflow for git repositories. Use when the user says “acp”, “add commit push”, “commit and push”, or asks to stage all changes in the current directory, write a good commit message from git diff, commit, and push the current branch without creating or switching branches. (file: /Users/douglas/Sites/dotfiles/codex/skills/acp/SKILL.md)
  • ascii-to-diagram: Convert ASCII art in markdown files to professional technical diagrams/infographics. Use when the user says “convert ascii art”, “generate diagram from ascii”, “replace ascii with image”, “ascii-to-diagram”, or wants to create book-quality technical illustrations from text-based diagrams. (file: /Users/douglas/Sites/dotfiles/codex/skills/ascii-to-diagram/SKILL.md)
  • create-plan: Create a concise plan. Use when a user explicitly asks for a plan related to a coding task. (file: /Users/douglas/Sites/dotfiles/codex/skills/create-plan/SKILL.md)
  • expand-project-ideas: Break down project-based learning files into individual expanded project files. Use when the user says “expand projects”, “break down projects”, “expand project ideas”, “create individual project files”, “deep dive into projects”, or wants to transform a project list into comprehensive individual learning guides with theory, solutions, and implementation details. (file: /Users/douglas/Sites/dotfiles/codex/skills/expand-project-ideas/SKILL.md)
  • improve-project-learning: Improve project-based learning files by turning them into a mini-book + project sprint (deep theory primer before projects), adding maximum-detail explanations, diagrams, guiding questions, real-world outcomes, and book references. This skill may add new sections or restructure files as needed, and should use WebSearch and any available resources to deliver the most complete, educational version of the document. (file: /Users/douglas/Sites/dotfiles/codex/skills/improve-project-learning/SKILL.md)
  • project-based-learning: Create comprehensive, deep-learning project-based paths for mastering technologies and concepts from first principles. Use when the user says “I want to learn”, “teach me”, “create a learning path”, “help me understand”, “project ideas for learning”, or wants to deeply understand any technology, concept, tool, or programming language through hands-on projects. Generates 10-20 real-world projects with conceptual explanations, ASCII diagrams, progressive hints, book references, and interview questions. (file: /Users/douglas/Sites/dotfiles/codex/skills/project-based-learning/SKILL.md)
  • skill-creator: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Codex’s capabilities with specialized knowledge, workflows, or tool integrations. (file: /Users/douglas/Sites/dotfiles/codex/skills/.system/skill-creator/SKILL.md)
  • skill-installer: Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos). (file: /Users/douglas/Sites/dotfiles/codex/skills/.system/skill-installer/SKILL.md)
  • technical-architect: Transform functional specifications, PRDs, or business requirements into comprehensive technical specifications with architecture decisions, implementation guidance, and sprint-ready task breakdowns. Use when a user needs a technical spec derived from a functional spec or wants requirements translated into implementable architecture, APIs, data models, and development tasks for a team, including junior developers. (file: /Users/douglas/Sites/dotfiles/codex/skills/technical-architect/SKILL.md)
  • Discovery: Available skills are listed in project docs and may also appear in a runtime “## Skills” section (name + description + file path). These are the sources of truth; skill bodies live on disk at the listed paths.
  • Trigger rules: If the user names a skill (with $SkillName or plain text) OR the task clearly matches a skill’s description, you must use that skill for that turn. Multiple mentions mean use them all. Do not carry skills across turns unless re-mentioned.
  • Missing/blocked: If a named skill isn’t in the list or the path can’t be read, say so briefly and continue with the best fallback.
  • How to use a skill (progressive disclosure): 1) After deciding to use a skill, open its SKILL.md. Read only enough to follow the workflow. 2) If SKILL.md points to extra folders such as references/, load only the specific files needed for the request; don’t bulk-load everything. 3) If scripts/ exist, prefer running or patching them instead of retyping large code blocks. 4) If assets/ or templates exist, reuse them instead of recreating from scratch.
  • Description as trigger: The YAML description in SKILL.md is the primary trigger signal; rely on it to decide applicability. If unsure, ask a brief clarification before proceeding.
  • Coordination and sequencing:
    • If multiple skills apply, choose the minimal set that covers the request and state the order you’ll use them.
    • Announce which skill(s) you’re using and why (one short line). If you skip an obvious skill, say why.
  • Context hygiene:
    • Keep context small: summarize long sections instead of pasting them; only load extra files when needed.
    • Avoid deeply nested references; prefer one-hop files explicitly linked from SKILL.md.
    • When variants exist (frameworks, providers, domains), pick only the relevant reference file(s) and note that choice.
  • Safety and fallback: If a skill can’t be applied cleanly (missing files, unclear instructions), state the issue, pick the next-best approach, and continue.