Migrate wiki content to repository structure and standardize frontmatter on dev

2026-09-03 14:31:57 -05:00
parent 9e9feb5d1e
commit c2b6de3c95
47 changed files with 1111 additions and 376 deletions
--- a/update.md
+++ b/update.md
@@ -0,0 +1,158 @@
+# Fargo 3D Community Content & Repository Hub Architecture (v5)
+
+This document outlines the architecture, API schemas, configuration, and implementation plan for upgrading the **Fargo 3D Wiki, Challenges, & Community Resources** system to consume markdown and structured assets directly from the **primary Git repository** (`Fargo3d/3DPrintMeetup`) instead of the flat Gitea Wiki API.
+
+---
+
+## 1. Overview & Key Advantages
+
+Rather than relying on the legacy Gitea Wiki API (which enforces a flat page hierarchy and requires an $O(N)$ loop to base64-decode each page just to read tags), the website will connect to the **Gitea Repository REST API**.
+
+```
+┌────────────────────────────────────────────────────────────────────────────────────────┐
+│                          COMMUNITY RESOURCE HUBS (WEBSITE)                             │
+├─────────────────────────┬─────────────────────────────┬────────────────────────────────┤
+│   🏆 Challenges Hub     │   🛠️ Tools & Gear Hub       │   📚 Wiki Knowledge Base       │
+│   Route: `/challenges`  │   Route: `/tools`           │   Route: `/wiki?page={Path}`   │
+│   • Active Challenges   │   • 3D Fuel Partner Perk    │   • Meetup Info & Dates        │
+│   • Past Archive        │   • Curated Tools & Reviews │   • Hardware & Slicer Guides   │
+│   • Direct STL / Files  │   • HueForge Color Palette  │   • Announcements Archive      │
+└─────────────────────────┴─────────────────────────────┴────────────────────────────────┘
+                               ▲                               ▲
+                               │                               │
+┌──────────────────────────────┴───────────────────────────────┴─────────────────────────┐
+│                    GITEA REPOSITORY REST API (BRANCH-AWARE)                            │
+│  Swagger: https://meetup.fargo3d.com/api/swagger                                       │
+│  • Git Tree (Recursive): `/api/v1/repos/{owner}/{repo}/git/trees/{branch}?recursive=1` │
+│  • Raw Markdown:        `/api/v1/repos/{owner}/{repo}/raw/{filepath}?ref={branch}`    │
+│  • Raw JSON / Assets:   `/api/v1/repos/{owner}/{repo}/raw/HueForge/3d-Fuel.json`       │
+└────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Major Advantages:
+1. **Branch & Fork Isolation for Safe Local Testing**:
+   - The repository owner, repository name, and branch/ref are configurable via `appsettings.json`.
+   - Developers can point their local environment to a fork (e.g. `espoon/3DPrintMeetup`) or a test branch (e.g. `v5-content`) and test website rendering immediately without altering production markdown or touching the live wiki.
+2. **Instant $O(1)$ Tree Discovery (Zero N+1 Calls)**:
+   - A single recursive git tree request retrieves all markdown files, folder hierarchies, sizes, and git commit SHAs in ~60ms.
+3. **True Folder Hierarchy & Categories**:
+   - Files are organized into natural repository directories (`challenges/`, `announcements/`, `HueForge/`, `tools/`) rather than flat wiki slug naming.
+4. **Structured Asset Ingestion**:
+   - Directly loads `HueForge/3d-Fuel.json` to provide real-time filament hex color palettes, transmissivity values, and filament profiles on `/tools`.
+5. **Direct Raw Streaming**:
+   - The raw API streams pure UTF-8 markdown text directly without base64 wrapper overhead.
+
+---
+
+## 2. Configuration & Branch-Targeting Schema
+
+In `Fargo3D.Web/appsettings.json`:
+
+```json
+{
+  "CommunityContent": {
+    "GiteaBaseUrl": "https://meetup.fargo3d.com",
+    "Owner": "Fargo3d",
+    "Repo": "3DPrintMeetup",
+    "Branch": "master",
+    "CacheDurationMinutes": 15
+  }
+}
+```
+
+In `Fargo3D.Web/appsettings.Development.json` (for local dev against a fork or branch):
+
+```json
+{
+  "CommunityContent": {
+    "Owner": "espoon",
+    "Repo": "3DPrintMeetup",
+    "Branch": "dev"
+  }
+}
+```
+
+---
+
+## 3. Gitea API Endpoints Utilized
+
+| Operation | Gitea Endpoint | Description |
+| :--- | :--- | :--- |
+| **Recursive Tree** | `GET /api/v1/repos/{owner}/{repo}/git/trees/{branch}?recursive=1` | Returns the entire file tree. Filter for `item.path.EndsWith(".md")` to index all content in 1 call. |
+| **Raw Content** | `GET /api/v1/repos/{owner}/{repo}/raw/{filepath}?ref={branch}` | Streams the raw markdown or JSON file content. |
+| **File Metadata** | `GET /api/v1/repos/{owner}/{repo}/contents/{filepath}?ref={branch}` | Returns metadata, commit info, and file size. |
+
+---
+
+## 4. Repository Folder Taxonomy & Routing
+
+The files in `Fargo3d/3DPrintMeetup` map to website sections as follows:
+
+| Repository Directory / File | Category | Target Route / UI Component |
+| :--- | :--- | :--- |
+| `challenges/*/readme.md`, `challenges.md` | `challenges` | `/challenges` & `/wiki?path=challenges/...` |
+| `tools/*.md`, `Supporting-Our-Community.md` | `tools` | `/tools` & `/wiki?path=tools/...` |
+| `HueForge/README.md`, `HueForge/3d-Fuel.json` | `hueforge` | `/tools` & `/wiki?path=HueForge/...` |
+| `announcements/*.md` | `announcements` | `/wiki?path=announcements/...` |
+| `Readme.md`, `itinerary.md`, `ideas.md` | `meetup` | `/wiki?path=Readme.md` (Home) |
+
+---
+
+## 5. Frontmatter YAML Schema Standard
+
+Markdown files can optionally define frontmatter for card titles, badges, and sorting:
+
+```yaml
+---
+title: "September 2026: Practi-FALL Prints"
+category: "challenges"
+subcategory: "2026"
+order: 1
+description: "Functional utility and everyday practicality challenge."
+tags:
+  - active
+  - functional
+  - contest
+---
+```
+
+If frontmatter is omitted, the title defaults to the filename (or first `# H1` header), and the category defaults to the parent folder name.
+
+---
+
+## 6. Implementation Architecture
+
+### 1. New Content Service: `CommunityRepoService.cs`
+Replaces legacy `wikiAPI` in `SharedClasses/`:
+- **`GetContentTreeAsync()`**: Fetches and caches the recursive git tree for `{Owner}/{Repo}@{Branch}`.
+- **`GetRawFileAsync(string path)`**: Downloads raw markdown text using `?ref={Branch}`.
+- **`GetFilamentDatabaseAsync()`**: Downloads and deserializes `HueForge/3d-Fuel.json`.
+- **`ParseFrontmatter(string markdown)`**: Extracts metadata (`title`, `category`, `order`, `tags`) using `FrontmatterParser.cs`.
+
+### 2. Dedicated Hub: `Fargo3D.Web/Components/Pages/Tools.razor`
+- **Route**: `@page "/tools"`
+- **Partner Voucher Card**: 3D Fuel voucher with one-click code copy and direct tracking link.
+- **Interactive HueForge Palette**: Visual swatch grid populated directly from `HueForge/3d-Fuel.json`.
+- **Community Supplies**: Community-tested recommendations pulled directly from the repo's tools markdown.
+
+### 3. Categorized Wiki Tree: `WikiPage.razor`
+- Replaces flat list with folder-aware accordion sidebar:
+  - 📅 **Meetup & Schedule** (`Readme.md`, `itinerary.md`, `ideas.md`)
+  - 🏆 **Maker Challenges** (Grouped by year/month)
+  - 🛠️ **Tools & Hardware** (Supplies, recommendations)
+  - 🎨 **HueForge Guides** (Filament guides, color theory)
+  - 📢 **Announcements Archive**
+
+---
+
+## 7. Migration & Local Testing Workflow
+
+1. **Create Branch or Fork**:
+   - In `meetup.fargo3d.com`, create a branch (e.g. `v5-content`) or fork `3DPrintMeetup` to your user account.
+2. **Update Local Config**:
+   - Set `"Branch": "v5-content"` in `appsettings.Development.json`.
+3. **Develop & Verify**:
+   - Commit markdown and images to your branch/fork.
+   - Run `Fargo3D.Web` locally — it will immediately pull the new structure from your branch without affecting production.
+4. **Merge to Production**:
+   - Merge your content branch into `master` on `Fargo3d/3DPrintMeetup`.