gitea/enhancements.md

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
2. Repository Landing Pages (Gitea Pages)
3. Database Schema Changes
4. API Endpoints
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

// 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

// 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

# 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

/* 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

// 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

# .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: |
    <link rel="preconnect" href="https://fonts.googleapis.com">    

  # 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:

# 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

-- 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

-- 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