gtbop-archive-site/MIGRATION_GUIDE.md

# GTBOP Archive Site — MkDocs Material Setup & Migration Guide

## What This Package Is

A complete MkDocs Material project scaffold mapped to your GTBOP pipeline output. Drop your existing Markdown deliverables into the placeholder files, build the site, and deploy. The result is a fully searchable, navigable archive site that your team can browse by series, by session, by deliverable type, or by keyword search.

---

## Infrastructure

| Component | Address | Purpose |
|-----------|---------|---------|
| **Live site** | `https://docs.gtbop.com/` | Cloudron Surfer — serves the built static files |
| **Source repo** | `https://mnemosyne.openextension.org/` | Gitea — version control for Markdown source files |
| **Build tool** | Local Mac | MkDocs Material — generates static HTML from Markdown |

The workflow: edit Markdown files locally, build with `mkdocs build`, deploy to Surfer, commit to Gitea.

---

## Why MkDocs Material Over Grav

| Concern | Grav (current) | MkDocs Material |
|---------|---------------|-----------------|
| **Adding a webinar** | Create nested folders, add frontmatter, update custom template, clear cache | Drop files into folder, add nav lines to `mkdocs.yml`, rebuild |
| **Search** | None built in | Full-text search across all documents, zero config |
| **Navigation** | Custom HTML template | Auto-generated sidebar from `mkdocs.yml` nav config |
| **Cross-referencing** | Manual links | Tags system + automatic section navigation |
| **Maintenance** | Tied to Grav templating knowledge | Any Markdown-literate person can add content |
| **Markdown handling** | Requires frontmatter on every page | No frontmatter required (optional for tags) |
| **Dark mode** | Theme-dependent | Built-in toggle |
| **Mobile** | Theme-dependent | Responsive out of the box |

---

## Project Structure

```
mkdocs-gtbop/
├── mkdocs.yml                          ← Site config + navigation
└── docs/
    ├── index.md                        ← Homepage
    ├── tags.md                         ← Tag index (auto-populated)
    │
    ├── green-commercial/               ← Series: Green & Commercial
    │   ├── index.md                    ← Series landing page
    │   │
    │   ├── 2026-01-15-graziosi-tree-pests/
    │   │   ├── index.md                ← Session landing page
    │   │   ├── archive-summary.md      ← Stage 2
    │   │   ├── prose-transcript.md     ← Stage 5
    │   │   ├── corrections.md          ← Stage 1 log
    │   │   ├── downloads.md            ← SRT download link
    │   │   ├── *.srt                   ← Actual SRT file (static asset)
    │   │   ├── platforms/
    │   │   │   ├── youtube.md          ← Stage 3
    │   │   │   ├── website.md
    │   │   │   └── ext-agent.md
    │   │   └── activities/
    │   │       ├── quiz.md             ← Stage 4
    │   │       ├── matching.md
    │   │       └── review-prompts.md
    │   │
    │   └── (additional sessions follow same structure)
    │
    ├── structural/                     ← Series: Structural Pest Control
    │   ├── index.md
    │   └── (sessions follow same structure)
    │
    └── projects/                       ← Stage 6: Writing Projects
        ├── index.md
        └── insecticide-bulletin/
            ├── index.md                ← Toolkit overview
            ├── outline.md
            ├── compendium.md
            └── source-guide.md
```

### Naming Convention: Session Folders

```
YYYY-MM-DD-lastname-short-topic/
```

Examples: `2026-01-15-graziosi-tree-pests/`, `2017-10-18-scharf-insecticide-moa/`

---

## First-Time Setup

### 1. Install MkDocs Material on your Mac

```bash
pip install mkdocs-material
```

### 2. Create the repo in Gitea

In your Gitea web UI at `https://mnemosyne.openextension.org/`: **New Repository** → `gtbop-archive-site`

### 3. Initialize and push the scaffold

```bash
cd ~/path/to/mkdocs-gtbop
git init
git remote add origin https://mnemosyne.openextension.org/grbraman/gtbop-archive-site.git
git add .
git commit -m "Initial scaffold"
git push -u origin main
```

### 4. Install Surfer on Cloudron

Cloudron App Store → search "Surfer" → install at `docs.gtbop.com`

### 5. Log in to Surfer from your Mac

```bash
surfer login https://docs.gtbop.com
```

Enter your Cloudron credentials when prompted. One-time step.

### 6. First build and deploy

```bash
mkdocs build
surfer put site/* /
```

Visit `https://docs.gtbop.com/` — you should see the site.

---

## How to Add a New Webinar

### Step 1 — Create the session folder

```bash
mkdir -p docs/green-commercial/YYYY-MM-DD-lastname-topic/platforms
mkdir -p docs/green-commercial/YYYY-MM-DD-lastname-topic/activities
```

### Step 2 — Copy files from an existing session

Copy all the `.md` files from an existing session folder. Update the content with your pipeline output.

### Step 3 — Update the session landing page (`index.md`)

Update: title, speaker, date, duration, series, CEU categories, deliverable links, source attribution.

### Step 4 — Add nav entry in `mkdocs.yml`

Copy an existing session's nav block under the right series tab and update paths:

```yaml
    - "Lastname — Topic (Mon Year)":
      - green-commercial/YYYY-MM-DD-lastname-topic/index.md
      - Archive Summary: green-commercial/YYYY-MM-DD-lastname-topic/archive-summary.md
      - Prose Transcript: green-commercial/YYYY-MM-DD-lastname-topic/prose-transcript.md
      - Transcript Corrections: green-commercial/YYYY-MM-DD-lastname-topic/corrections.md
      - Platform Versions:
        - YouTube: green-commercial/YYYY-MM-DD-lastname-topic/platforms/youtube.md
        - Website: green-commercial/YYYY-MM-DD-lastname-topic/platforms/website.md
        - Extension Agent: green-commercial/YYYY-MM-DD-lastname-topic/platforms/ext-agent.md
      - Moodle Activities:
        - Quiz: green-commercial/YYYY-MM-DD-lastname-topic/activities/quiz.md
        - Matching: green-commercial/YYYY-MM-DD-lastname-topic/activities/matching.md
        - Review Prompts: green-commercial/YYYY-MM-DD-lastname-topic/activities/review-prompts.md
      - Downloads:
        - Corrected SRT: green-commercial/YYYY-MM-DD-lastname-topic/downloads.md
```

### Step 5 — Update the series landing page

Add a row to the session table in `docs/green-commercial/index.md` or `docs/structural/index.md`.

### Step 6 — Preview, build, deploy, commit

```bash
mkdocs serve                            # Preview at http://localhost:8000
mkdocs build                            # Build static site
surfer put site/* /                     # Deploy to docs.gtbop.com
git add . && git commit -m "Add Lastname topic - Mon Year" && git push
```

---

## How to Add a Writing Project

### Step 1 — Create the project folder

```bash
mkdir -p docs/projects/short-project-name/
```

### Step 2 — Drop in the toolkit files

| Pipeline Output | Rename To |
|----------------|-----------|
| `GTBOP_BulletinToolkit_Overview.md` | `index.md` |
| `GTBOP_BulletinOutline_*.md` | `outline.md` |
| `GTBOP_ReferenceCompendium_*.md` | `compendium.md` |
| `GTBOP_SourceGuide_*.md` | `source-guide.md` |

### Step 3 — Add nav entry in `mkdocs.yml`

```yaml
    - "Project Display Name":
      - projects/short-project-name/index.md
      - Bulletin Outline: projects/short-project-name/outline.md
      - Reference Compendium: projects/short-project-name/compendium.md
      - Source Guide: projects/short-project-name/source-guide.md
```

### Step 4 — Update `docs/projects/index.md` and deploy

---

## Adding Tags to Pages

Add a YAML frontmatter block at the top of any page:

```yaml
---
tags:
  - Green & Commercial
  - Entomology
  - Graziosi
---
```

Tags appear on the page and are browsable from `https://docs.gtbop.com/tags/`.

---

## Quick Reference Commands

| Task | Command |
|------|---------|
| Local preview | `mkdocs serve` |
| Build site | `mkdocs build` |
| Deploy to Surfer | `surfer put site/* /` |
| Build + deploy (one line) | `mkdocs build && surfer put site/* /` |
| Commit changes | `git add . && git commit -m "message" && git push` |
| Full deploy cycle | `mkdocs build && surfer put site/* / && git add . && git commit -m "message" && git push` |

---

## What Your Team Gets

**For Beth / Dr. Pennisi / extension specialists:**
- Search bar that finds content across all processed webinars
- Tabbed navigation: click Green & Commercial or Structural to see only that series
- Each session has a landing page with links to every deliverable
- Dark mode toggle

**For you (maintenance):**
- Adding a webinar: ~10 minutes (copy folder, paste content, add nav lines, build)
- No custom templates to maintain
- No cache to clear
- No frontmatter required on content files (optional for tags)
- Git-friendly: every change is a diffable text file

**For writing project collaborators (Dan, Mike):**
- Dedicated Writing Projects tab separate from the archive
- Each toolkit has its own landing page explaining the documents
- Cross-links back to the source webinar's archive page

---

## Troubleshooting

**`mkdocs serve` shows an error about nav paths:**
A file listed in `mkdocs.yml` doesn't exist in `docs/`. Check for typos in the path.

**Site looks stale after deploy:**
Hard refresh in browser (Cmd+Shift+R). Surfer may cache.

**Surfer login expired:**
Run `surfer login https://docs.gtbop.com` again.

**Search not finding new content:**
MkDocs rebuilds the search index on every `mkdocs build`. Make sure you built before deploying.

---

## File Inventory in This Package

| File | Status |
|------|--------|
| `mkdocs.yml` | **Complete** — full config with nav for all 3 sessions + bulletin project |
| `docs/index.md` | **Complete** — homepage with series cards and pipeline overview |
| `docs/tags.md` | **Complete** — tag index page |
| `docs/green-commercial/index.md` | **Complete** — series landing page |
| `docs/structural/index.md` | **Complete** — series landing page |
| `docs/projects/index.md` | **Complete** — projects landing page |
| `docs/projects/insecticide-bulletin/index.md` | **Complete** — toolkit overview page |
| Session `index.md` files (3) | **Complete** — session landing pages with deliverable tables |
| Session `downloads.md` files (3) | **Complete** — SRT download pages |
| All other `*.md` files | **Placeholder** — paste your pipeline content here |

Total: 41 Markdown files across the full site structure.

---

*Prepared March 16, 2026 for GTBOP archive site deployment*
*Site: docs.gtbop.com / Repo: mnemosyne.openextension.org*