# Feature Enhancements Specification **Version:** 1.0 **Date:** January 2026 **Status:** Approved for Development ## Implementation Progress ### Phase 3: Organization Public Profile Page - COMPLETED (January 2026) **New Files Created:** - `models/organization/org_pinned.go` - Pinned repos and groups models - `models/organization/org_profile.go` - Public members and org stats - `models/migrations/v1_26/v326.go` - Database migration for pinned tables - `services/org/pinned.go` - Service layer for cross-model operations - `routers/api/v1/org/pinned.go` - API endpoints for pinned repos/groups - `routers/api/v1/org/profile.go` - API endpoints for org overview **Files Modified:** - `models/migrations/migrations.go` - Added migration 326 - `modules/structs/org.go` - Added API structs for pinned repos, groups, members - `routers/api/v1/api.go` - Registered new API routes - `routers/web/org/home.go` - Enhanced to load pinned repos, groups, members - `templates/org/home.tmpl` - Added pinned repos and public members sections - `options/locale/locale_en-US.json` - Added locale strings **API Endpoints Added:** - `GET /api/v1/orgs/{org}/overview` - Get organization overview - `GET /api/v1/orgs/{org}/pinned` - List pinned repositories - `POST /api/v1/orgs/{org}/pinned` - Pin a repository - `DELETE /api/v1/orgs/{org}/pinned/{repo}` - Unpin a repository - `PUT /api/v1/orgs/{org}/pinned/reorder` - Reorder pinned repos - `GET /api/v1/orgs/{org}/pinned/groups` - List pinned groups - `POST /api/v1/orgs/{org}/pinned/groups` - Create pinned group - `PUT /api/v1/orgs/{org}/pinned/groups/{id}` - Update pinned group - `DELETE /api/v1/orgs/{org}/pinned/groups/{id}` - Delete pinned group - `GET /api/v1/orgs/{org}/public_members/roles` - List public members with roles --- ### Phase 4: Gitea Pages Foundation - COMPLETED (January 2026) **New Files Created:** - `models/repo/pages.go` - Pages domain and config models - `models/migrations/v1_26/v327.go` - Database migration for pages tables - `modules/pages/config.go` - Landing.yaml configuration parser - `modules/structs/repo_pages.go` - API structs for pages - `services/pages/pages.go` - Pages service layer - `routers/api/v1/repo/pages.go` - API endpoints for pages management - `routers/web/pages/pages.go` - Web router for serving landing pages - `routers/web/repo/setting/pages.go` - Repository settings page for Pages - `templates/pages/simple.tmpl` - Simple landing page template - `templates/pages/documentation.tmpl` - Documentation template - `templates/pages/product.tmpl` - Product landing template - `templates/pages/portfolio.tmpl` - Portfolio/gallery template - `templates/pages/header.tmpl` - Pages header partial - `templates/pages/footer.tmpl` - Pages footer partial - `templates/repo/settings/pages.tmpl` - Pages settings UI template **Files Modified:** - `models/migrations/migrations.go` - Added migration 327 - `routers/api/v1/api.go` - Registered pages API routes - `routers/web/web.go` - Added pages routes and import - `templates/repo/settings/navbar.tmpl` - Added Pages link to settings nav - `options/locale/locale_en-US.json` - Added Pages locale strings **Web Routes Added:** - `GET /{username}/{reponame}/pages` - View landing page - `GET /{username}/{reponame}/pages/assets/*` - Serve page assets - `GET /{username}/{reponame}/settings/pages` - Pages settings - `POST /{username}/{reponame}/settings/pages` - Update pages settings **API Endpoints Added:** - `GET /api/v1/repos/{owner}/{repo}/pages` - Get pages configuration - `PUT /api/v1/repos/{owner}/{repo}/pages` - Update pages configuration - `DELETE /api/v1/repos/{owner}/{repo}/pages` - Disable pages - `GET /api/v1/repos/{owner}/{repo}/pages/domains` - List custom domains - `POST /api/v1/repos/{owner}/{repo}/pages/domains` - Add custom domain - `DELETE /api/v1/repos/{owner}/{repo}/pages/domains/{domain}` - Remove domain - `POST /api/v1/repos/{owner}/{repo}/pages/domains/{domain}/verify` - Verify domain **Features Implemented:** - Database models for PagesDomain and PagesConfig - YAML configuration parser for `.gitea/landing.yaml` - 4 landing page templates (simple, documentation, product, portfolio) - Custom domain support with verification tokens - SSL status tracking (pending actual Let's Encrypt integration) - README rendering on landing pages - Asset serving from repository - Repository settings UI for pages management - Enable/disable pages toggle - Template selection dropdown - Custom domain management with DNS verification instructions **Future Enhancements:** - Let's Encrypt SSL certificate integration - Subdomain-based routing (e.g., repo.owner.pages.domain.com) - Search functionality for documentation template - Analytics integration --- ### Phase 5: Enhanced Wiki System with V2 API - COMPLETED (January 2026) **New Files Created:** - `models/repo/wiki_ai.go` - WikiIndex model for full-text search - `models/migrations/v1_26/v328.go` - Database migration for wiki_index table - `modules/structs/repo_wiki_v2.go` - V2 API structs for wiki endpoints - `services/wiki/wiki_index.go` - Wiki indexing service (search, graph, stats) - `routers/api/v2/wiki.go` - V2 wiki API endpoints - `docs/phase5-ai-wiki-spec.md` - Phase 5 specification document **Files Modified:** - `models/migrations/migrations.go` - Added migration 328 - `routers/api/v2/api.go` - Registered v2 wiki routes - `modules/errors/codes.go` - Added wiki-related error codes **V2 API Endpoints Added:** - `GET /api/v2/repos/{owner}/{repo}/wiki/pages` - List wiki pages with metadata - `GET /api/v2/repos/{owner}/{repo}/wiki/pages/{pageName}` - Get page with content & links - `POST /api/v2/repos/{owner}/{repo}/wiki/pages` - Create wiki page - `PUT /api/v2/repos/{owner}/{repo}/wiki/pages/{pageName}` - Update wiki page - `DELETE /api/v2/repos/{owner}/{repo}/wiki/pages/{pageName}` - Delete wiki page - `GET /api/v2/repos/{owner}/{repo}/wiki/search` - Full-text search - `GET /api/v2/repos/{owner}/{repo}/wiki/graph` - Link relationship graph - `GET /api/v2/repos/{owner}/{repo}/wiki/stats` - Wiki statistics and health - `GET /api/v2/repos/{owner}/{repo}/wiki/pages/{pageName}/revisions` - Page history **Features Implemented:** - Full-text search across wiki pages using WikiIndex table - JSON content (not base64 like v1), with HTML rendering - Link extraction from markdown content (wiki-style and markdown links) - Link graph visualization (nodes and edges) - Incoming/outgoing link tracking - Wiki health metrics (orphaned pages, dead links, outdated pages, short pages) - Word count and statistics - Full CRUD operations for external tools/plugins - Designed for AI plugin integration (structured data for .NET AI function calling) **V2 API Structs:** - WikiPageV2, WikiCommitV2, WikiAuthorV2 - WikiPageListV2, WikiSearchResultV2, WikiSearchResponseV2 - WikiGraphV2, WikiGraphNodeV2, WikiGraphEdgeV2 - WikiStatsV2, WikiHealthV2 - WikiOrphanedPageV2, WikiDeadLinkV2, WikiOutdatedPageV2, WikiShortPageV2 - CreateWikiPageV2Option, UpdateWikiPageV2Option, DeleteWikiPageV2Option **Error Codes Added:** - WIKI_PAGE_NOT_FOUND - WIKI_PAGE_ALREADY_EXISTS - WIKI_RESERVED_NAME - WIKI_DISABLED **Design Decisions:** - V2 API separate from v1 to avoid interference - No built-in AI features - designed for external plugin integration - WikiIndex table for search (simplified from original AI-centric design) - Content hash for efficient change detection - Background indexing for performance --- --- ## Table of Contents 1. [Organization Public Profile Page](#1-organization-public-profile-page) 2. [Repository Landing Pages (Gitea Pages)](#2-repository-landing-pages-gitea-pages) 3. [Database Schema Changes](#3-database-schema-changes) 4. [API Endpoints](#4-api-endpoints) 5. [Implementation Phases](#5-implementation-phases) --- ## 1. Organization Public Profile Page ### Overview A new **Overview** tab becomes the default landing page for organizations, replacing the Repositories tab as the first view. This page showcases the organization's identity, featured projects, and public members. ### Tab Structure ``` [Overview] [Repositories] [Projects] [Packages] [People] [Settings] ↑ DEFAULT ``` ### 1.1 Pinned Repositories Organizations can pin and group unlimited repositories to highlight on their profile. #### Features | Feature | Specification | |---------|---------------| | **Count** | Unlimited pinned repos | | **Grouping** | Repos can be organized into named groups | | **Ordering** | Drag-and-drop reordering within groups | | **Metadata Displayed** | Stars, forks, primary language badge, description | #### Data Model ```go // models/organization/pinned_repo.go type OrgPinnedRepo struct { ID int64 `xorm:"pk autoincr"` OrgID int64 `xorm:"INDEX NOT NULL"` RepoID int64 `xorm:"INDEX NOT NULL"` GroupName string `xorm:"DEFAULT ''"` // Empty = ungrouped DisplayOrder int `xorm:"DEFAULT 0"` CreatedUnix timeutil.TimeStamp `xorm:"created"` } type OrgPinnedGroup struct { ID int64 `xorm:"pk autoincr"` OrgID int64 `xorm:"INDEX NOT NULL"` Name string `xorm:"NOT NULL"` DisplayOrder int `xorm:"DEFAULT 0"` Collapsed bool `xorm:"DEFAULT false"` // Allow collapsible groups } ``` #### UI Layout ``` ┌─────────────────────────────────────────────────────────────────────┐ │ 📌 Featured Projects │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ ▼ Core Products │ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │ │ [icon] │ │ [icon] │ │ [icon] │ │ │ │ main-app │ │ api-server │ │ web-client │ │ │ │ ⭐ 2.1k 🍴 432│ │ ⭐ 1.8k 🍴 289│ │ ⭐ 956 🍴 178 │ │ │ │ ● TypeScript │ │ ● Go │ │ ● React │ │ │ │ "Our flagship │ │ "Backend API │ │ "Frontend │ │ │ │ application" │ │ services" │ │ application" │ │ │ └───────────────┘ └───────────────┘ └───────────────┘ │ │ │ │ ▼ Libraries & Tools │ │ ┌───────────────┐ ┌───────────────┐ │ │ │ [icon] │ │ [icon] │ │ │ │ shared-utils │ │ cli-tool │ │ │ │ ⭐ 445 🍴 67 │ │ ⭐ 312 🍴 45 │ │ │ │ ● TypeScript │ │ ● Rust │ │ │ └───────────────┘ └───────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` ### 1.2 Public Members Display Members can opt-in to be displayed publicly on the organization profile. #### Features | Feature | Specification | |---------|---------------| | **Visibility** | Member chooses to be displayed (opt-in) | | **Roles Shown** | Owner, Admin, Member | | **Overflow** | "and X more" with link to People tab | | **Layout** | Avatar grid with username and role | #### Data Model ```go // Add to existing OrgUser model type OrgUser struct { // ... existing fields IsPublic bool `xorm:"DEFAULT false"` // Member opts in to public display } ``` #### UI Layout ``` ┌─────────────────────────────────────────────────────────────────────┐ │ 👥 Public Members [View All →]│ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │ │ │ 👤 │ │ 👤 │ │ 👤 │ │ 👤 │ │ 👤 │ │ 👤 │ ... and 18 more │ │ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ │ │ @alice @bob @carol @david @emma @frank │ │ Owner Admin Admin Member Member Member │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` ### 1.3 Promotional Region / About Section Organizations can create a rich profile page with custom content. #### Storage Content is stored in a **private repository** within the organization: ``` Repository: {org}/.profile (private) Files: - README.md # Main profile content (Markdown) - assets/ # Images, videos, badges - logo.png - banner.jpg - team-photo.jpg - style.css # Optional custom CSS (sandboxed) ``` #### Features | Feature | Specification | |---------|---------------| | **Content Format** | Markdown (README.md) | | **Editor** | Markdown editor + optional WYSIWYG toggle | | **Media** | Images, videos, badges stored in `.profile` repo | | **Custom CSS** | Allowed within sandboxed constraints | | **Version Control** | Full Git history via `.profile` repo | #### Content Capabilities ```markdown # Allowed in README.md: ## Standard Markdown - Headers, lists, links, code blocks - Tables, blockquotes - Task lists ## Extended Features - ![Images](./assets/logo.png) - ![Badges](https://img.shields.io/badge/...) - Embedded videos (iframe allowlist: YouTube, Vimeo) - HTML subset (safe tags only) ## Organization-specific - {{MEMBER_COUNT}} - Dynamic member count - {{REPO_COUNT}} - Dynamic repo count - {{PINNED_REPOS}} - Renders pinned repos widget ``` #### CSS Sandboxing ```css /* style.css - Allowed properties */ .profile-content { /* Typography */ font-family: ...; /* From approved list */ font-size: ...; color: ...; /* Layout */ margin: ...; padding: ...; /* Backgrounds */ background-color: ...; background-image: url('./assets/...'); /* Local only */ /* Borders */ border: ...; border-radius: ...; } /* Blocked: position:fixed, z-index manipulation, external URLs, animations (except approved), JavaScript injection */ ``` #### UI Layout ``` ┌─────────────────────────────────────────────────────────────────────┐ │ ┌────────────┐ │ │ │ │ Acme Corporation │ │ │ [LOGO] │ ━━━━━━━━━━━━━━━━ │ │ │ │ "Building the future, one commit at a time" │ │ └────────────┘ │ │ │ │ 🌐 acme.com 📍 San Francisco, CA 📧 hello@acme.com │ │ 🐦 @acmecorp 💼 500+ employees │ │ │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ ## About Us │ │ │ │ We are a team of passionate developers building open source │ │ tools that empower developers worldwide. Founded in 2015, │ │ we've grown to become a leader in developer productivity. │ │ │ │ ### What We Do │ │ │ │ 🚀 **Developer Tools** - IDE plugins, CLI utilities │ │ 🔧 **Infrastructure** - Deployment, monitoring, scaling │ │ 📚 **Education** - Tutorials, documentation, courses │ │ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ [TEAM PHOTO] │ │ │ │ │ │ │ └──────────────────────────────────────────────────────┘ │ │ │ │ ### Join Us │ │ We're always looking for talented people! Check out our │ │ [careers page](https://acme.com/careers). │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## 2. Repository Landing Pages (Gitea Pages) ### Overview Repository owners can create a **standalone landing page** that acts as a public-facing project website. This page is independent of the repository's visibility—a private repo can have a public landing page. ### Key Characteristics | Aspect | Specification | |--------|---------------| | **Independence** | Landing page visibility separate from repo visibility | | **Domain** | Custom domain OR auto-generated subdomain | | **SSL/TLS** | Automatic via Let's Encrypt | | **Templates** | 4 built-in templates, switchable without data loss | | **Configuration** | `.gitea/landing.yaml` (precedence) + DB fallback | ### 2.1 Domain Mapping #### Option 1: Auto-Generated Subdomain ``` Format: {repo}.{owner}.pages.{gitea-domain} Example: myproject.acme.pages.gitea.example.com ``` - Automatically available when landing page is enabled - No DNS configuration required - SSL certificate auto-provisioned #### Option 2: Custom Domain ``` User Configuration: 1. Add CNAME record: myproject.com → pages.gitea.example.com 2. Configure domain in repo settings 3. SSL certificate auto-provisioned via Let's Encrypt ``` #### DNS Verification ```go // Verify domain ownership before enabling type PagesDomain struct { ID int64 `xorm:"pk autoincr"` RepoID int64 `xorm:"INDEX NOT NULL"` Domain string `xorm:"UNIQUE NOT NULL"` Verified bool `xorm:"DEFAULT false"` VerificationTXT string // TXT record for verification SSLCertID string // Reference to cert storage CreatedUnix timeutil.TimeStamp VerifiedUnix timeutil.TimeStamp } ``` ### 2.2 Templates Four built-in templates with consistent configuration: #### Template 1: Simple Clean, minimal design focused on the README. ``` ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ [PROJECT LOGO] │ │ │ │ MyProject │ │ "A better way to do things" │ │ │ │ [⬇️ Download v2.1.0] [📖 View Docs] │ │ │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ # MyProject │ │ │ │ MyProject is a tool that helps you accomplish X faster and │ │ more reliably than ever before. │ │ │ │ ## Installation │ │ ```bash │ │ npm install myproject │ │ ``` │ │ │ │ ## Quick Start │ │ ... │ │ │ ├─────────────────────────────────────────────────────────────────────┤ │ ⭐ 2,341 stars │ 🍴 456 forks │ 📝 MIT License │ v2.1.0 │ └─────────────────────────────────────────────────────────────────────┘ ``` #### Template 2: Documentation Sidebar navigation with documentation pages from `/docs` folder. ``` ┌──────────────┬──────────────────────────────────────────────────────┐ │ │ │ │ [Logo] │ Getting Started │ │ MyProject │ ══════════════════════════════════════════════════ │ │ │ │ │ 🔍 Search │ Welcome to MyProject! This guide will walk you │ │ │ through installation and basic usage. │ │ ────────── │ │ │ │ ## Prerequisites │ │ 📖 DOCS │ │ │ Getting │ Before you begin, ensure you have: │ │ Started ● │ - Node.js 18+ │ │ Install │ - npm or yarn │ │ Config │ │ │ Usage │ ## Installation │ │ │ │ │ 📚 API │ ```bash │ │ Overview │ npm install -g myproject │ │ Reference │ ``` │ │ Examples │ │ │ │ ## Verify Installation │ │ ────────── │ │ │ 📦 v2.1.0 │ ```bash │ │ ⭐ 2,341 │ myproject --version │ │ │ ``` │ │ [GitHub] │ │ │ [Discord] │ [Next: Configuration →] │ │ │ │ └──────────────┴──────────────────────────────────────────────────────┘ ``` #### Template 3: Product Marketing-style landing page with features, screenshots, and CTAs. ``` ┌─────────────────────────────────────────────────────────────────────┐ │░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░│ │░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░│ │░░░░░░░░░░░░░░░░░░░░ [HERO BACKGROUND] ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░│ │░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░│ │░░░░░░░░░░░░░░░░░░░░░ MyProject ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░│ │░░░░░░░░░░░░░ "Ship faster with confidence" ░░░░░░░░░░░░░░░░░░░░░░░░░│ │░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░│ │░░░░░░░░░░░░░ [Get Started] [View Source] ░░░░░░░░░░░░░░░░░░░░░░░░░░│ │░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░│ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ 🚀 │ │ 🔒 │ │ 🔌 │ │ │ │ Blazing Fast │ │ Secure │ │ Extensible │ │ │ │ │ │ │ │ │ │ │ │ Built on Rust │ │ SOC2 compliant │ │ Plugin system │ │ │ │ for maximum │ │ with E2E │ │ with 200+ │ │ │ │ performance │ │ encryption │ │ integrations │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ [SCREENSHOT/DEMO] │ │ │ │ │ │ │ └───────────────────────────────────────────────────────────┘ │ │ │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ Latest Releases Contributors │ │ ──────────────── ──────────── │ │ 📦 v2.1.0 - Jan 8, 2026 [👤][👤][👤][👤][👤] +47 │ │ 📦 v2.0.2 - Dec 15, 2025 │ │ 📦 v2.0.1 - Dec 1, 2025 Trusted by 10,000+ developers │ │ │ │ [⭐ Star on Gitea] │ │ │ ├─────────────────────────────────────────────────────────────────────┤ │ [Home] [Docs] [Blog] [GitHub] [Discord] © 2026 Acme Corp │ └─────────────────────────────────────────────────────────────────────┘ ``` #### Template 4: Portfolio/Gallery Visual showcase for design, art, or media projects. ``` ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ Design System │ │ "A visual component library" │ │ │ │ [View Components] [Download] │ │ │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ │ │ │ │ │ │ │ │ │ │ [img 1] │ │ [img 2] │ │ [img 3] │ │ [img 4] │ │ │ │ │ │ │ │ │ │ │ │ │ │ Buttons │ │ Forms │ │ Cards │ │ Modals │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ │ │ │ │ │ │ │ │ │ │ [img 5] │ │ [img 6] │ │ [img 7] │ │ [img 8] │ │ │ │ │ │ │ │ │ │ │ │ │ │ Tables │ │ Nav │ │ Icons │ │ Colors │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ ## About This Project │ │ │ │ A comprehensive design system built for modern web applications. │ │ Includes 50+ components, dark mode support, and full │ │ accessibility compliance. │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` ### 2.3 Configuration Configuration lives in `.gitea/landing.yaml` with DB fallback. File takes precedence. #### Full Configuration Schema ```yaml # .gitea/landing.yaml # Landing Page Configuration for Gitea Pages #────────────────────────────────────────────────────────────────────── # BASIC SETTINGS #────────────────────────────────────────────────────────────────────── enabled: true template: product # simple | documentation | product | portfolio # Custom domain (optional - subdomain is always available) domain: myproject.com #────────────────────────────────────────────────────────────────────── # BRANDING #────────────────────────────────────────────────────────────────────── branding: logo: ./assets/logo.png logo_dark: ./assets/logo-dark.png # Optional dark mode variant favicon: ./assets/favicon.ico # Color scheme primary_color: "#4a90d9" secondary_color: "#2ecc71" accent_color: "#e74c3c" # Theme dark_mode: auto # auto | light | dark | both (toggle) # Custom fonts (from approved list) heading_font: "Inter" body_font: "system-ui" #────────────────────────────────────────────────────────────────────── # HERO SECTION #────────────────────────────────────────────────────────────────────── hero: title: "MyProject" tagline: "The best thing since sliced bread" # Background options background: ./assets/hero-bg.jpg # OR gradient: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)" # OR color: "#1a1a2e" # Call-to-action buttons cta_primary: text: "Get Started" link: "#installation" # OR link: releases/latest (auto-resolves to latest release) cta_secondary: text: "View Documentation" link: /docs style: outline # outline | ghost #────────────────────────────────────────────────────────────────────── # FEATURES (for product template) #────────────────────────────────────────────────────────────────────── features: - icon: rocket # Built-in icons: rocket, shield, puzzle, zap, etc. title: "Blazingly Fast" description: "Built with performance in mind from day one." - icon: shield title: "Secure by Default" description: "Enterprise-grade security out of the box." - icon: ./assets/custom-icon.svg # Custom icon title: "Extensible" description: "Plugin system for unlimited customization." - icon: puzzle title: "Easy Integration" description: "Works with your existing tools and workflows." #────────────────────────────────────────────────────────────────────── # SECTIONS #────────────────────────────────────────────────────────────────────── sections: - type: features # Renders features array above - type: screenshot image: ./assets/screenshot.png caption: "MyProject in action" - type: readme file: README.md # Default - type: releases limit: 3 show_notes: true # Show release notes excerpt - type: contributors limit: 12 show_count: true # "and 47 more contributors" - type: custom file: ./docs/features.md title: "Why MyProject?" #────────────────────────────────────────────────────────────────────── # DOCUMENTATION (for documentation template) #────────────────────────────────────────────────────────────────────── documentation: source: ./docs # Folder containing markdown files # Search search: true # Table of contents in each page toc: true # Sidebar navigation sidebar: - title: "Getting Started" items: - intro.md - installation.md - quick-start.md - title: "Guides" items: - configuration.md - deployment.md - troubleshooting.md - title: "API Reference" collapsed: true # Collapsed by default items: - api/overview.md - api/authentication.md - api/endpoints.md # "Edit this page" links edit_links: enabled: true text: "Edit this page" # Link auto-generated to repo file #────────────────────────────────────────────────────────────────────── # GALLERY (for portfolio template) #────────────────────────────────────────────────────────────────────── gallery: source: ./gallery # Folder containing images columns: 4 # 2, 3, or 4 lightbox: true # Click to enlarge captions: true # Show image filename as caption # Or explicit items: items: - image: ./gallery/buttons.png title: "Button Components" link: /docs/buttons - image: ./gallery/forms.png title: "Form Elements" link: /docs/forms #────────────────────────────────────────────────────────────────────── # FOOTER #────────────────────────────────────────────────────────────────────── footer: # Link columns links: - title: "Resources" items: - text: "Documentation" url: /docs - text: "API Reference" url: /docs/api - text: "Examples" url: /examples - title: "Community" items: - text: "Discord" url: https://discord.gg/xxx - text: "Twitter" url: https://twitter.com/myproject - text: "GitHub Discussions" url: https://github.com/org/repo/discussions - title: "Company" items: - text: "About" url: https://company.com/about - text: "Blog" url: https://company.com/blog - text: "Careers" url: https://company.com/careers # Copyright copyright: "© 2026 Acme Corporation. Released under MIT License." # Show "Powered by Gitea" badge show_powered_by: true #────────────────────────────────────────────────────────────────────── # SEO & SOCIAL #────────────────────────────────────────────────────────────────────── seo: title: "MyProject - Ship Faster with Confidence" description: "MyProject helps development teams ship code faster and more reliably." keywords: - developer tools - productivity - open source # Open Graph / Social sharing og_image: ./assets/og-image.png twitter_card: summary_large_image twitter_site: "@myproject" #────────────────────────────────────────────────────────────────────── # ANALYTICS (optional) #────────────────────────────────────────────────────────────────────── analytics: # Privacy-friendly options plausible: myproject.com # OR umami: website_id: "xxx" url: "https://analytics.example.com" # OR google_analytics: "G-XXXXXXXXXX" #────────────────────────────────────────────────────────────────────── # ADVANCED #────────────────────────────────────────────────────────────────────── advanced: # Custom CSS file custom_css: ./assets/custom.css # Custom head content (limited HTML) custom_head: | # Redirects redirects: /old-docs: /docs /github: https://github.com/org/repo ``` ### 2.4 URL Structure & Routing #### Standalone Architecture Landing pages are **completely independent** of the repository view: ``` Landing Page: https://myproject.com https://repo.owner.pages.gitea.example.com Repository: https://gitea.example.com/owner/repo (May be private - landing page still accessible) ``` #### Routing Flow ``` ┌─────────────────────┐ Request ──────► │ Gitea Router │ └──────────┬──────────┘ │ ┌────────────────┼────────────────┐ │ │ │ ▼ ▼ ▼ ┌─────────────────┐ ┌───────────┐ ┌───────────────────┐ │ pages.gitea.com │ │ Custom │ │ gitea.example.com │ │ *.pages.gitea.. │ │ Domain │ │ (main app) │ └────────┬────────┘ └─────┬─────┘ └───────────────────┘ │ │ ▼ ▼ ┌─────────────────────────────────┐ │ Pages Handler │ │ - Lookup repo by domain │ │ - Load .gitea/landing.yaml │ │ - Render template │ └─────────────────────────────────┘ ``` #### Navigation Between Landing and Repo The landing page is responsible for providing links to the source repository: ```yaml # In landing.yaml hero: cta_secondary: text: "View Source" link: https://gitea.example.com/owner/repo footer: links: - title: "Developers" items: - text: "Source Code" url: https://gitea.example.com/owner/repo - text: "Issues" url: https://gitea.example.com/owner/repo/issues ``` --- ## 3. Database Schema Changes ### New Tables ```sql -- Organization pinned repositories CREATE TABLE org_pinned_repo ( id BIGINT PRIMARY KEY AUTO_INCREMENT, org_id BIGINT NOT NULL, repo_id BIGINT NOT NULL, group_id BIGINT DEFAULT NULL, display_order INT DEFAULT 0, created_unix BIGINT, FOREIGN KEY (org_id) REFERENCES organization(id), FOREIGN KEY (repo_id) REFERENCES repository(id), FOREIGN KEY (group_id) REFERENCES org_pinned_group(id), UNIQUE KEY (org_id, repo_id) ); -- Organization pinned repo groups CREATE TABLE org_pinned_group ( id BIGINT PRIMARY KEY AUTO_INCREMENT, org_id BIGINT NOT NULL, name VARCHAR(255) NOT NULL, display_order INT DEFAULT 0, collapsed BOOLEAN DEFAULT FALSE, FOREIGN KEY (org_id) REFERENCES organization(id) ); -- Pages domain mapping CREATE TABLE pages_domain ( id BIGINT PRIMARY KEY AUTO_INCREMENT, repo_id BIGINT NOT NULL, domain VARCHAR(255) NOT NULL UNIQUE, verified BOOLEAN DEFAULT FALSE, verification_token VARCHAR(64), ssl_status VARCHAR(32) DEFAULT 'pending', ssl_cert_expiry BIGINT, created_unix BIGINT, verified_unix BIGINT, FOREIGN KEY (repo_id) REFERENCES repository(id) ); -- Pages configuration cache (parsed from .gitea/landing.yaml) CREATE TABLE pages_config ( id BIGINT PRIMARY KEY AUTO_INCREMENT, repo_id BIGINT NOT NULL UNIQUE, enabled BOOLEAN DEFAULT FALSE, template VARCHAR(32) DEFAULT 'simple', config_json TEXT, -- Cached parsed config config_hash VARCHAR(64), -- For invalidation updated_unix BIGINT, FOREIGN KEY (repo_id) REFERENCES repository(id) ); ``` ### Modified Tables ```sql -- Add to org_user table ALTER TABLE org_user ADD COLUMN is_public BOOLEAN DEFAULT FALSE; -- Add to repository table ALTER TABLE repository ADD COLUMN pages_enabled BOOLEAN DEFAULT FALSE; ALTER TABLE repository ADD COLUMN pages_subdomain VARCHAR(255); ``` --- ## 4. API Endpoints ### Organization Profile API ``` # Pinned repos GET /api/v1/orgs/{org}/pinned POST /api/v1/orgs/{org}/pinned PUT /api/v1/orgs/{org}/pinned/reorder DELETE /api/v1/orgs/{org}/pinned/{repo} # Pinned groups GET /api/v1/orgs/{org}/pinned/groups POST /api/v1/orgs/{org}/pinned/groups PUT /api/v1/orgs/{org}/pinned/groups/{id} DELETE /api/v1/orgs/{org}/pinned/groups/{id} # Public members GET /api/v1/orgs/{org}/public_members PUT /api/v1/orgs/{org}/public_members/{username} # Opt-in DELETE /api/v1/orgs/{org}/public_members/{username} # Opt-out # Profile content (via .profile repo) # Uses standard repo file API ``` ### Pages API ``` # Pages configuration GET /api/v1/repos/{owner}/{repo}/pages PUT /api/v1/repos/{owner}/{repo}/pages DELETE /api/v1/repos/{owner}/{repo}/pages # Custom domains GET /api/v1/repos/{owner}/{repo}/pages/domains POST /api/v1/repos/{owner}/{repo}/pages/domains DELETE /api/v1/repos/{owner}/{repo}/pages/domains/{domain} POST /api/v1/repos/{owner}/{repo}/pages/domains/{domain}/verify # SSL certificates GET /api/v1/repos/{owner}/{repo}/pages/domains/{domain}/ssl POST /api/v1/repos/{owner}/{repo}/pages/domains/{domain}/ssl/renew ``` --- ## 5. Implementation Phases ### Phase 1: Organization Profile (4-6 weeks) 1. **Week 1-2:** Database schema, models, migrations 2. **Week 2-3:** Pinned repos API and UI 3. **Week 3-4:** Public members opt-in system 4. **Week 4-5:** Profile content from `.profile` repo 5. **Week 5-6:** WYSIWYG editor integration, CSS sandboxing ### Phase 2: Gitea Pages Foundation (6-8 weeks) 1. **Week 1-2:** Pages router, subdomain handling 2. **Week 2-3:** Configuration parser (`.gitea/landing.yaml`) 3. **Week 3-4:** Simple template implementation 4. **Week 4-6:** Documentation template with sidebar 5. **Week 6-7:** Product and Portfolio templates 6. **Week 7-8:** Settings UI, template switching ### Phase 3: Custom Domains & SSL (3-4 weeks) 1. **Week 1:** Domain verification system 2. **Week 2:** Let's Encrypt integration 3. **Week 3:** DNS routing and Host header handling 4. **Week 4:** SSL certificate renewal, monitoring ### Phase 4: Polish & Advanced Features (2-3 weeks) 1. Analytics integration 2. Search functionality (docs template) 3. Image optimization 4. CDN integration options 5. Performance optimization --- ## Appendix: File Structure ### Organization `.profile` Repository ``` {org}/.profile/ ├── README.md # Main profile content ├── style.css # Optional custom CSS └── assets/ ├── logo.png ├── logo-dark.png ├── banner.jpg └── team-photo.jpg ``` ### Repository Landing Page ``` {repo}/ ├── .gitea/ │ └── landing.yaml # Landing page configuration ├── docs/ # Documentation (for docs template) │ ├── intro.md │ ├── installation.md │ └── api/ │ └── endpoints.md ├── gallery/ # Images (for portfolio template) │ ├── screenshot1.png │ └── screenshot2.png └── assets/ # Landing page assets ├── logo.png ├── favicon.ico ├── hero-bg.jpg ├── og-image.png └── custom.css ``` --- *End of Specification*