feat: Add GitHub Pages

development/github_pages/GITHUB_PAGES_PLAN.md

@@ -0,0 +1,194 @@
+# Timer Ninja — GitHub Pages Planning Document
+
+## Overview
+
+A Jekyll-based GitHub Pages site serving as both a visually striking landing page and full documentation hub for the Timer Ninja library. Deployed from the `docs/` folder on the `main` branch.
+
+---
+
+## Decisions
+
+| Decision | Choice |
+|---|---|
+| **Tech stack** | Jekyll (GitHub Pages native, no build CI needed) |
+| **Theme** | Fully custom (no base theme) for max creative control |
+| **Page scope** | Multi-page: Landing + User Guide + Examples + Advanced Usage |
+| **Navigation** | Sticky top navbar with logo, page links, GitHub link, day/night toggle |
+| **Hero style** | Full-screen with animated gradient/particle background + ninja sloth mascot |
+| **Code comparison** | Side-by-side panels (Traditional vs Timer Ninja) |
+| **Animations** | Rich — parallax hero, scroll-triggered fade/slide, animated trace output, typing code effect |
+| **Mascot usage** | Heavy — hero, CTA section, footer, 404 page |
+| **Day/night mode** | CSS custom properties + JS toggle, preference saved in localStorage |
+| **Primary color** | `#46bfc6` (light blue) with complementary palette |
+
+---
+
+## Design System
+
+### Color Palette
+
+**Light Mode:**
+| Token | Value | Usage |
+|---|---|---|
+| Primary | `#46bfc6` | Brand color, buttons, links, accents |
+| Primary Dark | `#3aa3a9` | Hover states |
+| Primary Light | `#6dd5db` | Gradients, glow |
+| Background | `#ffffff` | Page background |
+| Surface | `#f5fafa` | Section backgrounds |
+| Text | `#1a2b3c` | Body text |
+| Text Muted | `#5a6b7c` | Secondary text |
+| Code BG | `#f0f6f6` | Code block backgrounds |
+
+**Dark Mode:**
+| Token | Value | Usage |
+|---|---|---|
+| Primary | `#46bfc6` | Unchanged |
+| Primary Light | `#6dd5db` | Highlighted elements |
+| Background | `#0d1520` | Page background |
+| Surface | `#14202e` | Section backgrounds |
+| Text | `#e8f0f2` | Body text |
+| Text Muted | `#8fa3b2` | Secondary text |
+| Code BG | `#111d2b` | Code block backgrounds |
+
+### Typography
+- **Body:** Inter (Google Fonts)
+- **Code:** JetBrains Mono (Google Fonts)
+
+---
+
+## Site Structure
+
+```
+docs/
+├── _config.yml                # Jekyll configuration
+├── _data/
+│   └── navigation.yml         # Navbar links
+├── _includes/
+│   ├── head.html              # Meta, fonts, CSS, theme init script
+│   ├── navbar.html            # Sticky navbar with theme toggle
+│   └── footer.html            # Footer with mascot
+├── _layouts/
+│   ├── default.html           # Base layout
+│   ├── home.html              # Landing page layout (includes particles + typing JS)
+│   └── docs.html              # Documentation layout (sidebar TOC + scrollspy)
+├── _sass/
+│   ├── _variables.scss        # Design tokens, CSS custom properties
+│   ├── _base.scss             # Reset, typography, global styles
+│   ├── _navbar.scss           # Sticky nav, hamburger menu
+│   ├── _hero.scss             # Hero section, float animation
+│   ├── _features.scss         # Feature cards grid
+│   ├── _code.scss             # Code panels, trace output, quickstart steps, tabs
+│   ├── _docs.scss             # Documentation sidebar + content styles
+│   ├── _animations.scss       # Keyframes, scroll-triggered classes
+│   ├── _footer.scss           # Footer styles
+│   └── _dark-mode.scss        # Dark mode overrides
+├── assets/
+│   ├── css/main.scss          # SCSS entry point
+│   ├── js/
+│   │   ├── theme-toggle.js    # Day/night mode + hamburger + nav scroll
+│   │   ├── animations.js      # IntersectionObserver scroll reveals + tabs + trace
+│   │   ├── particles.js       # Canvas particle system for hero
+│   │   ├── typing-effect.js   # Typing animation for code comparison
+│   │   └── docs-toc.js        # Auto-generated TOC + scrollspy for docs
+│   └── images/
+│       └── mascot.png         # Ninja sloth mascot
+├── index.html                 # Landing page
+├── user-guide.md              # User Guide (from wiki)
+├── examples.md                # Examples (from wiki)
+├── advanced-usage.md          # Advanced Usage (from wiki)
+├── 404.html                   # Custom 404 page
+└── Gemfile                    # Jekyll dependencies
+```
+
+---
+
+## Landing Page Sections
+
+1. **Hero** — Full-screen animated gradient with canvas particles, floating mascot, tagline, CTA buttons, version badge
+2. **Why Timer Ninja?** — 6 feature cards in responsive grid: One Annotation, Visual Call Tree, Block Tracking, Smart Thresholds, Zero Dependencies, Thread-Safe
+3. **Before & After** — Side-by-side code comparison with typing animation: 6 lines of boilerplate → 1 annotation
+4. **See It In Action** — Terminal-style trace output with line-by-line reveal animation
+5. **Quick Start** — 4-step guide with tabbed Maven/Gradle code blocks
+6. **Block Tracking Highlight** — Dedicated showcase of `TimerNinjaBlock.measure()` API
+7. **CTA** — Final call-to-action with mascot
+
+---
+
+## Documentation Pages
+
+| Page | Source | Layout |
+|---|---|---|
+| User Guide | `wiki/User-Guide.md` | `docs` (sidebar TOC) |
+| Examples | `wiki/Examples.md` | `docs` (sidebar TOC) |
+| Advanced Usage | `wiki/Advanced-Usage.md` | `docs` (sidebar TOC) |
+
+Each page includes:
+- Auto-generated sidebar TOC from H2/H3 headings
+- Scrollspy highlighting current section
+- Previous/Next page navigation
+
+---
+
+## Features
+
+### Day/Night Mode
+- Toggle button in navbar (sun/moon icon)
+- CSS custom properties for all colors
+- Persisted in `localStorage`
+- Falls back to `prefers-color-scheme` system preference
+- Prevents FOUC with inline `<script>` in `<head>`
+
+### Animations
+- **Hero particles** — Canvas-based, 60 translucent circles with connecting lines
+- **Scroll reveals** — IntersectionObserver: fade-up, fade-left, fade-right, scale-up
+- **Staggered grid** — Feature cards animate in with sequential delays
+- **Trace reveal** — Console lines appear one by one (120ms intervals)
+- **Typing effect** — Code characters type in sequentially with cursor blink
+- **Parallax** — Hero mascot and background shift on scroll
+- **Float animation** — Mascot gently bobs up and down
+
+### Responsive
+- Navbar collapses to hamburger on mobile (< 768px)
+- Feature cards: 3 → 2 → 1 column
+- Code panels: side-by-side → stacked
+- Docs sidebar hidden on mobile (< 1024px)
+
+---
+
+## Deployment
+
+1. Push `docs/` to `main` branch
+2. GitHub Settings → Pages → Source: "Deploy from a branch" → `main` / `/docs`
+3. Site available at `https://thanglequoc.github.io/timer-ninja/`
+
+### Local Development
+
+```bash
+cd docs
+bundle install
+bundle exec jekyll serve
+# → http://localhost:4000/timer-ninja/
+```
+
+---
+
+## Verification Checklist
+
+- [ ] Jekyll builds without errors
+- [ ] All 4 pages load correctly
+- [ ] Dark/light mode toggles properly
+- [ ] localStorage persists theme preference
+- [ ] Scroll animations fire on all sections
+- [ ] Particle canvas renders in hero
+- [ ] Typing effect plays on code comparison
+- [ ] Trace output reveals line by line
+- [ ] Tab switchers work (Maven/Gradle)
+- [ ] Navbar hamburger works on mobile
+- [ ] Feature cards grid is responsive
+- [ ] Code panels stack on mobile
+- [ ] Docs sidebar TOC generates correctly
+- [ ] Scrollspy highlights active section
+- [ ] Previous/Next page navigation works
+- [ ] 404 page renders correctly
+- [ ] All links resolve (no broken links)
+- [ ] Mascot image loads

docs/.gitignore

@@ -0,0 +1,6 @@
+_site/
+.sass-cache/
+.jekyll-cache/
+.jekyll-metadata
+vendor/
+Gemfile.lock

docs/404.html

@@ -0,0 +1,24 @@
+---
+layout: default
+title: "404 — Page Not Found"
+permalink: /404.html
+---
+
+<section class="section" style="text-align: center; min-height: 60vh; display: flex; align-items: center; justify-content: center; padding-top: var(--navbar-height);">
+  <div class="container">
+    <div class="hero__mascot" style="width: 120px; height: 120px; margin: 0 auto 2rem;">
+      <img src="{{ '/assets/images/mascot.png' | relative_url }}" alt="Timer Ninja mascot">
+    </div>
+    <h1 style="font-size: 4rem; margin-bottom: 0.5rem;">
+      <span class="text-gradient">404</span>
+    </h1>
+    <h2 style="font-weight: 600; margin-bottom: 1rem;">This page has vanished like a ninja</h2>
+    <p style="max-width: 400px; margin: 0 auto 2rem; font-size: 1.1rem;">
+      The page you're looking for doesn't exist or has been moved.
+    </p>
+    <a href="{{ '/' | relative_url }}" class="btn btn--primary">
+      Back to Home
+      <span>&rarr;</span>
+    </a>
+  </div>
+</section>

docs/Gemfile

@@ -0,0 +1,7 @@
+source "https://rubygems.org"
+
+gem "github-pages", "~> 232", group: :jekyll_plugins
+
+group :jekyll_plugins do
+  gem "jekyll-seo-tag", "~> 2.8"
+end

docs/_config.yml

@@ -0,0 +1,33 @@
+title: Timer Ninja
+description: "A sneaky library for Java Method Timing — Track execution time with a single annotation. Zero boilerplate."
+url: "https://thanglequoc.github.io"
+baseurl: "/timer-ninja"
+
+# Build settings
+markdown: kramdown
+highlighter: rouge
+permalink: pretty
+
+# Sass/SCSS
+sass:
+  sass_dir: _sass
+  style: compressed
+
+# Plugins
+plugins:
+  - jekyll-seo-tag
+
+# Defaults
+defaults:
+  - scope:
+      path: ""
+      type: "pages"
+    values:
+      layout: "default"
+
+# Exclude from build
+exclude:
+  - Gemfile
+  - Gemfile.lock
+  - README.md
+  - vendor

docs/_data/navigation.yml

@@ -0,0 +1,9 @@
+main:
+  - title: Home
+    url: /
+  - title: User Guide
+    url: /user-guide/
+  - title: Examples
+    url: /examples/
+  - title: Advanced Usage
+    url: /advanced-usage/

docs/_includes/footer.html

@@ -0,0 +1,24 @@
+<footer class="footer">
+  <div class="footer__inner">
+    <div class="footer__mascot">
+      <img src="{{ '/assets/images/mascot.png' | relative_url }}" alt="Timer Ninja mascot" loading="lazy">
+    </div>
+    <p class="footer__tagline">Made with stealth by <strong>Timer Ninja</strong> — A sneaky library for Java Method Timing</p>
+    <ul class="footer__links">
+      <li><a href="{{ '/' | relative_url }}">Home</a></li>
+      <li><a href="{{ '/user-guide/' | relative_url }}">User Guide</a></li>
+      <li><a href="{{ '/examples/' | relative_url }}">Examples</a></li>
+      <li><a href="{{ '/advanced-usage/' | relative_url }}">Advanced Usage</a></li>
+      <li><a href="https://github.com/thanglequoc/timer-ninja" target="_blank" rel="noopener">GitHub</a></li>
+      <li><a href="https://central.sonatype.com/artifact/io.github.thanglequoc/timer-ninja" target="_blank" rel="noopener">Maven Central</a></li>
+    </ul>
+    <p class="footer__copy">&copy; {{ 'now' | date: "%Y" }} Timer Ninja. Released under the Apache License 2.0.</p>
+  </div>
+</footer>
+
+<!-- Back to top button -->
+<button class="back-to-top" id="backToTop" aria-label="Back to top" title="Back to top">
+  <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
+    <polyline points="18 15 12 9 6 15"></polyline>
+  </svg>
+</button>

docs/_includes/head.html

@@ -0,0 +1,41 @@
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="theme-color" content="#46bfc6">
+
+<title>{% if page.title %}{{ page.title }} — {{ site.title }}{% else %}{{ site.title }}{% endif %}</title>
+
+<!-- Fonts -->
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
+
+<!-- Prism.js Syntax Highlighting -->
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism.min.css" id="prism-light">
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism-tomorrow.min.css" id="prism-dark" disabled>
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/plugins/toolbar/prism-toolbar.min.css">
+
+<!-- CSS -->
+<link rel="stylesheet" href="{{ '/assets/css/main.css' | relative_url }}">
+
+<!-- Favicon -->
+<link rel="icon" href="{{ '/assets/images/mascot.png' | relative_url }}" type="image/png">
+
+{% seo %}
+
+<!-- Theme init (prevent FOUC) -->
+<script>
+  (function() {
+    var theme = localStorage.getItem('timer-ninja-theme');
+    if (!theme) {
+      theme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+    }
+    document.documentElement.setAttribute('data-theme', theme);
+    // Sync Prism theme
+    var lightSheet = document.getElementById('prism-light');
+    var darkSheet = document.getElementById('prism-dark');
+    if (lightSheet && darkSheet) {
+      lightSheet.disabled = (theme === 'dark');
+      darkSheet.disabled = (theme !== 'dark');
+    }
+  })();
+</script>

docs/_includes/navbar.html

@@ -0,0 +1,36 @@
+<nav class="navbar" id="navbar">
+  <div class="navbar__inner">
+    <a href="{{ '/' | relative_url }}" class="navbar__brand">
+      <img src="{{ '/assets/images/mascot.png' | relative_url }}" alt="Timer Ninja" loading="lazy">
+      <span>Timer Ninja</span>
+    </a>
+
+    <ul class="navbar__links" id="navLinks">
+      {% for item in site.data.navigation.main %}
+        <li>
+          <a href="{{ item.url | relative_url }}"
+             class="navbar__link{% if page.url == item.url %} is-active{% endif %}">
+            {{ item.title }}
+          </a>
+        </li>
+      {% endfor %}
+    </ul>
+
+    <div class="navbar__actions">
+      <button class="theme-toggle" id="themeToggle" aria-label="Toggle dark mode" title="Toggle dark mode">
+        <span class="icon-sun">&#9728;&#65039;</span>
+        <span class="icon-moon">&#127769;</span>
+      </button>
+
+      <a href="https://github.com/thanglequoc/timer-ninja" target="_blank" rel="noopener" class="navbar__github" aria-label="GitHub">
+        <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"></path></svg>
+      </a>
+
+      <button class="navbar__hamburger" id="navHamburger" aria-label="Menu">
+        <span></span>
+        <span></span>
+        <span></span>
+      </button>
+    </div>
+  </div>
+</nav>