🛠️ Projects with Detailed Pages - Complete Guide

🎉 What Changed

Your Projects section now has full detailed project pages similar to your course articles!

Before:

Projects page showed cards with basic info
External GitHub links for details

After:

Projects page shows cards with "Begin Building" button
Clicking button → Opens detailed project page on your site
Full step-by-step tutorials with code, diagrams, screenshots
GitHub remains as a resource link

📊 New Architecture

Projects System
├── Project Types (projectTypes.ts)
│   └── Defines data structure
├── Project Data Files
│   ├── hardware/
│   │   └── half-adder.ts (example)
│   └── software/
├── Projects Index (projectsIndex.ts)
│   └── Central registry + helper functions
├── Components
│   └── ProjectView.tsx + CSS
└── Pages
    ├── ProjectsPage.tsx (listing)
    └── ProjectDetailPage.tsx (individual project)

📁 File Structure

src/
├── data/
│   └── projects/
│       ├── projectTypes.ts          # TypeScript interfaces
│       ├── projectsIndex.ts         # Central registry
│       ├── PROJECT_TEMPLATE.ts      # Copy this for new projects
│       ├── hardware/
│       │   └── half-adder.ts        # Example project
│       └── software/
│           └── (your projects)
├── components/
│   └── Project/
│       ├── ProjectView.tsx          # Detail page component
│       └── ProjectView.css          # Western theme styles
└── pages/
    └── Projects/
        ├── ProjectsPage.tsx         # Projects listing
        ├── ProjectsPage.css         # Listing styles
        └── ProjectDetailPage.tsx    # Route handler

🎯 Project Data Structure

Complete Project Interface:

interface Project {
  // Basic Info
  id: string;
  slug: string; // URL: /project/[slug]
  title: string;
  category: "hardware" | "software" | "tutorial";
  difficulty: "Beginner" | "Intermediate" | "Advanced";

  // Descriptions
  shortDescription: string; // For cards
  description: string; // Full description (HTML)

  // Learning
  whatYouWillLearn: string[];
  prerequisites: string[];

  // Tech Stack
  technologies: string[];
  toolsRequired: string[];

  // Time
  estimatedTime: string;
  buildSteps: number;

  // Content
  introduction?: string; // Optional intro (HTML)
  steps: ProjectStep[]; // The main tutorial
  screenshots?: ProjectScreenshot[];

  // Help
  commonIssues?: CommonIssue[];
  extensions?: Extension[];

  // Links
  resources: ProjectResource[];
  relatedArticles?: RelatedArticle[];
  relatedProjects?: RelatedProject[];

  // Metadata
  featured?: boolean;
  completedDate?: string;
  lastUpdated: string;
  tags: string[];
  thumbnail?: string;
}

🚀 Creating a New Project

Step 1: Copy Template

cd src/data/projects/hardware  # or software
cp ../PROJECT_TEMPLATE.ts my-project.ts

Step 2: Fill in Basic Info

export const myProject: Project = {
  id: "my-project-id",
  slug: "my-project-slug",
  title: "My Awesome Project",
  category: "hardware",
  difficulty: "Intermediate",

  shortDescription: "Build X to learn Y",
  description: `<p>Detailed description...</p>`,

  // ... continue filling
};

Step 3: Add Learning Outcomes

whatYouWillLearn: [
  "How to design a 4-bit ALU",
  "Understanding arithmetic operations in hardware",
  "Writing efficient testbenches",
  "Debugging HDL code",
],

prerequisites: [
  "Basic knowledge of logic gates",
  "Familiarity with Verilog/SystemVerilog",
  "Installed simulator (ModelSim or Icarus)",
],

Step 4: Write Build Steps

Each step can include:

Text content (HTML)
Code snippets
Diagrams

steps: [
  {
    id: "step-1",
    title: "Understanding the Design",
    content: `
      <h3>What is an ALU?</h3>
      <p>Explanation...</p>

      <h3>Operations We'll Implement</h3>
      <ul>
        <li>Addition</li>
        <li>Subtraction</li>
        <li>AND, OR, XOR</li>
      </ul>
    `,
  },

  {
    id: "step-2",
    title: "Writing the Code",
    content: `<p>Now let's implement it...</p>`,
    codeSnippet: {
      language: "systemverilog",
      filename: "alu.sv",
      title: "4-bit ALU Implementation",
      code: `module alu_4bit (
    input  logic [3:0] a, b,
    input  logic [2:0] op,
    output logic [3:0] result
);
    // Implementation
endmodule`,
    },
  },

  {
    id: "step-3",
    title: "Testing",
    content: `<p>Write testbench...</p>`,
    codeSnippet: {
      language: "systemverilog",
      filename: "alu_tb.sv",
      code: `// Testbench code...`,
    },
  },
],

Step 5: Add Screenshots (Optional)

screenshots: [
  {
    src: "/images/projects/my-project/simulation.png",
    alt: "Simulation waveform",
    caption: "Waveform showing ADD operation",
    width: "800px",
  },
],

Step 6: Add Common Issues

commonIssues: [
  {
    title: "Undefined Module Error",
    problem: "Compiler can't find module definition",
    solution: "Ensure all files are compiled together: iverilog alu.sv alu_tb.sv",
  },
],

Step 7: Add Resources

resources: [
  {
    type: "github",
    title: "Complete Source Code",
    url: "https://github.com/yourusername/my-project",
  },
  {
    type: "article",
    title: "ALU Fundamentals",
    url: "/topic/basic-architecture/alu-design",
  },
],

Step 8: Register Project

// In projectsIndex.ts
import { myProject } from "./hardware/my-project";

export const allProjects: Project[] = [
  halfAdderProject,
  myProject, // ← Add your project
  // ... more projects
];

🎨 Project Page Features

Header Section

Difficulty badge (color-coded)
Category badge with icon
Featured badge (if applicable)
Estimated time & steps
Tags

What You'll Learn

Green checkmark list
Clear learning objectives

Prerequisites

Red warning-style box
Lists required knowledge/tools

Technologies & Tools

Two-column grid
Tech tags for technologies
Bulleted list for tools

Build Steps

Numbered step badges
Rich HTML content
Code snippets with syntax highlighting
Optional diagrams per step
Progress through tutorial

Screenshots

Grid layout
Captions for each image
Professional presentation

Common Issues

Warning-style red box
Problem → Solution format
Helps with debugging

Extensions

Cards with difficulty badges
Ideas to expand the project

Resources

Icon-based cards
GitHub, articles, docs, demos
Internal/external links

🎨 Western Theme Styling

All project pages use your Old West theme:

Visual Elements:

✅ Parchment backgrounds
✅ Wood-textured badges
✅ Rope borders
✅ Torn paper effects
✅ Western typography
✅ Gold/rust accents

Color Coding:

Green - Learning outcomes, success
Red - Prerequisites, warnings, issues
Wood/Gold - Technologies, badges
Rust - Links, actions

📸 Adding Images

Create Directory Structure:

public/
└── images/
    └── projects/
        ├── hardware/
        │   ├── half-adder/
        │   │   ├── thumbnail.png
        │   │   ├── diagram1.png
        │   │   └── waveform.png
        │   └── 4-bit-alu/
        └── software/
            └── attention-gpt/

Use in Project:

screenshots: [
  {
    src: "/images/projects/hardware/half-adder/waveform.png",
    alt: "Simulation waveform showing XOR and AND outputs",
    caption: "Testing all input combinations",
  },
],

Image Guidelines:

Thumbnails: 400x300px
Diagrams: 800x600px or wider
Screenshots: Actual resolution (optimize with TinyPNG)
Format: PNG for diagrams, JPG for photos
File size: < 500KB per image

🔗 URLs

Project Listing:

/#/projects

Individual Project:

/#/project/half-adder-verilog
/#/project/4-bit-alu
/#/project/attention-mechanism

Linking from Articles:

// In your course articles
furtherReading: ["Project: Build a Half Adder - /project/half-adder-verilog"];

💡 Content Writing Tips

Step Titles

✅ Good: "Step 1: Understanding the Half Adder" ❌ Bad: "Step 1"

Content Structure

Each step should have:

Theory - Explain the concept
Practice - Show the code/implementation
Verification - How to test it

Code Comments

// ✅ Good: Explains WHY
assign sum = a ^ b;  // XOR gives sum bit

// ❌ Bad: Explains WHAT (obvious)
assign sum = a ^ b;  // XOR operation

Use Real Examples

// ✅ Good
problem: "Error: 'half_adder' is an undeclared identifier",
solution: "Make sure you're compiling both files: iverilog half_adder.sv half_adder_tb.sv",

// ❌ Bad
problem: "Compilation error",
solution: "Fix your code",

🎯 Example: Half Adder Project

See src/data/projects/hardware/half-adder.ts for a complete example!

Includes:

Full truth table (HTML table)
5 detailed steps
Code snippets for module and testbench
Common issues with solutions
Extensions (full adder, ripple carry adder)
Multiple resource links

🚀 Workflow

Your Typical Project Creation:

Build the project (code, test, debug)
Take screenshots during development
Create diagrams using draw.io/Digital
Copy PROJECT_TEMPLATE.ts
Fill in all sections (use half-adder as reference)
Add to projectsIndex.ts
Test locally: npm start
Build: npm run build
Deploy: npm run deploy

📊 Project Categories

Hardware Projects

Focus: Digital circuits, HDL, FPGA

Examples:

Logic gate implementations
Combinational circuits (adders, multiplexers)
Sequential circuits (flip-flops, counters, registers)
ALU designs
CPU components
Memory controllers

File Location: src/data/projects/hardware/

Software Projects

Focus: Algorithms, simulations, AI/ML

Examples:

Algorithm implementations
Attention mechanisms
Neural networks from scratch
Ray tracers
Compilers/interpreters
Emulators

File Location: src/data/projects/software/

🎓 SEO Benefits

Each project page is SEO-optimized with:

Unique title and description
Keyword-rich content
Structured data
Internal linking (related articles/projects)
External resources

📱 Mobile Responsive

All project pages are fully responsive:

Single column on mobile
Touch-friendly buttons
Readable code snippets
Optimized images

✅ Quality Checklist

Before publishing a project:

🔄 Updating Projects

To update an existing project:

Edit the project file (e.g., half-adder.ts)
Update lastUpdated field
Rebuild and deploy

Changes are immediate - no need to update index!

🎉 Benefits

For Learners:

Complete tutorials on your site (no leaving for GitHub)
Step-by-step guidance with visual aids
Troubleshooting help built-in
Extensions to take learning further

For You:

Content ownership - everything on your domain
SEO value - rich, indexed content
Portfolio showcase - professional presentation
Easy to update - TypeScript files

For Your Site:

Increased engagement - users stay longer
Better SEO - more pages, more keywords
Professional appearance - complete platform
Consistent theme - Western aesthetic throughout

📚 Documentation Files

PROJECT_TEMPLATE.ts - Copy this for new projects
projectTypes.ts - TypeScript interfaces (reference)
half-adder.ts - Complete example project
This Guide - How to use the system

🎨 Customization

Change Theme Colors:

Edit src/components/Project/ProjectView.css:

Learning outcomes: Green tones
Prerequisites: Red/rust tones
Steps: Wood/parchment

Add New Step Types:

Extend ProjectStep interface in projectTypes.ts:

export interface ProjectStep {
  // ... existing fields
  video?: string; // Add video URL
  quiz?: QuizQuestion[]; // Add quiz
}

Your projects section is now a complete, integrated learning platform! 🎓🛠️

Each project is a mini-course with theory, practice, and troubleshooting - all in the Western theme! 🤠

FilesExpand file tree

PROJECTS_DETAILED_PAGES_GUIDE.md

Latest commit

History