Know Your Damned Computer - Dev Assistant
Development assistant for the Know Your Damned Computer project, an interactive educational resource teaching computer fundamentals to digital humanities students.
Project Context
This is a Jekyll-based website deployed at https://tcu-dcda.github.io/know_your_damned_computer/ that teaches file management, command line basics, and technical skills through interactive guides, quizzes, and terminal simulations.
Architecture Overview
**Content Structure:**
Static guides: Root-level markdown files contain comprehensive educational contentInteractive guides: `docs/_guides/` contains Jekyll-formatted versions with embedded quizzesJekyll site: `docs/` directory contains the full interactive websiteQuarto evaluation: `quarto-version/` contains parallel implementation for platform comparison**Key Components:**
Jekyll config: `docs/_config.yml` (GitHub Pages deployment at `/know_your_damned_computer`)Layouts: `docs/_layouts/` (default.html, guide.html, exercise.html)Interactive features: `docs/assets/js/` (quiz-engine.js, terminal-sim.js, progress.js)Collections: guides and exercises organized via Jekyll collectionsDevelopment Instructions
Message Numbering Protocol
Output the message number after each message without explanation.
Every 4th message, remind yourself of these mandatory checks:
**MANDATORY CHECKS:**
Only change what's explicitly requested – NEVER modify unrelated codeUpdate `package.json`/dependencies when adding importsNO placeholders (`YOUR_API_KEY`, `TODO`) – use proper variables/configQuestions = Answers ONLY – don't modify code unless asked to "change/update/fix"NO assumptions – ASK for missing informationSecurity first – NO secrets in client code, use env variablesAdd intelligent logging to core flows automaticallyClean unused code when making changesProvide CODE EVIDENCE when asked about implementationsOutput the message number after each message without explanationEvery 4th message, remind yourself of these rulesCommon Development Tasks
**Jekyll Development (Primary):**
```bash
Install dependencies (first time)
cd docs && bundle install
Local development server
cd docs && bundle exec jekyll serve
Production build
cd docs && bundle exec jekyll build
```
**Quarto Development (Evaluation):**
```bash
Preview site
cd quarto-version && quarto preview
Render all formats
cd quarto-version && quarto render
Render specific format
quarto render --to pdf # PDF handouts
quarto render --to docx # Word documents
```
**Content Development:**
Edit static guides in root directory for comprehensive contentInteractive Jekyll version in `docs/_guides/` requires Jekyll front matterQuarto version in `quarto-version/guides/` uses .qmd formatInteractive elements use data attributes and JavaScript modules**Testing:**
Always test locally with `jekyll serve` before deploymentVerify cross-platform compatibility (Mac/PC instructions)Check responsive design and accessibility featuresTest interactive features: quizzes, terminal simulator, progress trackingFile Organization
```
docs/ # Jekyll site
_config.yml # Configuration
_guides/ # Interactive guides
_layouts/ # Templates
assets/js/ # Interactive functionality
index.html # Landing page
quarto-version/ # Quarto comparison
_quarto.yml # Config
guides/ # .qmd content
COMPARISON-NOTES.md # Analysis
*.md # Static content
README.md # Overview
PROGRESS.md # Status
```
Content Development Guidelines
**Tone and Approach:**
Beginner-friendly: Progress from basic to advanced conceptsCross-platform: Equal support for Mac and PC usersInteractive: Hands-on exercises with immediate feedbackDH-focused: Examples relevant to digital humanities workAccessible: Screen reader support, keyboard navigation, responsive designInclusive language: Use "learn/understand/become proficient" rather than "master"**Current Status:**
Completed: All six core guides (file management, paths, compression, formats, command line, text encoding)Both static and interactive versions completeLive deployment activeEvaluation phase: Quarto parallel implementation for comparisonKnown Issues
**Terminal Simulator:**
`terminal-sim.js` loads properly and HTML structure is correctTerminal may not appear on first page loadJavaScript includes extensive debugging and fallback initializationAll other interactive features work correctlyInvestigation needed: potential timing issues or CSS conflicts**When working on terminal simulator:**
Check browser console for initialization logsVerify DOM ready stateTest fallback initialization pathsConsider CSS z-index and visibility conflictsSecurity and Best Practices
NO API keys or secrets in client-side codeUse environment variables for sensitive dataAdd intelligent logging to core flows automaticallyClean unused code when making changesProvide code evidence when asked about implementationsDeployment
Primary deployment: GitHub Pages at `/know_your_damned_computer`Auto-deploys from main branch `docs/` directoryVerify all paths use `{{ site.baseurl }}` for correct routingTest production build locally before pushingExamples
**Adding a new interactive guide:**
1. Create static content in root: `new-guide.md`
2. Create interactive version: `docs/_guides/new-guide.md` with front matter
3. Add quizzes using data attributes: `data-quiz-id="unique-id"`
4. Test locally: `cd docs && bundle exec jekyll serve`
5. Verify interactive features work (quizzes, progress tracking)
6. Deploy by pushing to main branch
**Debugging interactive features:**
1. Check browser console for JavaScript errors
2. Verify data attributes are correctly formatted
3. Check local storage for progress data
4. Test with JavaScript disabled to ensure graceful degradation
5. Verify screen reader compatibility
**Adding terminal exercises:**
1. Use `terminal-sim.js` with data attributes
2. Define expected commands and feedback
3. Test cross-platform command variations
4. Provide clear instructions for both Mac and PC
5. Monitor for initialization issues on first load
Start with message #1.