Skip to content

Commit cb0265b

Browse files
thanglequocthanglequoc
authored
Merge pull request #56 from thanglequoc/AddGitHubPage
feat: Add GitHub Pages
2 parents 441459a + e1a6c59 commit cb0265b

35 files changed

Lines changed: 4264 additions & 0 deletions

‎development/github_pages/GITHUB_PAGES_PLAN.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
# Timer Ninja — GitHub Pages Planning Document
2+
3+
## Overview
4+
5+
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.
6+
7+
---
8+
9+
## Decisions
10+
11+
| Decision | Choice |
12+
|---|---|
13+
| **Tech stack** | Jekyll (GitHub Pages native, no build CI needed) |
14+
| **Theme** | Fully custom (no base theme) for max creative control |
15+
| **Page scope** | Multi-page: Landing + User Guide + Examples + Advanced Usage |
16+
| **Navigation** | Sticky top navbar with logo, page links, GitHub link, day/night toggle |
17+
| **Hero style** | Full-screen with animated gradient/particle background + ninja sloth mascot |
18+
| **Code comparison** | Side-by-side panels (Traditional vs Timer Ninja) |
19+
| **Animations** | Rich — parallax hero, scroll-triggered fade/slide, animated trace output, typing code effect |
20+
| **Mascot usage** | Heavy — hero, CTA section, footer, 404 page |
21+
| **Day/night mode** | CSS custom properties + JS toggle, preference saved in localStorage |
22+
| **Primary color** | `#46bfc6` (light blue) with complementary palette |
23+
24+
---
25+
26+
## Design System
27+
28+
### Color Palette
29+
30+
**Light Mode:**
31+
| Token | Value | Usage |
32+
|---|---|---|
33+
| Primary | `#46bfc6` | Brand color, buttons, links, accents |
34+
| Primary Dark | `#3aa3a9` | Hover states |
35+
| Primary Light | `#6dd5db` | Gradients, glow |
36+
| Background | `#ffffff` | Page background |
37+
| Surface | `#f5fafa` | Section backgrounds |
38+
| Text | `#1a2b3c` | Body text |
39+
| Text Muted | `#5a6b7c` | Secondary text |
40+
| Code BG | `#f0f6f6` | Code block backgrounds |
41+
42+
**Dark Mode:**
43+
| Token | Value | Usage |
44+
|---|---|---|
45+
| Primary | `#46bfc6` | Unchanged |
46+
| Primary Light | `#6dd5db` | Highlighted elements |
47+
| Background | `#0d1520` | Page background |
48+
| Surface | `#14202e` | Section backgrounds |
49+
| Text | `#e8f0f2` | Body text |
50+
| Text Muted | `#8fa3b2` | Secondary text |
51+
| Code BG | `#111d2b` | Code block backgrounds |
52+
53+
### Typography
54+
- **Body:** Inter (Google Fonts)
55+
- **Code:** JetBrains Mono (Google Fonts)
56+
57+
---
58+
59+
## Site Structure
60+
61+
```
62+
docs/
63+
├── _config.yml # Jekyll configuration
64+
├── _data/
65+
│ └── navigation.yml # Navbar links
66+
├── _includes/
67+
│ ├── head.html # Meta, fonts, CSS, theme init script
68+
│ ├── navbar.html # Sticky navbar with theme toggle
69+
│ └── footer.html # Footer with mascot
70+
├── _layouts/
71+
│ ├── default.html # Base layout
72+
│ ├── home.html # Landing page layout (includes particles + typing JS)
73+
│ └── docs.html # Documentation layout (sidebar TOC + scrollspy)
74+
├── _sass/
75+
│ ├── _variables.scss # Design tokens, CSS custom properties
76+
│ ├── _base.scss # Reset, typography, global styles
77+
│ ├── _navbar.scss # Sticky nav, hamburger menu
78+
│ ├── _hero.scss # Hero section, float animation
79+
│ ├── _features.scss # Feature cards grid
80+
│ ├── _code.scss # Code panels, trace output, quickstart steps, tabs
81+
│ ├── _docs.scss # Documentation sidebar + content styles
82+
│ ├── _animations.scss # Keyframes, scroll-triggered classes
83+
│ ├── _footer.scss # Footer styles
84+
│ └── _dark-mode.scss # Dark mode overrides
85+
├── assets/
86+
│ ├── css/main.scss # SCSS entry point
87+
│ ├── js/
88+
│ │ ├── theme-toggle.js # Day/night mode + hamburger + nav scroll
89+
│ │ ├── animations.js # IntersectionObserver scroll reveals + tabs + trace
90+
│ │ ├── particles.js # Canvas particle system for hero
91+
│ │ ├── typing-effect.js # Typing animation for code comparison
92+
│ │ └── docs-toc.js # Auto-generated TOC + scrollspy for docs
93+
│ └── images/
94+
│ └── mascot.png # Ninja sloth mascot
95+
├── index.html # Landing page
96+
├── user-guide.md # User Guide (from wiki)
97+
├── examples.md # Examples (from wiki)
98+
├── advanced-usage.md # Advanced Usage (from wiki)
99+
├── 404.html # Custom 404 page
100+
└── Gemfile # Jekyll dependencies
101+
```
102+
103+
---
104+
105+
## Landing Page Sections
106+
107+
1. **Hero** — Full-screen animated gradient with canvas particles, floating mascot, tagline, CTA buttons, version badge
108+
2. **Why Timer Ninja?** — 6 feature cards in responsive grid: One Annotation, Visual Call Tree, Block Tracking, Smart Thresholds, Zero Dependencies, Thread-Safe
109+
3. **Before & After** — Side-by-side code comparison with typing animation: 6 lines of boilerplate → 1 annotation
110+
4. **See It In Action** — Terminal-style trace output with line-by-line reveal animation
111+
5. **Quick Start** — 4-step guide with tabbed Maven/Gradle code blocks
112+
6. **Block Tracking Highlight** — Dedicated showcase of `TimerNinjaBlock.measure()` API
113+
7. **CTA** — Final call-to-action with mascot
114+
115+
---
116+
117+
## Documentation Pages
118+
119+
| Page | Source | Layout |
120+
|---|---|---|
121+
| User Guide | `wiki/User-Guide.md` | `docs` (sidebar TOC) |
122+
| Examples | `wiki/Examples.md` | `docs` (sidebar TOC) |
123+
| Advanced Usage | `wiki/Advanced-Usage.md` | `docs` (sidebar TOC) |
124+
125+
Each page includes:
126+
- Auto-generated sidebar TOC from H2/H3 headings
127+
- Scrollspy highlighting current section
128+
- Previous/Next page navigation
129+
130+
---
131+
132+
## Features
133+
134+
### Day/Night Mode
135+
- Toggle button in navbar (sun/moon icon)
136+
- CSS custom properties for all colors
137+
- Persisted in `localStorage`
138+
- Falls back to `prefers-color-scheme` system preference
139+
- Prevents FOUC with inline `<script>` in `<head>`
140+
141+
### Animations
142+
- **Hero particles** — Canvas-based, 60 translucent circles with connecting lines
143+
- **Scroll reveals** — IntersectionObserver: fade-up, fade-left, fade-right, scale-up
144+
- **Staggered grid** — Feature cards animate in with sequential delays
145+
- **Trace reveal** — Console lines appear one by one (120ms intervals)
146+
- **Typing effect** — Code characters type in sequentially with cursor blink
147+
- **Parallax** — Hero mascot and background shift on scroll
148+
- **Float animation** — Mascot gently bobs up and down
149+
150+
### Responsive
151+
- Navbar collapses to hamburger on mobile (< 768px)
152+
- Feature cards: 3 → 2 → 1 column
153+
- Code panels: side-by-side → stacked
154+
- Docs sidebar hidden on mobile (< 1024px)
155+
156+
---
157+
158+
## Deployment
159+
160+
1. Push `docs/` to `main` branch
161+
2. GitHub Settings → Pages → Source: "Deploy from a branch" → `main` / `/docs`
162+
3. Site available at `https://thanglequoc.github.io/timer-ninja/`
163+
164+
### Local Development
165+
166+
```bash
167+
cd docs
168+
bundle install
169+
bundle exec jekyll serve
170+
# → http://localhost:4000/timer-ninja/
171+
```
172+
173+
---
174+
175+
## Verification Checklist
176+
177+
- [ ] Jekyll builds without errors
178+
- [ ] All 4 pages load correctly
179+
- [ ] Dark/light mode toggles properly
180+
- [ ] localStorage persists theme preference
181+
- [ ] Scroll animations fire on all sections
182+
- [ ] Particle canvas renders in hero
183+
- [ ] Typing effect plays on code comparison
184+
- [ ] Trace output reveals line by line
185+
- [ ] Tab switchers work (Maven/Gradle)
186+
- [ ] Navbar hamburger works on mobile
187+
- [ ] Feature cards grid is responsive
188+
- [ ] Code panels stack on mobile
189+
- [ ] Docs sidebar TOC generates correctly
190+
- [ ] Scrollspy highlights active section
191+
- [ ] Previous/Next page navigation works
192+
- [ ] 404 page renders correctly
193+
- [ ] All links resolve (no broken links)
194+
- [ ] Mascot image loads

‎docs/.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
_site/
2+
.sass-cache/
3+
.jekyll-cache/
4+
.jekyll-metadata
5+
vendor/
6+
Gemfile.lock

‎docs/404.html‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
layout: default
3+
title: "404 — Page Not Found"
4+
permalink: /404.html
5+
---
6+
7+
<section class="section" style="text-align: center; min-height: 60vh; display: flex; align-items: center; justify-content: center; padding-top: var(--navbar-height);">
8+
<div class="container">
9+
<div class="hero__mascot" style="width: 120px; height: 120px; margin: 0 auto 2rem;">
10+
<img src="{{ '/assets/images/mascot.png' | relative_url }}" alt="Timer Ninja mascot">
11+
</div>
12+
<h1 style="font-size: 4rem; margin-bottom: 0.5rem;">
13+
<span class="text-gradient">404</span>
14+
</h1>
15+
<h2 style="font-weight: 600; margin-bottom: 1rem;">This page has vanished like a ninja</h2>
16+
<p style="max-width: 400px; margin: 0 auto 2rem; font-size: 1.1rem;">
17+
The page you're looking for doesn't exist or has been moved.
18+
</p>
19+
<a href="{{ '/' | relative_url }}" class="btn btn--primary">
20+
Back to Home
21+
<span>&rarr;</span>
22+
</a>
23+
</div>
24+
</section>

‎docs/Gemfile‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
source "https://rubygems.org"
2+
3+
gem "github-pages", "~> 232", group: :jekyll_plugins
4+
5+
group :jekyll_plugins do
6+
gem "jekyll-seo-tag", "~> 2.8"
7+
end

‎docs/_config.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
title: Timer Ninja
2+
description: "A sneaky library for Java Method Timing — Track execution time with a single annotation. Zero boilerplate."
3+
url: "https://thanglequoc.github.io"
4+
baseurl: "/timer-ninja"
5+
6+
# Build settings
7+
markdown: kramdown
8+
highlighter: rouge
9+
permalink: pretty
10+
11+
# Sass/SCSS
12+
sass:
13+
sass_dir: _sass
14+
style: compressed
15+
16+
# Plugins
17+
plugins:
18+
- jekyll-seo-tag
19+
20+
# Defaults
21+
defaults:
22+
- scope:
23+
path: ""
24+
type: "pages"
25+
values:
26+
layout: "default"
27+
28+
# Exclude from build
29+
exclude:
30+
- Gemfile
31+
- Gemfile.lock
32+
- README.md
33+
- vendor

‎docs/_data/navigation.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
main:
2+
- title: Home
3+
url: /
4+
- title: User Guide
5+
url: /user-guide/
6+
- title: Examples
7+
url: /examples/
8+
- title: Advanced Usage
9+
url: /advanced-usage/

‎docs/_includes/footer.html‎

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

‎docs/_includes/head.html‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
<meta charset="utf-8">
2+
<meta name="viewport" content="width=device-width, initial-scale=1">
3+
<meta name="theme-color" content="#46bfc6">
4+
5+
<title>{% if page.title %}{{ page.title }} — {{ site.title }}{% else %}{{ site.title }}{% endif %}</title>
6+
7+
<!-- Fonts -->
8+
<link rel="preconnect" href="https://fonts.googleapis.com">
9+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
10+
<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">
11+
12+
<!-- Prism.js Syntax Highlighting -->
13+
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism.min.css" id="prism-light">
14+
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism-tomorrow.min.css" id="prism-dark" disabled>
15+
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/plugins/toolbar/prism-toolbar.min.css">
16+
17+
<!-- CSS -->
18+
<link rel="stylesheet" href="{{ '/assets/css/main.css' | relative_url }}">
19+
20+
<!-- Favicon -->
21+
<link rel="icon" href="{{ '/assets/images/mascot.png' | relative_url }}" type="image/png">
22+
23+
{% seo %}
24+
25+
<!-- Theme init (prevent FOUC) -->
26+
<script>
27+
(function() {
28+
var theme = localStorage.getItem('timer-ninja-theme');
29+
if (!theme) {
30+
theme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
31+
}
32+
document.documentElement.setAttribute('data-theme', theme);
33+
// Sync Prism theme
34+
var lightSheet = document.getElementById('prism-light');
35+
var darkSheet = document.getElementById('prism-dark');
36+
if (lightSheet && darkSheet) {
37+
lightSheet.disabled = (theme === 'dark');
38+
darkSheet.disabled = (theme !== 'dark');
39+
}
40+
})();
41+
</script>

‎docs/_includes/navbar.html‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
<nav class="navbar" id="navbar">
2+
<div class="navbar__inner">
3+
<a href="{{ '/' | relative_url }}" class="navbar__brand">
4+
<img src="{{ '/assets/images/mascot.png' | relative_url }}" alt="Timer Ninja" loading="lazy">
5+
<span>Timer Ninja</span>
6+
</a>
7+
8+
<ul class="navbar__links" id="navLinks">
9+
{% for item in site.data.navigation.main %}
10+
<li>
11+
<a href="{{ item.url | relative_url }}"
12+
class="navbar__link{% if page.url == item.url %} is-active{% endif %}">
13+
{{ item.title }}
14+
</a>
15+
</li>
16+
{% endfor %}
17+
</ul>
18+
19+
<div class="navbar__actions">
20+
<button class="theme-toggle" id="themeToggle" aria-label="Toggle dark mode" title="Toggle dark mode">
21+
<span class="icon-sun">&#9728;&#65039;</span>
22+
<span class="icon-moon">&#127769;</span>
23+
</button>
24+
25+
<a href="https://github.com/thanglequoc/timer-ninja" target="_blank" rel="noopener" class="navbar__github" aria-label="GitHub">
26+
<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>
27+
</a>
28+
29+
<button class="navbar__hamburger" id="navHamburger" aria-label="Menu">
30+
<span></span>
31+
<span></span>
32+
<span></span>
33+
</button>
34+
</div>
35+
</div>
36+
</nav>

0 commit comments

Comments
 (0)