grbraman/gtbop-archive-site

Fork 0

Files

T

Rich Braman 1368a3e669 Initial scaffold

2026-03-17 10:44:57 -04:00

11 KiB

Raw Blame History

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

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

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

surfer login https://docs.gtbop.com

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

6. First build and deploy

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

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:

    - "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

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

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`

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

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

11 KiB Raw Blame History