Add docs for URL feature

spier · spier · commit ec547b4a82b3 · 2025-11-16T21:53:41.000+01:00
diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@ An advent calendar for 2025, to highlight InnerSource patterns that need your he
 
 - create content for the calendar / e.g. pick patterns from [this list](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues/772) that could be improved
 - (optional) hide days until that day is reached i.e. only once we reach December 1st, 2025 the 1st "door" in the advent calendar can be opened
-- (optional) create individual URLs for each day (so that we can share individual days on social media etc)
+- **(done)** create individual URLs for each day (so that we can share individual days on social media etc)
 
 ## Assessment for my use case
 
diff --git a/docs/IMPLEMENTATION-NOTES.md b/docs/IMPLEMENTATION-NOTES.md
@@ -0,0 +1,121 @@
+# Implementation Summary: Individual URLs for Each Day
+
+## What Was Changed
+
+### Modified Files
+1. **`js/main2.js`** - Added URL hash functionality
+
+### New Files Created
+1. **`URL-SHARING.md`** - Documentation on how to use the new URL feature
+2. **`test-links.html`** - Demo page to test direct links to each day
+
+## Key Features Implemented
+
+### 1. URL Hash Support
+Each day now has a unique URL using hash fragments:
+- Day 1: `index.html#day-1`
+- Day 2: `index.html#day-2`
+- Day 3: `index.html#day-3`
+- ...and so on
+
+### 2. Auto-Open on Page Load
+When someone visits a URL with a hash (e.g., `index.html#day-5`), the calendar automatically opens to that specific day.
+
+### 3. URL Updates on Click
+When you click a day, the browser URL automatically updates to include the day's hash, making it easy to copy and share.
+
+### 4. Browser Navigation Support
+The browser's back and forward buttons work correctly:
+- Back button returns to the calendar view
+- Forward button opens the day again
+
+### 5. Clean Back Navigation
+When clicking the back arrow in the calendar, the URL hash is cleared, returning to the base URL.
+
+## Technical Implementation Details
+
+### Changes to `main2.js`:
+
+1. **Added global variable** to store calendar instance:
+   ```javascript
+   calendarInstance;
+   ```
+
+2. **Created `checkURLHash()` function**:
+   - Reads the URL hash on page load
+   - Parses the day number
+   - Automatically opens the corresponding day if valid
+
+3. **Modified `init()` function**:
+   - Calls `checkURLHash()` after layout
+   - Adds event listener for `hashchange` events (browser navigation)
+
+4. **Updated `layout()` function**:
+   - Stores the Calendar instance in `calendarInstance` variable
+
+5. **Enhanced click handler**:
+   - Updates URL hash using `window.history.pushState()`
+   - Format: `#day-N` where N is the 1-based day number
+
+6. **Enhanced back button handler**:
+   - Clears the URL hash when returning to calendar view
+   - Uses `window.history.pushState()` to update URL
+
+## How to Use
+
+### For End Users:
+1. Open the calendar
+2. Click any active day
+3. The URL in your browser will update (e.g., `index.html#day-3`)
+4. Copy and share that URL
+5. Anyone who visits that URL will see that specific day automatically opened
+
+### For Developers:
+You can create direct links in your HTML or markdown:
+```html
+<a href="index.html#day-1">Check out Day 1!</a>
+```
+
+### For Social Media/Marketing:
+Share complete URLs:
+```
+https://yourdomain.com/advent-calendar/index.html#day-5
+```
+
+## Testing
+
+### Test Page
+Open `test-links.html` in your browser to see all direct links and test them.
+
+### Manual Testing Steps:
+1. Open `index.html` in a browser
+2. Click on day 5 - URL should change to `index.html#day-5`
+3. Refresh the page - Day 5 should open automatically
+4. Click the back arrow - URL should change back to `index.html`
+5. Use browser back button - Should return to day 5
+6. Test with a direct link: `index.html#day-3`
+
+## Browser Compatibility
+Works in all modern browsers that support:
+- `window.location.hash`
+- `window.history.pushState()`
+- `addEventListener('hashchange')`
+
+This includes: Chrome, Firefox, Safari, Edge, and all mobile browsers.
+
+## Advantages of This Approach
+
+1. **No Server Configuration**: Works with static hosting (GitHub Pages, Netlify, etc.)
+2. **No File Duplication**: Still uses a single HTML file
+3. **SEO Friendly**: Hash fragments are indexed by search engines
+4. **Social Media Friendly**: URLs are shareable on all platforms
+5. **Backwards Compatible**: Works alongside existing functionality
+6. **Performance**: No additional HTTP requests needed
+
+## Future Enhancements (Optional)
+
+If you want to make this even better, you could:
+1. Add Open Graph meta tags that update based on the day opened
+2. Implement analytics tracking for which days are most popular
+3. Add a "Share" button that copies the current day's URL to clipboard
+4. Create a QR code generator for each day's URL
diff --git a/docs/QUICK-REFERENCE.md b/docs/QUICK-REFERENCE.md
@@ -0,0 +1,100 @@
+# Quick Reference: URL Sharing
+
+## 📋 Quick Links
+
+### Active Days (Ready to Share)
+```
+index.html#day-1   → Welcome
+index.html#day-2   → Code of Conduct
+index.html#day-3   → Balancing Openness and Security
+index.html#day-4   → InnerSource Ambassadors
+index.html#day-5   → Live Freely
+index.html#day-6   → Tolerable Planet
+index.html#day-7   → Normal
+index.html#day-8   → Superhero
+index.html#day-9   → New Weariness
+index.html#day-10  → The Sinner
+index.html#day-11  → Intellectual Wealth
+index.html#day-12  → Limiting Principle
+index.html#day-13  → Quaintly Free
+index.html#day-14  → On A Level
+index.html#day-15  → Experiences
+index.html#day-16  → Entrenched
+index.html#day-17  → Happiness
+index.html#day-18  → Working Jobs
+index.html#day-19  → Spending Billions
+index.html#day-20  → Principle Of Having
+index.html#day-21  → Enemies
+index.html#day-22  → Better World
+index.html#day-23  → Coming soon
+index.html#day-24  → Coming soon
+index.html#day-25  → Coming soon
+```
+
+## 🚀 How It Works
+
+1. **Click a day** → URL updates automatically
+2. **Copy the URL** → Share it anywhere
+3. **Someone clicks** → That day opens automatically
+
+## ✅ What Works
+
+- ✅ Direct links to any day
+- ✅ Browser back/forward buttons
+- ✅ URL sharing on social media
+- ✅ Bookmarking specific days
+- ✅ Works with all browsers
+- ✅ No server configuration needed
+
+## 📱 Social Media Tips
+
+**Twitter/X:**
+```
+Check out Day 5 of our #InnerSource Patterns Advent Calendar! 🎄
+https://yourdomain.com/index.html#day-5
+```
+
+**LinkedIn:**
+```
+Discover InnerSource patterns this December! 
+Today's focus: Day 3 - Balancing Openness and Security
+https://yourdomain.com/index.html#day-3
+```
+
+**Email:**
+```
+Subject: Day 7 of InnerSource Patterns Advent Calendar
+
+Click here to see today's pattern:
+https://yourdomain.com/index.html#day-7
+```
+
+## 🔗 Creating Links in HTML
+
+```html
+<!-- Simple link -->
+<a href="index.html#day-1">Day 1</a>
+
+<!-- With custom text -->
+<a href="index.html#day-5">Read today's pattern</a>
+
+<!-- In a button -->
+<button onclick="window.location.href='index.html#day-10'">
+  Go to Day 10
+</button>
+```
+
+## 🧪 Testing
+
+1. Open `test-links.html` to see all links
+2. Click any link to test
+3. Verify URL changes
+4. Test browser back button
+5. Refresh and verify day stays open
+
+## 💡 Pro Tips
+
+- Share a different day each day of December
+- Use short URLs (bit.ly, etc.) for social media
+- Include the day number in your social posts
+- Create a "Day of the Week" schedule
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,3 @@
+These files were added when creating the individual URLs for each day.
+
+You might have to move `test-links.html` back to the root of this repo for it to work.
diff --git a/docs/URL-SHARING.md b/docs/URL-SHARING.md
@@ -0,0 +1,47 @@
+# URL Sharing Feature
+
+## Overview
+Each day in the advent calendar now has its own unique URL that can be shared directly.
+
+## URL Format
+To link to a specific day, use the following URL format:
+```
+index.html#day-N
+```
+
+Where `N` is the day number (1-25).
+
+## Examples
+- Day 1 (Welcome): `index.html#day-1`
+- Day 2 (Code of Conduct): `index.html#day-2`
+- Day 3 (Balancing Openness and Security): `index.html#day-3`
+- Day 4 (InnerSource Ambassadors): `index.html#day-4`
+- ...and so on
+
+## Features
+1. **Direct Links**: Share a specific day by copying the URL from your browser
+2. **Auto-Open**: When someone clicks a day-specific link, that day automatically opens
+3. **Browser Navigation**: The browser's back/forward buttons work as expected
+4. **Shareable**: Perfect for social media, emails, or documentation
+
+## Usage
+
+### For Users
+1. Click on any active day in the calendar
+2. The URL will automatically update to include `#day-N`
+3. Copy and share that URL with others
+4. When they visit the URL, that specific day will open automatically
+
+### For Developers/Marketers
+Create direct links to specific days:
+```html
+<a href="index.html#day-1">Check out Day 1!</a>
+<a href="index.html#day-5">See Day 5</a>
+```
+
+## Technical Details
+- Uses URL hash fragments (`#day-N`)
+- Works with static hosting (GitHub Pages, etc.)
+- No server-side configuration required
+- Maintains single-file architecture
+- Supports browser history (back/forward buttons)
diff --git a/docs/test-links.html b/docs/test-links.html

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+These files were added when creating the individual URLs for each day.`
	`2`	`+`
	`3`	+You might have to move `test-links.html` back to the root of this repo for it to work.