Modernize documentation site with Hakyll and Bulma CSS

.github/workflows/deploy.yml

@@ -0,0 +1,75 @@
+name: Build and Deploy
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Haskell
+        uses: haskell-actions/setup@v2
+        with:
+          ghc-version: '9.4.8'
+          cabal-version: '3.10.2.0'
+
+      - name: Cache Cabal
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.cabal/packages
+            ~/.cabal/store
+            dist-newstyle
+          key: ${{ runner.os }}-cabal-${{ hashFiles('**/*.cabal', '**/cabal.project') }}
+          restore-keys: |
+            ${{ runner.os }}-cabal-
+
+      - name: Cache Hakyll
+        uses: actions/cache@v3
+        with:
+          path: _cache
+          key: ${{ runner.os }}-hakyll-${{ hashFiles('site.hs') }}
+          restore-keys: |
+            ${{ runner.os }}-hakyll-
+
+      - name: Install dependencies
+        run: cabal update && cabal build --only-dependencies
+
+      - name: Build site generator
+        run: cabal build
+
+      - name: Build website
+        run: cabal run site build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: '_site'
+
+  deploy:
+    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -2,3 +2,15 @@
 .*.swp
 _site
 .DS_Store
+
+# Hakyll
+_cache/
+dist/
+dist-newstyle/
+.stack-work/
+site
+*.hi
+*.o
+cabal.project.local
+cabal.project.local~
+.ghc.environment.*

MIGRATION.md

@@ -0,0 +1,245 @@
+# Migration from Jekyll to Hakyll
+
+This document describes the migration of the Cloud Haskell documentation site from Jekyll to Hakyll with Bulma CSS.
+
+## What Changed
+
+### Static Site Generator
+- **Before:** Jekyll (Ruby-based)
+- **After:** Hakyll (Haskell-based)
+
+### CSS Framework
+- **Before:** Bootstrap (older version)
+- **After:** Bulma CSS (modern, responsive)
+
+### Design
+- **Before:** Traditional Bootstrap navbar and layout
+- **After:** Modern design inspired by Tokio.rs and Irmin.org
+  - Hero section on homepage
+  - Feature cards highlighting key capabilities
+  - Responsive sidebar for documentation
+  - Modern color scheme (Nord-inspired)
+  - Improved typography
+  - Better code syntax highlighting
+
+## Directory Structure Changes
+
+### Renamed/Moved
+- `_posts/` → `posts/` (Hakyll convention)
+- `_layouts/` → `old_layouts/` (archived)
+- `_includes/` → `old_includes/` (archived)
+
+### New Files
+```
+site.hs              # Hakyll site generator
+site.cabal           # Cabal package definition
+templates/           # New Bulma-based templates
+  ├── default.html
+  ├── index.html
+  ├── documentation.html
+  ├── tutorial.html
+  ├── post.html
+  ├── blog.html
+  └── page.html
+css/
+  ├── custom.css     # Custom styling
+  └── syntax.css     # Code highlighting
+.github/workflows/
+  └── deploy.yml     # Automated CI/CD
+README-BUILD.md      # Build instructions
+MIGRATION.md         # This file
+Makefile.new         # Build helpers
+```
+
+## Key Features
+
+### Homepage
+- **Hero Section:** Eye-catching header with gradient background
+- **Feature Cards:** Six cards highlighting Cloud Haskell capabilities:
+  - Distributed Computing
+  - Concurrent Processes
+  - Fault Tolerance
+  - Pluggable Transports
+  - Platform Libraries
+  - Type Safety
+- **Recent Posts:** Shows latest 3 blog posts
+- **Call to Action:** Prominent buttons for getting started
+
+### Documentation
+- **Sidebar Navigation:** Organized menu for easy navigation
+  - Getting Started
+  - Core Libraries
+  - Platform Libraries
+  - Network Transports
+  - Tutorials
+  - Resources
+- **Responsive:** Sidebar converts to mobile-friendly menu on small screens
+
+### Blog
+- **Dedicated Blog Page:** Clean listing of all posts
+- **Individual Post Pages:** Improved readability with proper spacing
+- **Tags:** Support for categorizing posts
+
+### Tutorials
+- **Breadcrumb Navigation:** Easy to track location
+- **Info Boxes:** Highlighted sections for important information
+- **Code Highlighting:** Nord-themed syntax highlighting
+
+## Building the Site
+
+### Old Way (Jekyll)
+```bash
+bundle install
+bundle exec jekyll serve
+```
+
+### New Way (Hakyll)
+```bash
+cabal build
+cabal run site build
+cabal run site watch
+```
+
+Or use the Makefile:
+```bash
+make build
+make watch
+```
+
+## Deployment
+
+### Automated via GitHub Actions
+- Builds automatically on push to main/master
+- Deploys to GitHub Pages
+- Uses caching for faster builds
+
+### Manual
+```bash
+make build
+# _site directory contains the generated site
+```
+
+## Content Migration
+
+All existing content has been preserved:
+- ✅ Blog posts (in `posts/`)
+- ✅ Tutorials (in `tutorials/`)
+- ✅ Documentation (`documentation.md`)
+- ✅ Other pages (about, contact, team, wiki)
+- ✅ Static assets (images, PDFs, etc.)
+
+### Markdown Compatibility
+Hakyll uses Pandoc for Markdown processing, which is compatible with Jekyll's Kramdown with additional features.
+
+## Design Elements
+
+### Color Scheme
+```css
+Primary:     #5e81ac (blue)
+Primary Dark: #4c6a8f
+Primary Light: #88c0d0
+Secondary:   #bf616a (red)
+Dark BG:     #2e3440
+Light BG:    #eceff4
+Code BG:     #3b4252
+```
+
+### Typography
+- System fonts for performance and native feel
+- Improved line height (1.7) for readability
+- Better heading hierarchy
+
+### Components
+- Cards with hover effects
+- Smooth scrolling
+- Sticky sidebar navigation
+- Responsive navbar with mobile menu
+- Modern footer with organized links
+
+## Browser Support
+
+The new design uses modern CSS that works in:
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest)
+- Mobile browsers (iOS Safari, Chrome Mobile)
+
+## Performance
+
+### Improvements
+- **No jQuery dependency** (used by old Bootstrap)
+- **Minimal JavaScript** (only navbar toggle)
+- **CDN-hosted Bulma** (cached across sites)
+- **Static generation** (fast page loads)
+
+## Maintenance
+
+### Adding Content
+
+**Blog Post:**
+```markdown
+---
+title: New Post Title
+date: 2024-01-01
+---
+
+Content here...
+```
+
+**Tutorial:**
+Just edit files in `tutorials/` directory.
+
+**Documentation:**
+Edit `documentation.md` or template in `templates/documentation.html`.
+
+### Modifying Design
+
+- **Colors:** Edit `css/custom.css`
+- **Layout:** Edit templates in `templates/`
+- **Navigation:** Edit `templates/default.html`
+
+## Troubleshooting
+
+### Common Issues
+
+**Build fails:**
+- Ensure GHC 8.10+ and Cabal 3.0+ are installed
+- Run `cabal update`
+- Try `cabal clean` then rebuild
+
+**Template errors:**
+- Check all `$variables$` are defined in site.hs contexts
+- Verify template syntax
+
+**Content not appearing:**
+- Check file paths match patterns in site.hs
+- Ensure proper YAML front matter
+
+## Resources
+
+- [Hakyll Documentation](https://jaspervdj.be/hakyll/)
+- [Bulma Documentation](https://bulma.io/documentation/)
+- [Tokio.rs](https://tokio.rs) (design inspiration)
+- [Irmin.org](https://irmin.org) (design inspiration)
+
+## Next Steps
+
+1. ✅ Set up GitHub Pages deployment
+2. Test the site thoroughly
+3. Gather feedback from users
+4. Continue improving documentation
+5. Add more tutorials
+
+## Rollback (if needed)
+
+If you need to revert to Jekyll:
+```bash
+mv old_layouts _layouts
+mv old_includes _includes
+mv posts _posts
+# Use old Gemfile and Jekyll configuration
+```
+
+## Questions?
+
+Open an issue on GitHub or contact the maintainers.

Makefile.new

@@ -0,0 +1,39 @@
+.PHONY: build watch clean rebuild deploy help
+
+# Default target
+help:
+	@echo "Cloud Haskell Documentation Site - Hakyll"
+	@echo ""
+	@echo "Available targets:"
+	@echo "  build    - Build the site generator and website"
+	@echo "  watch    - Start preview server (http://localhost:8000)"
+	@echo "  clean    - Clean generated files"
+	@echo "  rebuild  - Clean and rebuild everything"
+	@echo "  deploy   - Deploy to GitHub Pages"
+	@echo ""
+	@echo "First time setup:"
+	@echo "  cabal build"
+
+# Build the site generator first, then build the site
+build:
+	cabal build
+	cabal run site build
+
+# Watch for changes and serve locally
+watch:
+	cabal build
+	cabal run site watch
+
+# Clean generated files
+clean:
+	cabal run site clean
+	rm -rf _cache _site
+
+# Rebuild from scratch
+rebuild:
+	cabal run site rebuild
+
+# Deploy (builds _site directory)
+deploy: build
+	@echo "Deploy _site directory to your hosting service"
+	@echo "For GitHub Pages, commit and push to main/master branch"