timeline-svg/WINDOWS_USAGE.md

Using Timeline SVG on Windows

This guide explains how to use Timeline SVG Generator on Windows after building the distribution in WSL.

Building the Distribution (in WSL)

1. In your WSL terminal, navigate to the project directory:

   cd /home/worsch/timeline-svg
   

2. Build the distribution package:

   make dist-zip
   

   This creates either timeline-svg-dist.zip (if zip is installed) or timeline-svg-dist.tar.gz.

3. The distribution file is now in your project directory and accessible from Windows at:

   \\wsl$\Ubuntu\home\worsch\timeline-svg\timeline-svg-dist.tar.gz
   

   Or if you have the WSL path mounted:

   \\wsl.localhost\Ubuntu\home\worsch\timeline-svg\timeline-svg-dist.tar.gz
   

Transferring to Windows

Option 1: Copy from WSL Location

1. Open Windows Explorer
2. Navigate to \\wsl$\Ubuntu\home\worsch\timeline-svg\
3. Copy timeline-svg-dist.tar.gz (or .zip) to your Windows directory
   • Example: C:\Users\YourName\Documents\timeline-svg\

Option 2: Use Command Line

In WSL terminal:

# Copy to Windows user directory
cp timeline-svg-dist.tar.gz /mnt/c/Users/YourName/Documents/

Or from Windows PowerShell:

# Copy from WSL to Windows
Copy-Item "\\wsl$\Ubuntu\home\worsch\timeline-svg\timeline-svg-dist.tar.gz" -Destination "C:\Users\YourName\Documents\"

Extracting on Windows

If you have a .zip file:

• Right-click the file → "Extract All..."
• Choose destination folder

If you have a .tar.gz file:

• Install 7-Zip (free): https://www.7-zip.org/
• Right-click → 7-Zip → Extract Here (twice - first for .gz, then for .tar)

Running on Windows

Once extracted, you have several options:

Option 1: Use the Batch Script (Easiest)

1. Double-click start-server.bat in the extracted folder
2. A command window will open and your browser will launch automatically
3. The application will be available at http://localhost:8000
4. To stop the server, close the command window or press Ctrl+C

Note: Requires Python to be installed on Windows. Download from https://www.python.org/ if needed.

Option 2: Use Python Directly

1. Open Command Prompt or PowerShell in the extracted folder
2. Run one of these commands:

   python -m http.server 8000
   

   or

   python3 -m http.server 8000
   

3. Open your browser to http://localhost:8000

Option 3: Use Node.js http-server

If you have Node.js installed:

npx http-server -p 8000

Option 4: Direct File Access (Limited)

You can open index.html directly in your browser, but due to CORS restrictions:

• ✅ UI will load
• ❌ Auto-loading of example projects won't work
• ❌ CSV/template files must be manually uploaded

Recommendation: Use a local server (Option 1-3) for full functionality.

Working with Your Own Projects

Creating a New Project

1. Copy one of the example folders (e.g., example\)
2. Rename it to your project name
3. Edit the files:
   • project.json - Configure field mappings and settings
   • sample.csv - Replace with your timeline data
   • style.css - Customize colors and fonts
   • template-v2.svg - Design your timeline layout

Loading Your Project

You have two options:

Option 1: Load Entire Project Folder (Recommended)

1. Click "📂 Load Project Folder"
2. Select your project folder (e.g., example\ or your custom project folder)
3. All files (project.json, CSV, SVG, CSS) will be loaded automatically
4. Timeline generates immediately

This is the easiest method - one click loads everything!

Option 2: Load Files Individually

1. Click "📁 Load" next to "Project Configuration"
2. Select your project.json file
3. Manually upload CSV, CSS, and SVG files using the respective buttons

Note: Due to browser security, uploading just project.json won't automatically load the other files from the same directory. Use the folder picker (Option 1) for automatic loading.

File Paths on Windows

The application uses forward slashes (/) in URLs, which work correctly in browsers on Windows. You don't need to change anything in the code.

Example project.json on Windows:

{
  "name": "My Timeline",
  "dataSource": "sample.csv",
  "stylesheet": "style.css",
  "svgTemplate": "template-v2.svg"
}

These relative paths work the same way on Windows and Linux when served via HTTP.

Troubleshooting on Windows

"Python not found"

Install Python:

1. Download from https://www.python.org/downloads/
2. Important: Check "Add Python to PATH" during installation
3. Restart Command Prompt
4. Try running start-server.bat again

Port 8000 already in use

Change the port in start-server.bat:

• Edit the file with Notepad
• Change 8000 to another port like 8080 or 3000
• Update the browser URL accordingly

Files not loading (CORS errors)

• Make sure you're using the local server (not opening index.html directly)
• Check that all project files are in the same directory structure
• Look at browser console (F12) for specific error messages

Browser doesn't open automatically

If start http://localhost:8000 doesn't work:

• Manually open your browser
• Navigate to http://localhost:8000
• The application should load normally

Syncing Between WSL and Windows

If you want to develop in WSL but test on Windows:

Option 1: Work in WSL-accessible location

Develop in a Windows folder accessed from WSL:

cd /mnt/c/Users/YourName/Documents/timeline-svg

Changes made in WSL are immediately visible in Windows.

Option 2: Rebuild distribution after changes

1. Make changes in WSL
2. Rebuild: make dist-zip
3. Copy to Windows
4. Extract and test

Option 3: Use the Windows folder directly

The distribution folder can be used from both environments:

• WSL: cd /mnt/c/Users/YourName/Documents/timeline-svg/dist
• Windows: C:\Users\YourName\Documents\timeline-svg\dist

Performance Notes

• The application runs entirely in the browser (no backend needed)
• Performance is identical on Windows and Linux
• Large CSV files (>1000 rows) may take a few seconds to process
• SVG generation is client-side and depends on your browser/CPU speed

Additional Resources

• See README.md for application overview and features
• See TEMPLATE_V2_GUIDE.md for template customization
• See TROUBLESHOOTING.md for common issues and solutions

Questions or Issues?

If you encounter problems specific to Windows:

1. Check the browser console (F12 → Console tab) for error messages
2. Verify Python is installed and in PATH
3. Try the alternative server options above
4. Check file permissions (extracted files should be readable)