gitea-template/README.md

Gitea Ocean Theme

A beautiful, clean pastel ocean-themed template for Gitea featuring soft blues, rounded corners, and glassmorphism effects. This theme transforms your Gitea instance into a cohesive, modern experience with whale animations and ocean motifs throughout.

✨ Features

• 🌊 Ocean-themed aesthetic – Soft pastel blues (#8CA9FF, #AAC4F5) with cream backgrounds (#FFF8DE)
• 🐋 Animated whale hero – Welcoming landing page with swimming whale animation
• 💎 Glassmorphism design – Rounded corners, semi-transparent cards, subtle shadows
• 📱 Fully responsive – Clean layout adapting to all screen sizes
• 🎨 Cohesive styling – Dashboard, repositories, footer all matching the ocean theme
• ⚡ Modern tech stack – Bootstrap 5.3.3, Font Awesome 6.5.2, Google Fonts (Inter)

📦 What's Included

• custom/templates/home.tmpl – overrides the default landing page with a Bootstrap 5 design
• custom/templates/custom/header.tmpl – injects Bootstrap, Font Awesome, typography, and all ocean theme styles
• custom/templates/custom/body_inner_post.tmpl – adds JavaScript for repository card styling
• custom/templates/custom/footer.tmpl – delivers a multi-column footer with ocean theme styling
• custom/public/css/home.css – additional home page styling

📋 Prerequisites

• Gitea 1.18+ (tested against the current main template structure)
• Access to the custom/ directory on your Gitea host (default /var/lib/gitea/custom when using official packages)

🚀 Installation

1. Stop Gitea (optional but safest):

   sudo rc-service gitea stop
   

2. Copy the theme files:

   sudo rsync -av custom/ /var/lib/gitea/custom/
   

   Adjust the destination path if your APP_DATA_PATH differs.

3. Fix permissions:

   sudo chown -R git:git /var/lib/gitea/custom
   

   Replace git:git with the user/group running your Gitea service.

4. Start or restart Gitea:

   sudo rc-service gitea start
   

5. Bust caches (optional but recommended): add or increment ui.asset_version in app.ini, or clear $GITEA_CUSTOM/public cache if you use a CDN.

🎨 Design Details

Color Palette

• Ocean Blue: #8CA9FF, #AAC4F5 (primary accents)
• Cream Background: #FFF8DE (warm, welcoming base)
• Dark Text: #1e293b, #64748b (readable on light backgrounds)
• Code Blocks: rgba(170, 196, 245, 0.15) (soft ocean background)
• Cards: rgba(255, 255, 255, 0.75) (semi-transparent white)

Styling Highlights

• Rounded corners: 0.75rem - 1rem throughout
• Subtle borders: rgba(140, 169, 255, 0.15)
• Minimal shadows: 0 1px 3px rgba(140, 169, 255, 0.08)
• Smooth transitions: 0.2s ease for hover effects
• Ocean blue accents: Active tabs, hover states, links

✅ Verification Checklist

After copying the files, visit your instance root URL:

• Logged-out visitors should see the hero landing page with CTA buttons, feature highlights and the install checklist.
• Logged-in users should see the "Welcome back" dashboard card with quick action buttons.
• The top navigation bar should render with the glassmorphism background and rounded menu pills, with the announcement banner above it.
• The footer should show the new three-column resource section followed by the standard Gitea footer.

🎯 What Gets Themed

✅ Landing Page – Whale animation hero section
✅ Navbar – Ocean blue with glassmorphism
✅ Dashboard – User switcher, repository cards, sidebar
✅ Repository Pages – Code blocks, tabs, content boxes
✅ Markdown – Clean ocean-themed code styling
✅ Footer – Multi-column layout with ocean gradients

🔧 Troubleshooting

• Styles didn't update – Make sure custom/templates/custom/header.tmpl copied correctly and bump ui.asset_version in app.ini to invalidate the service worker cache.
• CDN blocked or SRI mismatch – If the environment strips query params or modifies assets, host Bootstrap and Font Awesome locally inside custom/public/vendor/ and update the links in custom/templates/custom/header.tmpl (remove the integrity attribute when serving self-hosted copies).
• Repository cards not showing – Clear browser cache with hard refresh (Ctrl+Shift+R / Cmd+Shift+R)
• Markdown underlines appearing – Ensure JavaScript in body_inner_post.tmpl is running correctly

🔄 Updating

To revert to the stock appearance, delete the overrides:

sudo rm -rf /var/lib/gitea/custom/templates/home.tmpl \
            /var/lib/gitea/custom/templates/custom/header.tmpl \
            /var/lib/gitea/custom/templates/custom/body_inner_post.tmpl \
            /var/lib/gitea/custom/templates/custom/footer.tmpl \
            /var/lib/gitea/custom/public/css/home.css

Then restart Gitea.

💡 Customization Tips

• Change ocean colors: Edit the CSS variables in custom/templates/custom/header.tmpl
• Adjust card transparency: Modify rgba(255, 255, 255, 0.75) values for different opacity levels
• Modify whale animation: Edit the animations in home.tmpl or custom/public/css/home.css
• Update footer content: Customize custom/templates/custom/footer.tmpl with your links and information

🙏 Credits

Originally based on sharmavijay86's Gitea Bootstrap 5 Landing Page Theme. Extensively modified and redesigned with:

• Complete ocean-themed color palette (pastel blues and creams)
• Glassmorphism effects and rounded corners throughout
• Whale animation and ocean motifs
• Cohesive repository, dashboard, and footer styling
• Custom JavaScript for dynamic card rendering
• Markdown code block ocean theme styling

---

Happy theming! 🌊🐋