# Feature Enhancements Specification

**Version:** 1.0
**Date:** January 2026
**Status:** Approved for Development

---

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

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