# SW FAQs Advanced HubDB — AI Agent Reference

**Module name:** SW FAQs Advanced HubDB  
**Internal name (version report):** SW FAQs Advanced HubDB — must stay unique vs deprecated **SW FAQs Advanced**  
**Use this document when:** The user asks about the Smithworks FAQ hub (`/faqs`), HubDB-backed hub pages, category navigation, topic tags, hub search, category pagination, FAQ canonical URLs, or how module FAQs differ from blog-embedded FAQs.

**Master version number (check `module.html`):** 2026.05.27.22.44

**Marketer-facing module FAQs (not this file):** https://smithworks.marketing/faqs — HubDB `faqs` table; **109+** rows with `group_key` **sw-modules-faq** for SW module Q&A. **Do not** add new module FAQ content to legacy **SW Module FAQs.html** (`/sw-module-faqs`). Future FAQ edits: HubDB directly per **`docs/PROCESS-SMITHWORKS-FAQ-HUBDB.md`**.

**Exact field paths:** This `.txt` + **SW AI Documentation** section `#sw-faqs-advanced-hubdb`. **Blog/page FAQ blocks:** **SW FAQs Simple** (`.txt` section `#sw-faqs-simple`).

---

## 1. Overview

**SW FAQs Advanced HubDB** renders a crawlable **FAQ hub** from one HubDB table:

- **Hub index** — category cards + optional hub-wide search (`/faqs`)
- **Category pages** — flat FAQ list per `category`, topic tag filter, pagination, “On this page” TOC (`/faqs/{category-slug}` when **Category Link Style** = path)

**SW FAQs Simple** uses the **same HubDB table** for small FAQ blocks on individual pages/posts (`page_paths` or `group_key`). Simple needs only a **column subset**; Advanced needs the **full hub contract**.

**This module is HubDB-only** — no inline repeater. Content always comes from HubDB rows with a populated **`category`** (hub ignores rows without `category`).

---

## 2. Theme dependencies (mandatory)

Uploading this module folder alone is **not** sufficient for SEO on paginated hub URLs.

| Asset | Purpose |
|-------|---------|
| `sw-partials/sw-faq-pagination-canonical.html` | Self-referencing canonical for `?page=2+` on category URLs |
| `templates/header.html` | Include partial **before** `{{ standard_header_includes }}` (same pattern as `/blog/all` canonical) |

Without the partial, HubSpot may canonicalize paginated FAQ URLs to page 1.

**Process:** `docs/PROCESS-FAQ-HUB-THEME-SETUP.md`, `docs/SW-Module-Docs/SW FAQs Advanced HubDB/THEME-SETUP.md`

---

## 3. HubDB table contract

**Table:** `faqs` (Smithworks default table ID **2225626814** — other portals need their own table).

### Subset vs full (Simple vs Advanced)

| Column | SW FAQs Simple | SW FAQs Advanced HubDB |
|--------|----------------|-------------------------|
| `name` | Yes | Yes (internal label only) |
| `question` | Yes | Yes |
| `answer` | Yes | Yes (short answer) |
| `long_answer` | Optional | Yes (long-only / read-more modes) |
| `page_paths` | Yes *or* `group_key` | Recommended (“Appears in blog post”) |
| `group_key` | Yes *or* `page_paths` | Optional |
| `related_posts_urls` | Optional | Optional (hub related posts) |
| `category` | Not required | **Required** for hub |
| `category_order` | Not required | **Required** for hub nav order |
| `sort_order` | Not required | **Required** within category |
| `subtopic` | Optional | Optional — **comma-separated topic tags** (filter chips) |

**`subtopic`:** API name `subtopic`. Comma-separated labels (e.g. `HubSpot, SW Modules, SW FAQs Advanced HubDB Module`). Not a second hierarchy under `category`.

**Row rules:** One row = one question + one answer. Do not use `category` as a fake section header without Q&A.

**Ops:** `docs/PROCESS-SMITHWORKS-FAQ-HUBDB.md` — row workflow, JSON handoffs, snapshot CSV refresh after every HubDB update.

---

## 4. Content tab

- **Enable Module** — Turns the module on/off.
- **Custom ID** / **Custom Classes** — Side by side (`half_width`); optional HTML id and extra CSS classes on the module shell.
- **Headings** — Repeater above hub content. Per row: **Heading** text; **Size** (h1–h6, p); **Display Size**; **Color** (auto, theme, custom); **Align** with optional **tablet/mobile** text-align overrides; optional **tablet/mobile display size** overrides; **Padding Override** (top/bottom px); optional **CSS Class**.
- **Content Area** — Intro rich text (index or category intro).
- **Content style** — Below Content Area (SW Image & Text pattern): Default, Large (text balanced), Large (text full-width), Small, Blockquote → `lead` / `small` / `blockquote` on `.sw-faqs-advanced__intro`.
- **Hub Page Mode** — **FAQ Hub Index** vs **FAQ Category Page** (also auto-detected from URL when possible).
- **HubDB Category Name** — Must match HubDB `category` text when the URL slug alone is not enough.
- **Hub Navigation** — **FAQ Hub Base Path** (default `/faqs`); **Category Link Style** — **path** (recommended: `/faqs/{slug}`) vs **query** (`?category=slug`).
- **Output FAQPage Schema** — FAQPage JSON-LD from **visible** FAQs on the current page (per-page when paginated).
- **Answer Display Mode** — Short only, Long only, or Short + Read More (expand/collapse).
- **Read More / Show Less** labels — When using read-more mode.
- **Show Related Posts** — From HubDB `related_posts_urls` (dot-separated titles).
- **Show Appears In Blog Post Link** — First `/blog/…` in `page_paths` (not related posts URLs).
- **Topic Tags** — Show filter chips; show per-FAQ tag buttons; default OR/AND match mode.
- **FAQ Hub Search and Pagination** — Hub-wide search; placeholders; tag collapse threshold; **Paginate Category Pages**; **FAQs Per Page** (default 10).
- **HubDB Settings** — **HubDB Table ID**; max related links; developer empty-state note.
- **Module Inner: Background Video** — When inner background = Video.

---

## 5. Style tab

Same **Module Outer / Module Inner** pattern as **SW FAQs Simple**:

- **Module Settings** — Outer/inner spacing and width; height groups.
- **Module Background Settings** — Outer band + inner FAQ shell; inner border override (default: no forced inner border when override off).
- **Content Colors** — Text/link contrast on inner background.

UI radii use theme `var(--border_radius)` except topic tag pills (full rounded).

---

## 6. Hub behavior (for agents)

| Feature | Behavior |
|---------|----------|
| Category nav | Built from distinct HubDB `category` values; ordered by `category_order` |
| Index search | `?q=` searches across categories when on index; **fuzzy** typo-tolerant matching |
| Category search | Defaults to current category; **Search all FAQs** → `/faqs?q=` |
| Search / tag results | Full FAQ cards inline (question + answer + read more)—not snippet links to wrong paginated pages |
| Ask AI | Optional **ChatGPT** link under search (short prompt to **sw-module-documentation** + user search phrase) |
| Topic tags | `?tags=slug1,slug2&tag_match=or\|and`; filter in left sidebar (desktop) |
| Pagination | `?page=N`; rel prev/next; page number links (3+ pages); lazy-load category index JSON from `/faqs` on first filter/search |
| Filter + search active | Hides pagination + TOC; strips `page` from URL; lists matching FAQs only |
| Canonical | Base category URL when filtering; `?page=N` self-canonical when partial installed |

---

## 7. CMS setup

Typical Smithworks pattern:

1. **Hub index** at `/faqs` — **SW General Page** + module **FAQ Hub Index**.
2. **One CMS page per category** at `/faqs/{slug}` — module **FAQ Category Page**; slug matches auto-slug from `category` text.
3. Publish HubDB table after row edits.
4. Add paginated URLs to sitemap when pagination is on.

Dedicated FAQ hub templates are optional; General Page + module mode is the supported pattern.

---

## 8. Deprecated module

**SW FAQs Advanced** (inline repeater) is deprecated — `is_available_for_new_content: false`. Do **not** overwrite deprecated files on portals that still reference old pages. New hub work uses **SW FAQs Advanced HubDB** only.

---

## 9. Common tasks

- **Add module FAQs for marketers/AI:** Edit HubDB `faqs` rows (or JSON handoff); browse at **https://smithworks.marketing/faqs** — not `SW Module FAQs.html`.
- **FAQ on a blog post:** Use **SW FAQs Simple** + HubDB rows with `page_paths` = `/blog/post-slug`.
- **New hub category:** Add rows with new `category` + `category_order`; create CMS page at matching `/faqs/{slug}`.
- **Fix paginated SEO:** Confirm theme partial + header include per §2.
- **Topic tag filter:** Populate `subtopic` with comma-separated tags; one tag per chip.

---

## 10. Do not invent

- HubDB column API names (use contract in §3).
- Field paths — use labels in this doc / SW AI Documentation.
- That inline repeater or FAQ Source toggle still exists (removed — HubDB only).