gtbop-archive-site/PUBLISH_GUIDE.md

# GTBOP Archive Site — Publish Guide
## Reference for Claude Agent in Zed

This file describes the conventions for publishing pipeline deliverables
to the GTBOP MkDocs archive site. Read this before making changes.

---

## Project Structure

```
gtbop-docs/
├── mkdocs.yml                    # Nav config — edit this for every new session
├── docs/
│   ├── index.md                  # Homepage
│   ├── tags.md                   # Auto-generated tag index
│   ├── green-commercial/
│   │   ├── index.md              # Series landing page (has session table)
│   │   └── YYYY-MM-DD-lastname-topic/   # One folder per session
│   │       ├── index.md          # Session overview with deliverable links
│   │       ├── archive-summary.md
│   │       ├── corrections.md
│   │       ├── prose-transcript.md
│   │       ├── processing-log.md
│   │       ├── platforms/
│   │       │   ├── youtube.md
│   │       │   ├── website.md
│   │       │   └── ext-agent.md
│   │       └── activities/
│   │           ├── quiz.md
│   │           └── matching.md
│   ├── structural/               # Same structure as green-commercial
│   ├── writing-projects/
│   │   ├── index.md
│   │   └── project-name-speaker/
│   │       ├── index.md          # Toolkit overview / cover page
│   │       ├── bulletin-outline.md
│   │       ├── reference-compendium.md
│   │       └── source-guide.md
│   └── reference/
│       ├── common-corrections.md
│       ├── speaker-roster.md
│       └── ceu-categories.md
└── PUBLISH_GUIDE.md              # This file
```

---

## File Rename Mapping

When copying from the staging folder, rename files as follows:

| Pipeline Filename Pattern | Rename To | Destination |
|---------------------------|-----------|-------------|
| `GTBOP_Corrections_*.md` | `corrections.md` | session root |
| `GTBOP_Archive_Summary_*.md` | `archive-summary.md` | session root |
| `GTBOP_ProseTranscript_*.md` | `prose-transcript.md` | session root |
| `GTBOP_ProcessingLog_*.md` | `processing-log.md` | session root |
| `GTBOP_YouTube_*.md` | `youtube.md` | `platforms/` |
| `GTBOP_Website_*.md` | `website.md` | `platforms/` |
| `GTBOP_ExtAgent_*.md` | `ext-agent.md` | `platforms/` |
| `GTBOP_Quiz_*.md` | `quiz.md` | `activities/` |
| `GTBOP_Matching_*.md` | `matching.md` | `activities/` |

For writing projects:

| Pipeline Filename Pattern | Rename To |
|---------------------------|-----------|
| `GTBOP_BulletinToolkit_Overview.md` | `index.md` |
| `GTBOP_BulletinOutline_*.md` | `bulletin-outline.md` |
| `GTBOP_ReferenceCompendium_*.md` | `reference-compendium.md` |
| `GTBOP_SourceGuide_*.md` | `source-guide.md` |

Only copy files that exist. Not every session produces all deliverables.

---

## Session Folder Naming

Format: `YYYY-MM-DD-lastname-topic`

Examples:
- `2024-03-07-mccullough-weed-mgmt`
- `2024-11-14-scharf-insecticides`
- `2024-06-20-graziosi-tree-pests`

Use lowercase, hyphens, no spaces. Keep the topic slug short (2-3 words).

---

## Session Index Page Template

Generate this as `index.md` inside each session folder:

```
---
tags:
  - [Series: Green & Commercial or Structural]
  - [Topic area: Weed Science, Entomology, Plant Pathology, Turfgrass, etc.]
  - [Speaker last name]
---

# [Session Title]
## GTBOP [Series] — [Month Day, Year]

**Speaker:** [Full name, title, affiliation]
**Moderator:** [Full name, title, affiliation]
**Duration:** [MM:SS]
**CEU Categories:** [e.g., Category 24 (Ornamental and Turf)]

---

## Deliverables

| Stage | Deliverable | Status |
|-------|-------------|--------|
| 1 | [Corrections Log](corrections.md) | Complete |
| 2 | [Archive Summary](archive-summary.md) | Complete |
| 3 | [YouTube Version](platforms/youtube.md) | Complete |
| 3 | [Website Version](platforms/website.md) | Complete |
| 3 | [Extension Agent Version](platforms/ext-agent.md) | Complete |
| 4 | [Quiz](activities/quiz.md) | Complete |
| 4 | [Matching Exercises](activities/matching.md) | Complete |
| 5 | [Prose Transcript](prose-transcript.md) | Complete |
| — | [Processing Log](processing-log.md) | Complete |

---

## Session Overview

[1-2 paragraph summary — ask the user for this or extract from
the archive summary's narrative section.]

---

*Source: Corrected SRT — [filename] ([block count] blocks)*
*Processed: [Date] | Pipeline v4.1*
```

Only include rows in the deliverables table for files that actually exist.
Mark missing deliverables as "Pending" if stages will be completed later,
or remove the row entirely if the stage doesn't apply.

---

## mkdocs.yml Nav Entry

Add under the appropriate series tab. Use the **structure** below as a
template — replace every `{placeholder}` with the actual session values.
Do NOT copy the example names literally.

**Template (replace all `{placeholders}`):**

```yaml
    - "{Speaker} — {Topic} ({YYYY-MM-DD})":
      - Overview: {series}/{session-folder}/index.md
      - Archive Summary: {series}/{session-folder}/archive-summary.md
      - Corrections Log: {series}/{session-folder}/corrections.md
      - Prose Transcript: {series}/{session-folder}/prose-transcript.md
      - Processing Log: {series}/{session-folder}/processing-log.md
      - Platform Versions:
        - YouTube: {series}/{session-folder}/platforms/youtube.md
        - Website: {series}/{session-folder}/platforms/website.md
        - Extension Agent: {series}/{session-folder}/platforms/ext-agent.md
      - Moodle Activities:
        - Quiz: {series}/{session-folder}/activities/quiz.md
        - Matching: {series}/{session-folder}/activities/matching.md
```

Where:
- `{series}` = `green-commercial` or `structural`
- `{session-folder}` = the folder name, e.g. `2024-03-07-mccullough-weed-mgmt`
- `{Speaker}` = last name, `{Topic}` = short title, `{YYYY-MM-DD}` = session date

Nav label format: `"Speaker — Topic (YYYY-MM-DD)"`

Only include lines for files that actually exist in the session folder.
Place sessions in chronological order
within each series tab.

---

## Series Landing Page Update

Add a row to the session table in the series `index.md`:

```markdown
| 2024-03-07 | [McCullough](2024-03-07-mccullough-weed-mgmt/index.md) | Weed Management in Warm-Season Turfgrass | 1–5 |
```

---

## Writing Project Folder Naming

Format: `project-name-speaker`

Examples:
- `insecticide-bulletin-scharf`
- `fire-ant-management-oi`

---

## Deploy Commands

```bash
# Preview locally
mkdocs serve

# Build + deploy + commit (one-liner)
mkdocs build && surfer put site/* / && git add . && git commit -m "MESSAGE" && git push
```

---

## Tag Conventions

Use these tag categories in frontmatter:

- **Series:** `Green & Commercial` or `Structural`
- **Topic:** `Weed Science`, `Entomology`, `Plant Pathology`, `Turfgrass`, `Structural`, `Horticulture`
- **Speaker:** Last name only (e.g., `McCullough`, `Scharf`, `Graziosi`)

---

## Important Notes

- The staging folder is `~/gtbop-staging/` — deliverables are copied FROM here
- The MkDocs project root is `~/Projects/gtbop-docs/`
- Surfer is at `docs.gtbop.com`
- Gitea remote is `origin`
- Always preview with `mkdocs serve` before deploying
- The `site/` folder is git-ignored — never commit build output