gitcaddy/gitea
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity
main
gitea/enhancements.md
logikonline b816ee4eec feat: add Phases 3-5 enhancements (org profiles, pages, wiki v2 API) 
Phase 3: Organization Public Profile Page
- Pinned repositories with groups
- Public members display with roles
- API endpoints for pinned repos and groups

Phase 4: Gitea Pages Foundation
- Landing page templates (simple, docs, product, portfolio)
- Custom domain support with verification
- YAML configuration parser (.gitea/landing.yaml)
- Repository settings UI for pages

Phase 5: Enhanced Wiki System with V2 API
- Full CRUD operations via v2 API
- Full-text search with WikiIndex table
- Link graph visualization
- Wiki health metrics (orphaned, dead links, outdated)
- Designed for external AI plugin integration
- Developer guide for .NET integration

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-09 15:14:27 -05:00

1140 lines
52 KiB
Markdown
Raw Permalink Blame History

# 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: |
<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*
Reference in New Issue View Git Blame Copy Permalink