TMHSDigital · TMHSDigital · Aug 26, 2026 · Aug 26, 2026 · Aug 26, 2026
diff --git a/.github/AGENTS.md b/.github/AGENTS.md
@@ -14,7 +14,7 @@ CI, deployment, and repository automation under `.github/`.
 
 | File | Purpose |
 |------|---------|
-| [dependabot.yml](dependabot.yml) | Weekly GitHub Actions version updates |
+| [dependabot.yml](dependabot.yml) | Weekly GitHub Actions and pip (requirements-docs.txt) updates |
 | [lychee.toml](lychee.toml) | External link checker settings |
 | [ISSUE_TEMPLATE/](ISSUE_TEMPLATE/) | Issue form for content problems |
 | [PULL_REQUEST_TEMPLATE.md](PULL_REQUEST_TEMPLATE.md) | PR checklist for contributors |
@@ -23,7 +23,7 @@ CI, deployment, and repository automation under `.github/`.
 
 - Pin actions to major version tags (e.g. `@v7`), consistent with existing files.
 - CI must stay fast: this repo is markdown-only.
-- Pages workflow runs `scripts/prepare-mkdocs.py` before building; do not commit `docs/CONTRIBUTING.md`.
+- Pages workflow runs `scripts/prepare-mkdocs.py` before building; do not commit `docs/CONTRIBUTING.md`, `docs/index.md`, or `docs/*/index.md`.
 - Required permissions: `contents: read` for CI; add `pages: write` and `id-token: write` for Pages deploy.
 
 ## Dependabot PRs

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -8,4 +8,4 @@
 
 - [ ] Links are relative and resolve (`python scripts/check-internal-links.py`)
 - [ ] Markdown lint passes (`npx markdownlint-cli2 "**/*.md"`)
-- [ ] Updated `docs/README.md` / root `README.md` if pages were added or moved
+- [ ] New pages have an H1 (optional `nav_order` comment). Do not edit `mkdocs.yml` nav.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -5,3 +5,8 @@ updates:
     schedule:
       interval: weekly
     open-pull-requests-limit: 5
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
diff --git a/.github/lychee.toml b/.github/lychee.toml
@@ -8,4 +8,9 @@ user_agent = "Awesome-Ads-Link-Checker/1.0"
 
 exclude = [
   "https://adespresso.com/wp-content/*",
+  "https://upload.wikimedia.org/*",
+  "https://www.canva.com/*",
+  "https://www.pexels.com/*",
+  "https://www.adobe.com/*",
+  "https://unsplash.com/*",
 ]
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -47,9 +47,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
       - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
       - run: pip install -r requirements-docs.txt
+      - run: python -m unittest scripts.test_catalog
       - run: python scripts/prepare-mkdocs.py
       - run: mkdocs build --strict
diff --git a/.github/workflows/link-check-scheduled.yml b/.github/workflows/link-check-scheduled.yml
@@ -14,6 +14,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Prepare generated docs
+        run: python scripts/prepare-mkdocs.py
       - uses: lycheeverse/lychee-action@v2
         with:
           args: --config .github/lychee.toml "**/*.md"

diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
@@ -20,6 +20,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
 
       - uses: actions/setup-python@v7
         with:

diff --git a/.gitignore b/.gitignore
@@ -4,6 +4,15 @@ research/
 # MkDocs build output and generated site files
 site/
 docs/CONTRIBUTING.md
+docs/index.md
+docs/channels/index.md
+docs/resources/index.md
+docs/ad-templates/index.md
+docs/meta/index.md
+
+# Python
+__pycache__/
+*.py[cod]
 
 # Secrets and local environment files
 .env

diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc
@@ -2,6 +2,11 @@
   "config": ".markdownlint.json",
   "ignores": [
     "docs/CONTRIBUTING.md",
+    "docs/index.md",
+    "docs/channels/index.md",
+    "docs/resources/index.md",
+    "docs/ad-templates/index.md",
+    "docs/meta/index.md",
     "research/**"
   ]
 }
diff --git a/AGENTS.md b/AGENTS.md
@@ -4,7 +4,7 @@ Instructions for AI coding agents working in the Awesome Ads repository.
 
 ## Purpose
 
-This repository is a **markdown documentation project**. There is no application runtime beyond GitHub Pages (MkDocs Material). Your job is usually to edit, add, or reorganize guides and keep links, CI, and navigation consistent.
+This repository is a **markdown documentation project**. There is no application runtime beyond GitHub Pages (MkDocs Material). Your job is usually to edit, add, or reorganize guides. Keep links valid. Site navigation is generated from the docs folders at build time.
 
 ## Repository layout
 
@@ -31,12 +31,7 @@ Each directory has its own `AGENTS.md` with scope-specific rules. Read the neare
 - **Audience:** Small-business owners and marketers. Write clearly; avoid jargon without explanation.
 - **Links:** Use relative paths only so pages work on GitHub and GitHub Pages.
 - **Filenames:** Keep existing UPPERCASE names for channel/resource files (e.g. `SEA.md`, `BUDGETING.md`).
-- **Navigation:** When adding or renaming a page, update:
-  - [mkdocs.yml](mkdocs.yml) (site sidebar navigation)
-  - [docs/README.md](docs/README.md)
-  - [README.md](README.md) (if the page is linked from the landing page)
-  - [docs/index.md](docs/index.md) (if the page should appear on the site home page)
-  - [docs/meta/REPO_OUTLINE.md](docs/meta/REPO_OUTLINE.md) when structure changes
+- **Navigation:** Add or rename a page by placing a markdown file in the right folder with an H1. Optional `<!-- nav_order: 20 -->` on the line after the H1 controls sidebar order. The GitHub Pages nav and indexes are generated at build time. Do not edit a page list in [mkdocs.yml](mkdocs.yml).
 - **Style:** No emojis in prose unless already present in a file you are not rewriting. Prefer complete sentences. Avoid em dashes in new copy; use commas, periods, or hyphens instead.
 - **Scope:** Do not expand scope into code, apps, or infrastructure unless explicitly requested.
 
@@ -46,6 +41,7 @@ Run before opening a PR:
 
 ```bash
 npx markdownlint-cli2 "**/*.md"
+python -m unittest scripts.test_catalog
 python scripts/check-public-repo-hygiene.py
 python scripts/check-internal-links.py
 python scripts/prepare-mkdocs.py
@@ -61,11 +57,11 @@ Site config lives in [mkdocs.yml](mkdocs.yml). The [Deploy GitHub Pages](.github
 ## Do not
 
 - Commit secrets, credentials, API keys, tokens, or private keys.
-- Commit local-only paths: `research/`, `site/`, `docs/CONTRIBUTING.md`, `.env`, or other generated build output.
+- Commit local-only paths: `research/`, `site/`, `docs/CONTRIBUTING.md`, generated `docs/index.md` and `docs/*/index.md`, `.env`, or other generated build output.
 - Commit draft research, internal notes, or machine-local paths unless the user explicitly asks to publish them.
 - Use `git add -A` or `git add .` without reviewing the staged file list first.
 - Add unrelated tooling (frameworks, package.json, etc.) without explicit request.
-- Break relative links or leave orphaned files out of the table of contents.
+- Break relative links.
 - Run destructive git commands unless the user explicitly asks.
 - Push to the remote unless the user explicitly asks.
 

diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -2,4 +2,6 @@
 
 This project follows the [Community Guidelines](docs/meta/COMMUNITY_GUIDELINES.md).
 
-Report unacceptable behavior via [GitHub Issues](https://github.com/TMHSDigital/Awesome-Ads/issues).
+Report content problems via [GitHub Issues](https://github.com/TMHSDigital/Awesome-Ads/issues).
+
+Report harassment or other conduct violations privately. Do not open a public Issue for that. Contact the repository owner through their GitHub profile, or use GitHub's report-abuse tools.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -14,7 +14,7 @@ We welcome contributions from the community! Follow these guidelines to help us
 └── scripts/          # Maintenance scripts (link checker)
 ```
 
-Add new channel guides under `docs/channels/`. Add cross-cutting topics under `docs/resources/`. Update [docs/README.md](docs/README.md) and the root [README.md](README.md) when adding pages.
+Add new channel guides under `docs/channels/`. Add cross-cutting topics under `docs/resources/`. The site nav is generated at build time from those folders. Start each page with an H1. Optional `<!-- nav_order: 20 -->` on the next line controls sidebar order.
 
 ## How to contribute
 
@@ -32,6 +32,7 @@ Add new channel guides under `docs/channels/`. Add cross-cutting topics under `d
 5. **Verify locally**
    ```bash
    npx markdownlint-cli2 "**/*.md"
+   python -m unittest scripts.test_catalog
    python scripts/check-public-repo-hygiene.py
    python scripts/check-internal-links.py
    python scripts/prepare-mkdocs.py
@@ -61,7 +62,7 @@ Open the local URL printed by `mkdocs serve` (typically port 8000).
 - Write clear, accurate prose aimed at small-business readers.
 - Use relative links so pages work on GitHub and GitHub Pages.
 - End markdown files with a single trailing newline.
-- Update the table of contents when adding or renaming pages.
+- The published site catalog is generated from the docs folders. Do not maintain a second page list.
 
 ## Issues and bug reports
 

diff --git a/README.md b/README.md
@@ -8,36 +8,11 @@ Awesome Ads is an open reference for planning, launching, and refining campaigns
 
 | | |
 |---|---|
-| **Full index** | [docs/README.md](docs/README.md) |
 | **Published site** | [tmhsdigital.github.io/Awesome-Ads](https://tmhsdigital.github.io/Awesome-Ads/) |
+| **Source** | [docs/](docs/) |
 | **Contributing** | [CONTRIBUTING.md](CONTRIBUTING.md) |
 
-## Channels
-
-Guides for each major advertising channel, from setup through optimization.
-
-| Channel | Guide | Channel | Guide |
-|---------|-------|---------|-------|
-| Search (SEA) | [SEA](docs/channels/SEA.md) | Social | [SOCIAL](docs/channels/SOCIAL.md) |
-| Display | [DISPLAY](docs/channels/DISPLAY.md) | Video | [VIDEO](docs/channels/VIDEO.md) |
-| Email | [EMAIL](docs/channels/EMAIL.md) | Native | [NATIVE](docs/channels/NATIVE.md) |
-| Affiliate | [AFFILIATE](docs/channels/AFFILIATE.md) | Influencer | [INFLUENCER](docs/channels/INFLUENCER.md) |
-| Print | [PRINT](docs/channels/PRINT.md) | Broadcast | [BROADCAST](docs/channels/BROADCAST.md) |
-| Out-of-home | [OOH](docs/channels/OOH.md) | Direct mail | [DIRECT_MAIL](docs/channels/DIRECT_MAIL.md) |
-| Event sponsorship | [EVENT](docs/channels/EVENT.md) | | |
-
-## Resources
-
-Cross-cutting topics that apply across channels.
-
-| Topic | Guide |
-|-------|-------|
-| Analytics and reporting | [ANALYTICS](docs/resources/ANALYTICS.md) |
-| Budgeting and planning | [BUDGETING](docs/resources/BUDGETING.md) |
-| Legal and ethical considerations | [LEGAL](docs/resources/LEGAL.md) |
-| Campaign examples | [EXAMPLES](docs/resources/EXAMPLES.md) |
-| FAQ and troubleshooting | [FAQ](docs/resources/FAQ.md) |
-| Templates and design | [TEMPLATES](docs/ad-templates/TEMPLATES.md) |
+The GitHub Pages sidebar, home page, and section indexes are generated at build time from the markdown files under `docs/channels/`, `docs/resources/`, `docs/ad-templates/`, and `docs/meta/`. Add a file with an H1 and it appears on the next deploy.
 
 ## For contributors and agents
 

diff --git a/docs/AGENTS.md b/docs/AGENTS.md
@@ -13,26 +13,23 @@ You are working inside the `docs/` tree. All user-facing guides live here.
 
 ## Index
 
-[README.md](README.md) is the canonical table of contents for this folder. Keep it in sync when adding or removing pages. Also update [mkdocs.yml](../mkdocs.yml) navigation and [index.md](index.md) when the change affects the published site.
+[README.md](README.md) points at the published site. Home and section indexes are generated at build time from the markdown files in each subdirectory. Do not hand-edit `index.md` files under `docs/`.
 
 ## Link conventions
 
 Links between docs should be **relative to the current file**:
 
 - From `docs/README.md` to a channel: `channels/SEA.md`
 - From `docs/channels/SEA.md` to a resource: `../resources/ANALYTICS.md`
-- From `docs/ad-templates/SOCIAL_MEDIA.md` to the hub: `TEMPLATES.md`
+- From `docs/ad-templates/TEMPLATES.md` to a channel: `../channels/SOCIAL.md`
 
 Links from the root [README.md](../README.md) use the `docs/` prefix (e.g. `docs/channels/SEA.md`).
 
 ## Adding a new page
 
 1. Place the file in the correct subdirectory (`channels/`, `resources/`, or `ad-templates/`).
-2. Add an entry to [README.md](README.md) and [mkdocs.yml](../mkdocs.yml).
-3. Update the root [README.md](../README.md) if the page should appear on the landing page.
-4. Update [index.md](index.md) if the page should appear on the site home page.
-5. Update [meta/REPO_OUTLINE.md](meta/REPO_OUTLINE.md) for structural changes.
-6. Run validation from the repo root (see [CONTRIBUTING.md](../CONTRIBUTING.md)).
+2. Start the file with an H1. Optional `<!-- nav_order: 20 -->` on the next line controls sidebar order.
+3. Run validation from the repo root (see [CONTRIBUTING.md](../CONTRIBUTING.md)).
 
 ## Content standards
 

diff --git a/docs/README.md b/docs/README.md
@@ -1,35 +1,10 @@
 # Awesome Ads — Documentation
 
-## Advertising channels
+Source files for the published site live in the subfolders of this directory. The live catalog is generated at build time.
 
-1. [Search Engine Advertising (SEA)](channels/SEA.md)
-2. [Social Media Advertising](channels/SOCIAL.md)
-3. [Display Advertising](channels/DISPLAY.md)
-4. [Video Advertising](channels/VIDEO.md)
-5. [Email Marketing](channels/EMAIL.md)
-6. [Native Advertising](channels/NATIVE.md)
-7. [Affiliate Marketing](channels/AFFILIATE.md)
-8. [Influencer Marketing](channels/INFLUENCER.md)
-9. [Print Advertising](channels/PRINT.md)
-10. [Broadcast Advertising](channels/BROADCAST.md)
-11. [Out-of-Home (OOH) Advertising](channels/OOH.md)
-12. [Direct Mail](channels/DIRECT_MAIL.md)
-13. [Event Sponsorship](channels/EVENT.md)
+Browse the guides at [tmhsdigital.github.io/Awesome-Ads](https://tmhsdigital.github.io/Awesome-Ads/).
 
-## Additional resources
-
-1. [Analytics and Reporting](resources/ANALYTICS.md)
-2. [Ad Budgeting and Planning](resources/BUDGETING.md)
-3. [Legal and Ethical Considerations](resources/LEGAL.md)
-4. [Examples of Successful Ad Campaigns](resources/EXAMPLES.md)
-5. [Ad Templates and Design Resources](ad-templates/TEMPLATES.md)
-   - [Social Media Ad Templates](ad-templates/SOCIAL_MEDIA.md)
-   - [Display Ad Templates](ad-templates/DISPLAY_ADS.md)
-   - [Video Ad Templates](ad-templates/VIDEO_ADS.md)
-   - [Email Marketing Templates](ad-templates/EMAIL_MARKETING.md)
-6. [FAQ and Troubleshooting](resources/FAQ.md)
-
-## Meta
-
-- [Repository outline](meta/REPO_OUTLINE.md)
-- [Community guidelines](meta/COMMUNITY_GUIDELINES.md)
+- [channels/](channels/) — one guide per advertising channel
+- [resources/](resources/) — analytics, budgeting, legal, examples, FAQ
+- [ad-templates/](ad-templates/) — templates and design resources
+- [meta/](meta/) — repository outline and community guidelines
diff --git a/docs/ad-templates/AGENTS.md b/docs/ad-templates/AGENTS.md
@@ -1,32 +1,16 @@
 # Agents: Templates
 
-Ad template overviews and format-specific companion pages. The hub is [TEMPLATES.md](TEMPLATES.md); child pages drill into social, display, video, and email formats.
-
-## Files
-
-| File | Role |
-|------|------|
-| `TEMPLATES.md` | Hub: template types, design tools, stock assets, high-level design tips |
-| `SOCIAL_MEDIA.md` | Social media ad templates |
-| `DISPLAY_ADS.md` | Display ad templates |
-| `VIDEO_ADS.md` | Video ad templates |
-| `EMAIL_MARKETING.md` | Email marketing templates |
+Ad template overviews. The hub is [TEMPLATES.md](TEMPLATES.md). Additional format-specific pages in this folder are picked up by the catalog automatically.
 
 ## Structure
 
-- **Hub (`TEMPLATES.md`):** Broad coverage of tools (Canva, Adobe, stock libraries) and design principles. May include image assets via external URLs.
-- **Child pages:** Shorter format-specific summaries that link back to the hub with `[TEMPLATES.md](TEMPLATES.md)`.
-
-## When editing
-
-- Keep sibling pages roughly consistent in length and depth.
-- Prefer linking to the hub for shared design advice rather than duplicating "Tools and Resources" lists.
-- External image URLs (Wikimedia, vendor CDNs) are intentional; do not replace with broken local paths.
+- **Hub (`TEMPLATES.md`):** Tools and design principles. Prefer official vendor URLs over hotlinked logos.
+- **Optional companions:** Format-specific pages should link back to the hub with `[TEMPLATES.md](TEMPLATES.md)`.
 
 ## When adding a template category
 
-1. Add `NEW_FORMAT.md` in this directory.
-2. Add a bullet under ad-templates in [../README.md](../README.md), [mkdocs.yml](../../mkdocs.yml), and the root [README.md](../../README.md).
+1. Add `NEW_FORMAT.md` in this directory with an H1.
+2. Optional `<!-- nav_order: 20 -->` on the next line.
 3. Cross-link from [TEMPLATES.md](TEMPLATES.md).
 
 ## Parent context

diff --git a/docs/ad-templates/DISPLAY_ADS.md b/docs/ad-templates/DISPLAY_ADS.md
diff --git a/docs/ad-templates/EMAIL_MARKETING.md b/docs/ad-templates/EMAIL_MARKETING.md
diff --git a/docs/ad-templates/SOCIAL_MEDIA.md b/docs/ad-templates/SOCIAL_MEDIA.md