Repository Issues & Bug Analysis

Overview

This document provides a comprehensive analysis of potential bugs, issues, deprecated dependencies, and areas for improvement in the repository. Issues are categorized by severity and type to help prioritize fixes.

Critical Issues
High Priority Issues
Medium Priority Issues
Low Priority Issues
Recommendations
Future Maintenance

Critical Issues

1. Deprecated MathJax CDN

Severity: 🔴 Critical
Impact: Math equations may stop rendering
Affected Files: 8 presentation files

Description: Multiple presentations use the deprecated MathJax CDN endpoint https://cdn.mathjax.org/mathjax/latest/MathJax.js, which has been shut down since April 2017.

Affected Files:

talks/lessons.html
talks/thesis.html
talks/eyes_on_bot.html
talks/onto_memes.html
stack/lin-sp-bp.html
stack/jumping_networks.html
stack/adversarial_opinion_dynamics.html
course_slides/ml_centraal/demoday.html

Current Code:

math: {
    mathjax: 'https://cdn.mathjax.org/mathjax/latest/MathJax.js',
    config: 'TeX-AMS_HTML-full'
}

Recommended Fix: Replace with the new CDN:

math: {
    mathjax: 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.9/MathJax.js',
    config: 'TeX-AMS_HTML-full'
}

Or use MathJax 3.x:

// In HTML <head>
<script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

Note: The old CDN may still work due to redirects, but this is not guaranteed.

High Priority Issues

2. Missing Directories Referenced in Docker Compose

Severity: 🟠 High
Impact: Docker Compose build will fail
Affected Files: docker-compose.yml

Description: The docker-compose.yml file references directories that don’t exist in the repository:

./scripts (mapped to /run in container)
./_members (mapped to /data/_members in container)

Current Configuration:

autogen-profiles:
  volumes:
    - ./scripts:/run
    - ./_data:/data/_data
    - ./_members:/data/_members
  working_dir: /run
  command: bash -c "pip install -q pyyaml tqdm && ./autogen_profiles"

Recommended Fix:

Option A: Remove the autogen-profiles service if not needed:

# Comment out or remove the autogen-profiles service
services:
  jekyll:
    image: jekyll/jekyll:3.8
    # ... rest of config

Option B: Create the missing directories and script:

mkdir -p scripts _members
# Create autogen_profiles script if needed

Option C: Add .gitkeep files to preserve empty directories:

mkdir -p scripts _members
touch scripts/.gitkeep _members/.gitkeep

3. Insecure HTTP Links

Severity: 🟠 High
Impact: Mixed content warnings, security vulnerabilities
Affected Files: 15 HTML files

Description: Multiple files contain http:// links instead of https://, which can cause:

Mixed content warnings in browsers
Security vulnerabilities
Broken functionality on HTTPS sites

Affected Files:

talks/lessons.html
talks/eyes_on_bot.html
talks/onto_memes.html
talks/thesis.html
stack/ directory files
course_slides/ml_centraal/demoday.html
And more…

Common Patterns:

<!-- Bad -->
<a href="http://example.com">Link</a>
<img src="http://example.com/image.png">

<!-- Good -->
<a href="https://example.com">Link</a>
<img src="https://example.com/image.png">

Recommended Fix:

Search and replace http:// with https:// where applicable
Verify all external links work with HTTPS
For relative paths, ensure they don’t include protocol

Automated Fix:

# Find all HTTP links in HTML files
grep -r "http://" --include="*.html" .

# Use sed or manual replacement to update to HTTPS

4. Empty Development Configuration

Severity: 🟠 High
Impact: Inconsistent development environment
Affected Files: _config.dev.yml

Description: The _config.dev.yml file exists but is completely empty. This file is referenced in docker-compose.yml:

command: jekyll serve -H 0.0.0.0 -P 4000 --config _config.yml,_config.dev.yml --incremental

Issues:

Jekyll will still work but might show warnings
Defeats the purpose of having a separate dev config
Could cause confusion for developers

Recommended Fix:

Option A: Add development-specific settings:

# _config.dev.yml
# Development-specific overrides
url: "http://localhost:4000"
environment: development

# Enable verbose output
verbose: true

# Disable certain features in development
# google_analytics: ""
# gtag: ""

Option B: Remove the file and update docker-compose.yml:

command: jekyll serve -H 0.0.0.0 -P 4000 --config _config.yml --incremental

Medium Priority Issues

5. Outdated Reveal.js Version

Severity: 🟡 Medium
Impact: Missing features, potential security issues
Affected Files: package.json, all presentation files

Description: The repository uses reveal.js v3.5.0, which was released in 2018. The current version is 4.x (or 5.x), with significant improvements:

Better mobile support
Improved performance
New features and plugins
Security updates

Current Version:

{
  "name": "reveal.js",
  "version": "3.5.0"
}

Recommended Fix:

Caution: Upgrading reveal.js may break existing presentations due to API changes.

Steps:

Test with one presentation first
Review migration guide: https://revealjs.com/upgrading/
Update package.json and node_modules
Update presentation HTML files with new syntax
Test all presentations thoroughly

Major Changes in v4:

New plugin system
Changed configuration options
Updated API methods

6. Staticman Configuration Incomplete

Severity: 🟡 Medium
Impact: Comments feature non-functional
Affected Files: staticman.yml, _config.yml

Description: Staticman is configured but not fully set up:

_config.yml has empty/incomplete staticman section
No repository/branch specified in config
reCAPTCHA configured but not enabled
Comments infrastructure present but likely non-functional

Current Config in _config.yml:

staticman:
  repository :  # Empty!
  branch     :  # Empty!
  endpoint   :  # Empty!

Current Config in staticman.yml:

branch: "master"  # Should be "main" for newer repos
moderation: false
reCaptcha:
  enabled: false

Recommended Fix:

Option A: Complete Staticman setup:

Deploy Staticman instance or use public instance
Fill in repository details in _config.yml
Enable and configure reCAPTCHA
Update branch from “master” to “main”
Test comment submission

Option B: Remove Staticman if not used:

Remove staticman-related includes
Remove staticman configuration files
Remove staticman CSS
Consider alternatives (Disqus, utterances, giscus)

7. Hardcoded Personal Information

Severity: 🟡 Medium
Impact: Privacy concerns, maintenance issues
Affected Files: Multiple presentation files, _config.yml

Description: Personal information (email, Twitter handle, etc.) is hardcoded in multiple places, making updates tedious and error-prone.

Examples:

<!-- In talks/lessons.html -->
<a href="http://twitter.com/alorozco53" target="_blank">
  <i class="fa fa-twitter"></i>@alorozco53
</a>

<!-- Email in _config.yml -->
email: "alorozco53@mila.quebec"

Recommended Fix:

Centralize personal info in _config.yml
Use Jekyll variables in presentations
Create reusable includes for author info

Example:

<!-- Create _includes/author-info.html -->
<a href="" target="_blank">
  @
</a>

8. Missing Alt Text on Images

Severity: 🟡 Medium
Impact: Accessibility issues
Affected Files: Multiple presentation files

Description: Many images in presentations have empty or missing alt attributes, causing accessibility issues for screen readers.

Examples:

<!-- Bad -->
<img src="../img/example.png" width="50%" height="50%" style="border:none;" alt="">

<!-- Good -->
<img src="../img/example.png" width="50%" height="50%" style="border:none;" 
     alt="Deep learning network architecture diagram">

Recommended Fix:

Audit all presentations for images
Add descriptive alt text to all images
Use empty alt=”” only for decorative images
Consider adding captions for complex diagrams

Low Priority Issues

9. Inconsistent Coding Style

Severity: 🟢 Low
Impact: Code maintainability
Affected Files: All HTML and CSS files

Description:

Mixed indentation (tabs vs spaces)
Inconsistent quote usage (single vs double)
Varying HTML formatting
No consistent code formatter

Recommended Fix:

Choose a style guide (e.g., Prettier, StandardJS)
Add .editorconfig file
Set up pre-commit hooks for formatting
Document style guidelines in CONTRIBUTING.md

Example .editorconfig:

root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
indent_style = space
indent_size = 2
trim_trailing_whitespace = true

[*.md]
trim_trailing_whitespace = false

10. Redundant CSS Files

Severity: 🟢 Low
Impact: Performance, maintenance
Affected Files: /css/ directory

Description: Multiple versions of CSS files exist:

bootstrap.css and bootstrap.min.css
reveal.css and reveal.min.css
Source maps (.map files)

Issues:

Larger repository size
Confusion about which file is used
Potential version mismatches

Recommended Fix:

Use only minified versions in production
Add source CSS to .gitignore if generated
Document build process for CSS
Consider using CSS preprocessors (SASS/LESS)

11. Unused Sample Posts

Severity: 🟢 Low
Impact: Repository clutter
Affected Files: /sampleposts/ directory

Description: The /sampleposts/ directory contains 7 sample markdown files that are likely unused and from the Beautiful Jekyll template.

Recommended Fix:

Review sample posts
Delete if not needed
Or move to documentation folder as examples

12. Large Image Files

Severity: 🟢 Low
Impact: Performance, repository size
Affected Files: /img/ directory (211 files)

Description: The repository contains 211 image files. Some may be:

Unoptimized (not compressed)
Larger than necessary for web use
Duplicates or unused

Recommended Fix:

Audit images for actual usage
Compress images with tools like:
- ImageOptim (Mac)
- TinyPNG (Web)
- imagemin (CLI)
Use appropriate formats:
- PNG for graphics/screenshots
- JPEG for photos
- SVG for logos/icons
- WebP for modern browsers
Remove unused images

13. No Error Pages for Presentations

Severity: 🟢 Low
Impact: User experience
Affected Files: N/A (missing files)

Description: If a presentation file is moved or deleted, users get a generic 404 page. There’s no custom error handling for presentations.

Recommended Fix:

Create custom 404 page for presentations
Add redirects for moved presentations
Implement a presentations index page

14. No Testing Infrastructure

Severity: 🟢 Low
Impact: Quality assurance
Affected Files: N/A (missing files)

Description: No automated tests exist for:

Link checking (broken links)
HTML validation
Accessibility testing
Build verification

Recommended Fix:

Add GitHub Actions workflow for CI/CD
Implement link checking with html-proofer
Add accessibility tests with pa11y
Validate HTML with W3C validator

Example GitHub Actions workflow:

# .github/workflows/test.yml
name: Test
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Build site
        uses: actions/jekyll-build-pages@v1
      - name: Check HTML
        uses: chabad360/htmlproofer@master

Recommendations

Immediate Actions (Do First)

Fix MathJax CDN - Critical for presentations with math
Fix Docker Compose - Remove or create missing directories
Update HTTP to HTTPS - Security and functionality

Short-term Actions (This Month)

Populate or remove _config.dev.yml
Audit and fix Staticman configuration
Add alt text to images for accessibility
Create or update CONTRIBUTING.md with coding guidelines

Long-term Actions (Next Quarter)

Consider reveal.js upgrade - Plan and test carefully
Implement testing infrastructure
Optimize images for performance
Clean up unused files
Add comprehensive error handling

Nice-to-Have Improvements

Set up automated dependency updates (Dependabot)
Add comprehensive testing suite
Implement CSS/JS minification pipeline
Create presentation template generator
Add search functionality to presentations
Implement dark mode for presentations
Add analytics to track presentation views

Future Maintenance

Regular Maintenance Tasks

Monthly:

Check for broken links
Review and update dependencies
Test all presentations
Check for security updates

Quarterly:

Audit repository size and clean up
Review and update documentation
Test on different browsers/devices
Update copyright years and info

Annually:

Major dependency updates
Comprehensive security audit
Performance optimization review
Accessibility audit

Monitoring Setup

Consider implementing:

Uptime monitoring - For the live site
Broken link monitoring - Automated checks
Performance monitoring - PageSpeed Insights
Security scanning - Dependabot, Snyk
Analytics - Google Analytics or privacy-focused alternative

Version Control Best Practices

Use semantic versioning for releases
Tag important milestones
Write descriptive commit messages
Use branches for new features
Implement code review process
Keep main branch stable

Documentation Updates

Keep these documents updated:

USAGE.md - Usage instructions
PRESENTATIONS.md - Presentation guide
ISSUES.md - This file
CONTRIBUTING.md - Contribution guidelines (create if missing)
CHANGELOG.md - Version history (create if missing)

Issue Tracking

How to Report Issues

Check if issue already exists in this document
Verify the issue is reproducible
Document steps to reproduce
Include screenshots if applicable
Note your environment (OS, browser, etc.)

Priority Definitions

🔴 Critical: Breaks functionality, requires immediate fix
🟠 High: Significant impact, fix within days
🟡 Medium: Noticeable issue, fix within weeks
🟢 Low: Minor issue, fix when convenient

Issue Status Tracking

Issue	Status	Assigned	Notes
Deprecated MathJax CDN	Open	-	Need to update 8 files
Missing Docker directories	Open	-	Decide on approach
HTTP links	Open	-	Systematic search/replace needed
Empty dev config	Open	-	Quick fix
Outdated reveal.js	Open	-	Requires testing
Staticman setup	Open	-	Decide to fix or remove

Appendix: Useful Commands

Check for Issues

# Find HTTP links
grep -r "http://" --include="*.html" .

# Find deprecated MathJax
grep -r "cdn.mathjax.org/mathjax/latest" --include="*.html" .

# Find images without alt text
grep -r '<img[^>]*alt=""' --include="*.html" .

# Find large images (>500KB)
find ./img -type f -size +500k

# Check for broken links (requires html-proofer)
htmlproofer ./_site --disable-external

# Validate HTML
# Upload to https://validator.w3.org/ or use CLI tool

Fix Common Issues

# Replace HTTP with HTTPS (use with caution!)
find . -name "*.html" -exec sed -i 's|http://|https://|g' {} +

# Remove trailing whitespace
find . -name "*.html" -exec sed -i 's/[[:space:]]*$//' {} +

# Fix line endings (convert to LF)
find . -name "*.html" -exec dos2unix {} +

Last Updated: 2025-11-11
Document Version: 1.0
Maintainer: AlOrozco53
Status: Living Document - Update as issues are discovered/resolved

Repository Issues & Bug Analysis

Overview

Table of Contents

Critical Issues

1. Deprecated MathJax CDN

High Priority Issues

2. Missing Directories Referenced in Docker Compose

3. Insecure HTTP Links

4. Empty Development Configuration

Medium Priority Issues

5. Outdated Reveal.js Version

6. Staticman Configuration Incomplete

7. Hardcoded Personal Information

8. Missing Alt Text on Images

Low Priority Issues

9. Inconsistent Coding Style

10. Redundant CSS Files

11. Unused Sample Posts

12. Large Image Files

13. No Error Pages for Presentations

14. No Testing Infrastructure

Recommendations

Immediate Actions (Do First)

Short-term Actions (This Month)

Long-term Actions (Next Quarter)

Nice-to-Have Improvements

Future Maintenance

Regular Maintenance Tasks

Monitoring Setup

Version Control Best Practices

Documentation Updates

Issue Tracking

How to Report Issues

Priority Definitions

Issue Status Tracking

Appendix: Useful Commands

Check for Issues

Fix Common Issues