grbraman/gtbop-archive-site
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial scaffold

Browse Source
This commit is contained in:
Rich Braman
2026-03-17 10:44:57 -04:00
commit 1368a3e669
43 changed files with 983 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
MIGRATION_GUIDE.md
+308
View File
@@ -0,0 +1,308 @@
# 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*