# yuzhaozhang.com — Current state summary

> **Purpose:** Machine- and human-readable snapshot of site structure, published content, and content architecture. Use this to plan new articles, tools, and cross-links without re-exploring the repo.  
> **Last updated:** 2026-06-07  
> **Live site:** https://yuzhaozhang.com/

---

## 1. What this site is

**Yuzhao (David) Zhang** publishes practical freight-cost resources for **shippers, 3PLs, and operations leaders** in **Canada and North America** (author based in the Greater Toronto Area; content uses `en-CA`).

**Positioning:** Plain language, invoice-grounded, no vendor marketing. Freight cost is framed as a **system problem** (shipment profile, carrier rules, service requirements, operations, invoice logic)—not only a rate-table problem.

**Primary content types:**

| Type | Role |
|------|------|
| Long-form blog articles | Deep guides and explainers |
| Interactive tools | Calculators and self-assessments (no sign-up) |
| Glossary | A–Z reference with links into articles/tools |
| Start here hub | Scenario-based routing to the right resources |
| Newsletter | Header signup via `subscribe.php` |

**Related agent instructions (repo):**

| File | Use when |
|------|----------|
| `agent_instructions/sole.md` | Writing voice, structure, quality bar |
| `agent_instructions/audience.md` | Who to write for (business operators, not only logistics pros) |
| `agent_instructions/blog.md` | Technical checklist for publishing a new post |
| `llms.txt` | Shorter public LLM context (keep in sync after major changes) |

**Style reference articles (per `sole.md`):**

- https://yuzhaozhang.com/blog/how_to_evaluate_carrier_contracts/
- https://yuzhaozhang.com/blog/dimensional_weight_explained/

---

## 2. Technical architecture

**Stack:** Static HTML/CSS/JS. No build step. Each blog post is a folder with `index.html`.

**Deploy:** GitHub Actions on push to `main` → FTP to cPanel (`.github/workflows/deployCpanel.yml`).

**Shared assets:**

| Path | Role |
|------|------|
| `styles.css` | Global layout, blog, tools, glossary |
| `home.css` | Home page only |
| `script.js` | Nav, newsletter UX, blog search filter on `blog.html` |
| `home.js` | Home page interactions |
| `images/` | Favicon, author photo (`davidzhang.jpg`) |

**Backend (light):**

- `subscribe.php` — newsletter signup
- `contact.php` — contact form (home page)
- `data/` — protected subscriber data (`.htaccess`, not in git)

**SEO / discovery (update when adding posts):**

| File | Notes |
|------|-------|
| `sitemap.xml` | All indexable URLs + `lastmod` |
| `rss.xml` | Atom feed; newest entries first |
| `schema.json` | JSON-LD export; `Blog.blogPost` list |
| `robots.txt` | Crawler rules |
| `llms.txt` | LLM-oriented site summary |

---

## 3. Site map (pages)

```
/                           Home (bio, themes, featured articles, contact)
/blog.html                  Blog index (16 cards, client-side search)
/start-here/                Scenario hub (5 situation cards + FAQ schema)
/tools/                     Tools index
/tools/dimensional-weight-calculator/
/tools/carrier-contract-scorecard/
/tools/skid-builder/        Pallet layout calculator (LTL)
/glossary/                  ~48 terms, 11 deep-links to blog posts
/blog/<slug>/               One article per folder (see §5)
```

**Global nav (all main pages):** Home · Start here · Blog · Tools · Glossary · Newsletter (dropdown → `subscribe.php`)

---

## 4. Content clusters (topic architecture)

Content is organized into **three logical clusters**. Use these to avoid duplicate topics and to plan internal links.

### Cluster A — Accessorial charges (hub + wave 1)

**Hub:** [Freight Accessorial Charges Explained](https://yuzhaozhang.com/blog/freight_accessorial_charges_explained/)

Hub includes a **comparison table** (parcel vs LTL triggers) and a **“Related articles in this cluster”** list. Deep dives link back to the hub implicitly via site navigation; hub explicitly links to all children.

| Slug | Title (short) | Published | Role |
|------|---------------|-----------|------|
| `freight_accessorial_charges_explained` | Freight Accessorial Charges Explained | 2025-09-15 | **Hub** — parcel + LTL overview |
| `what_is_overmax_shipping` | What Is Overmax in Shipping? | 2025-10-15 | Parcel size ceiling / network limits |
| `additional_handling_surcharge_explained` | Additional Handling Surcharge | 2025-11-15 | Non-standard parcel handling |
| `oversize_vs_large_package_vs_overmax` | Oversize vs Large Package vs Overmax | 2025-12-15 | Tier comparison (not carrier-specific labels) |
| `liftgate_fee_less_than_truckload_shipping` | Liftgate Fee (LTL) | 2026-01-15 | LTL dock vs ground unload |
| `what_is_limited_access_delivery` | Limited Access Delivery | 2026-02-15 | LTL constrained sites |
| `how_to_audit_freight_accessorial_charges` | How to Audit Accessorials | 2026-03-15 | Invoice workflow, disputes |

**Cluster gaps (not yet dedicated articles):** residential delivery, appointment/notification, inside delivery, detention, fuel surcharge mechanics.

### Cluster B — Foundations & mode (cross-cutting)

These support Start here “foundations” and mode-selection paths. Not all are in the accessorial hub list.

| Slug | Title (short) | Published | Role |
|------|---------------|-----------|------|
| `dimensional_weight_explained` | Dimensional Weight Explained | 2026-04-01 | Billable weight, divisors, rounding; **interactive demos** |
| `shipping_courier_vs_ltl` | Courier vs LTL | 2026-03-31 | Mode choice for multi-piece shipments |
| `how_to_evaluate_carrier_contracts` | Evaluate Carrier Contracts | 2026-04-20 | Contract beyond rate table; links to scorecard tool |

### Cluster C — Shipping strategy / operations economics (wave 2 + 3)

Newer articles aimed at **operators and margin**, not only fee definitions.

| Slug | Title (short) | Published | Role |
|------|---------------|-----------|------|
| `freight_cost_shock` | What Causes Freight Cost Shock? | 2026-06-07 | 10 causes of sudden cost spikes; early warning checklist; shock vs creep timeline |
| `freight_cost_creep` | Why Freight Costs Keep Increasing | 2026-06-07 | 11 sources of gradual drift; compounding scenario; consolidation example; 10-point diagnostic checklist |
| `ltl_reweigh_reclass_charges` | LTL Reweigh and Reclass Charges | 2026-06-04 | Reweigh vs reclass, NMFC class, density, dispute checklist, prevention |
| `amazon_supply_chain_services_shippers` | Amazon Supply Chain Services | 2026-05-07 | AWD, MCF, AMZL; shipper decision framework |
| `freight_decisions_gross_margin` | Small Freight Decisions & Gross Margin | 2026-05-06 | Five margin leak points |
| `detect_freight_leakage` | Detect Freight Leakage | 2026-05-06 | Signals + 4-step invoice workflow |

**Cross-links:** `freight_cost_shock` ↔ `freight_cost_creep` (explicit bidirectional pair). Both link to `detect_freight_leakage`, `ltl_reweigh_reclass_charges`, `freight_accessorial_charges_explained`, `how_to_audit_freight_accessorial_charges`. Wave 2/3 articles are **not** yet wired into Start here scenario cards or home “featured” list (planning opportunity).

---

## 5. Full article inventory (16 posts)

Listed **newest first** (matches `blog.html`, `rss.xml`, `sitemap.xml`).

| # | Slug | Full title | Published | Modified | “What you’ll get” section | Special assets |
|---|------|------------|-----------|----------|---------------------------|----------------|
| 1 | `freight_cost_shock` | What Causes Freight Cost Shock? 10 Reasons Shipping Costs Suddenly Increase | 2026-06-07 | 2026-06-07 | Yes | Hero `images/1.jpg` (needed) |
| 2 | `freight_cost_creep` | Why Freight Costs Keep Increasing: How to Identify and Stop Freight Cost Creep | 2026-06-07 | 2026-06-07 | Yes | Hero `images/1.jpg` (needed) |
| 3 | `ltl_reweigh_reclass_charges` | LTL Reweigh and Reclass Charges Explained: Why Your Invoice Is Higher Than the Quote | 2026-06-04 | 2026-06-04 | Yes | Hero `images/1.jpg` (needed) |
| 4 | `amazon_supply_chain_services_shippers` | What Amazon Supply Chain Services Means for Shippers | 2026-05-07 | 2026-05-07 | Yes | Hero `images/1.jpg` |
| 5 | `freight_decisions_gross_margin` | How Small Freight Decisions Quietly Reduce Gross Margins | 2026-05-06 | 2026-05-06 | Yes | Hero `images/1.jpg` |
| 6 | `detect_freight_leakage` | How Operators Can Detect Freight Leakage Without Building a Logistics Department | 2026-05-06 | 2026-05-06 | Yes | Hero `images/1.jpg` |
| 7 | `how_to_evaluate_carrier_contracts` | How to Evaluate Carrier Contracts: Beyond the Rate Table to Real Invoice Behavior | 2026-04-20 | 2026-04-20 | Yes | Embedded scorecard CTA → `/tools/carrier-contract-scorecard/`; `carrier-contract-scorecard.js` in post folder (duplicate of tool logic) |
| 8 | `dimensional_weight_explained` | Dimensional Weight Explained: A Real-World Guide for Shippers and 3PLs to Reduce Freight Cost | 2026-04-01 | 2026-04-15 | Yes | `feathers-rocks-intro.js`, `dim-rounding-comparison.js`, SVG/PNG diagrams |
| 9 | `shipping_courier_vs_ltl` | Courier vs. Less-Than-Truckload: How Shippers Should Decide for Multi-Piece Shipments | 2026-03-31 | 2026-04-15 | No | Hero image |
| 10 | `how_to_audit_freight_accessorial_charges` | How to Audit Freight Accessorial Charges on Carrier Invoices | 2026-03-15 | 2026-03-15 | Yes | Hero `images/1.jpg` |
| 11 | `what_is_limited_access_delivery` | What Is Limited Access Delivery? | 2026-02-15 | 2026-02-15 | No | Hero `images/1.png` |
| 12 | `liftgate_fee_less_than_truckload_shipping` | What Is a Liftgate Fee in Less-than-Truckload Shipping? | 2026-01-15 | 2026-01-15 | No | Hero `images/1.jpg` |
| 13 | `oversize_vs_large_package_vs_overmax` | Oversize vs Large Package vs Overmax | 2025-12-15 | 2025-12-15 | No | Hero `images/1.png` |
| 14 | `additional_handling_surcharge_explained` | What Is an Additional Handling Surcharge? | 2025-11-15 | 2025-11-15 | No | Hero `images/1.jpg` |
| 15 | `what_is_overmax_shipping` | What Is Overmax in Shipping? | 2025-10-15 | 2025-10-15 | No | Hero `images/1.jpg` |
| 16 | `freight_accessorial_charges_explained` | Freight Accessorial Charges Explained: Parcel and Less-than-Truckload Fees That Increase Shipping Cost | 2025-09-15 | 2025-09-15 | No | Hub table + related-articles list |

**Article folder convention:**

```
blog/<slug>/
  index.html          # Full article (canonical URL ends with trailing slash)
  images/             # Hero + inline (typically 1.jpg or 1.png, 1200×630 for cards)
  *.js                # Optional page-specific interactives
```

**Per-post HTML patterns:**

- `lang="en-CA"`, geo meta (GTA), hreflang `en-CA` / `en` / `x-default`
- JSON-LD: `Article` + `BreadcrumbList`
- `articleSection`: `"Shipping strategy"` on all posts
- Paths from post: `../../styles.css`, `../../script.js`, `../../blog.html`, etc.
- Body class / structure: `.blog-post`, `.blog-post-summary` for value bullets where present

**Posts missing `sole.md` “What you’ll get” block (7):** wave-1 accessorial deep dives (`freight_accessorial_charges_explained`, `what_is_overmax_shipping`, `additional_handling_surcharge_explained`, `oversize_vs_large_package_vs_overmax`, `liftgate_fee_less_than_truckload_shipping`, `what_is_limited_access_delivery`) + `shipping_courier_vs_ltl`. Optional retrofit when editing those pages.

---

## 6. Interactive tools

| Tool | URL | In sitemap | Linked from |
|------|-----|------------|-------------|
| Dimensional Weight Calculator | `/tools/dimensional-weight-calculator/` | Yes | Start here (cost + mode cards), glossary, DIM article |
| Carrier Contract Scorecard | `/tools/carrier-contract-scorecard/` | Yes | Start here (contracts card), evaluate-contracts article |
| Skid Builder | `/tools/skid-builder/` | Yes | Tools index |

All tools: free, no sign-up, client-side JS.

---

## 7. Start here hub (user journeys)

URL: https://yuzhaozhang.com/start-here/

Five scenario cards route readers to articles + tools:

| Scenario | Articles linked | Tool |
|----------|-----------------|------|
| Why did freight costs increase? | Audit accessorials, accessorial hub, DIM explained | DIM calculator |
| How do I evaluate a carrier contract? | Evaluate carrier contracts | Contract scorecard |
| Unexpected fees? | Accessorial hub, audit workflow + inline links to liftgate, limited access, handling, overmax, oversize tiers | — |
| Courier or LTL? | Courier vs LTL | DIM calculator |
| New to freight costs? | Ordered path: DIM → accessorial hub → courier vs LTL → contracts → glossary | — |

**FAQ schema** on Start here answers five questions (cost increase, contract eval, unexpected fees, courier vs LTL, where to start).

**Not yet linked from Start here:** `detect_freight_leakage`, `freight_decisions_gross_margin`, `amazon_supply_chain_services_shippers` — strong candidates for a sixth card (“margin / leakage / economics”) or expansion of the cost-diagnosis card.

---

## 8. Glossary

URL: https://yuzhaozhang.com/glossary/

- **~48 terms** (A–Z sections)
- **11 terms** link to existing blog posts (accessorial cluster + DIM + contracts + courier vs LTL)
- **No glossary links yet** to wave 2 articles (leakage, gross margin, Amazon)

When adding articles, update glossary entries for new terms and add “See also” links from related terms.

---

## 9. Home page vs blog index

**Home featured list** (5 articles): contracts, DIM, accessorial hub, audit accessorials, courier vs LTL — does not surface wave 2.

**Blog index** (`blog.html`): all 16 posts, reverse chronological; `data-search` keywords on each card for filter; JSON-LD `ItemList` with `numberOfItems: 16`.

---

## 10. Internal linking graph (simplified)

```mermaid
flowchart TB
  subgraph hub [Accessorial hub]
    FA[freight_accessorial_charges_explained]
  end
  subgraph wave1 [Accessorial deep dives]
    OM[overmax]
    AH[additional_handling]
    OS[oversize_vs_large]
    LG[liftgate]
    LA[limited_access]
    AU[audit_accessorials]
  end
  subgraph foundations [Foundations]
    DIM[dimensional_weight]
    CVL[courier_vs_ltl]
    CC[evaluate_contracts]
  end
  subgraph wave2 [Strategy wave 2 + 3]
    SHK[freight_cost_shock]
    CRP[freight_cost_creep]
    FL[detect_leakage]
    GM[gross_margin]
    AMZ[amazon_scs]
  end
  FA --> OM & AH & OS & LG & LA & AU
  FA --> DIM & CVL & CC
  AMZ --> GM
  SHK <--> CRP
  SHK --> FL & AU
  CRP --> FL & GM & DIM & CC & AU
  CC --> ToolScorecard[carrier-contract-scorecard]
  DIM --> ToolDIM[dimensional-weight-calculator]
```

**Strong cross-link opportunities for new content:**

- Link wave 2/3 into accessorial hub “broader context” footer (currently only DIM, courier vs LTL, contracts)
- Add shock + creep + leakage + gross margin to Start here “cost diagnosis” card
- Glossary entries for “freight leakage,” “freight cost creep,” “freight cost shock,” “GRI,” “billable weight drift”
- Amazon article ↔ courier vs LTL ↔ contracts (partially started)

---

## 11. Topics covered vs open space

### Well covered

- Parcel/LTL accessorial definitions and audit workflow
- Dimensional weight and billable weight
- Courier vs LTL mode choice (multi-piece)
- Carrier contract evaluation framework + scorecard tool
- Freight leakage detection (operator-level)
- Gross margin impact of small freight decisions
- Amazon Supply Chain Services (shipper lens)

### Mentioned but thin or absent (article opportunities)

| Topic | Why it fits the site |
|-------|----------------------|
| Fuel surcharge / GRI mechanics | Now covered in `freight_cost_shock`; a deeper standalone on fuel index math is still viable |
| Residential delivery (parcel + LTL) | In hub table only |
| Freight class / NMFC deep dive | Reweigh/reclass article covers density + class table; room for a dedicated NMFC lookup guide |
| TMS / data / KPIs | Home themes promise this; few dedicated posts yet |
| Practical AI in transportation | Home theme; not a blog cluster yet |
| Returns / reverse logistics | Touches Amazon article only |
| Insurance / claims / liability | In contracts article; room for standalone |
| International / cross-border | Occasional mentions; not a cluster |
| 3PL-specific economics | Audience file; limited 3PL-only articles |

### Suggested sequencing for next articles (for planning agents)

1. **Extend cluster A** — residential delivery (completes accessorial hub table rows; fuel surcharge now covered in `freight_cost_shock`).
2. **Bridge wave 2/3 to Start here** — add shock + creep + leakage to cost diagnosis scenario card; no new posts required.
3. **TMS / data** — aligns with home positioning; differentiate from generic “digital transformation” content.
4. **LTL freight class deep dive** — pairs with DIM calculator, skid builder, and reweigh/reclass article.

---

## 12. Publishing checklist (new article)

From `agent_instructions/blog.md` — every new post must touch:

1. `blog/<slug>/index.html` + `images/`
2. `blog.html` — new `blog-card` + `data-search` keywords
3. `sitemap.xml` — new `<url>` (+ bump blog/home `lastmod` if appropriate)
4. `rss.xml` — new `<entry>` + feed `<updated>`
5. `schema.json` — `Blog.blogPost` entry
6. Meta: canonical, Open Graph, Twitter, JSON-LD `Article`
7. Optional: `llms.txt`, `summary.md` (this file), glossary links, Start here / hub “related” lists, home featured

**Slug style:** lowercase, underscores, descriptive (`how_to_audit_freight_accessorial_charges`).

---

## 13. Voice and quality bar (short)

Full rules: `agent_instructions/sole.md`.

**Non-negotiables for new posts:**

- Section near top: **“What you’ll get from this article”** (4–6 outcome bullets)
- Opening: practical scenario, not dictionary definition
- Answer: problem → why it matters financially/operationally → what to do differently
- At least one example, table, or visual where complexity is high
- Carrier-neutral where thresholds vary; no invented savings percentages
- Internal links to hub, tools, or glossary where relevant

**Audience:** Smart business operators (owners, GMs, ops, finance partners) who may not speak logistics jargon—see `agent_instructions/audience.md`.

---

## 14. Known inconsistencies (fix when convenient)

| Item | Detail |
|------|--------|
| Start here | Omits wave 2/3 strategy articles (shock, creep, leakage, gross margin, Amazon, reweigh) |
| Home featured | Omits wave 2/3 articles |
| Glossary | No links to leakage, gross margin, Amazon, shock, creep posts |
| Hub footer | Accessorial hub “broader context” omits wave 2/3 |
| `blog.md` | Publishing checklist lives at `agent_instructions/blog.md` (root `blog.md` removed) |
| Style split | 6 posts have “What you’ll get”; 7 older posts do not |

---

## 15. Quick reference URLs

| Resource | URL |
|----------|-----|
| Home | https://yuzhaozhang.com/ |
| Blog index | https://yuzhaozhang.com/blog.html |
| Start here | https://yuzhaozhang.com/start-here/ |
| Tools | https://yuzhaozhang.com/tools/ |
| Glossary | https://yuzhaozhang.com/glossary/ |
| Atom feed | https://yuzhaozhang.com/rss.xml |
| Sitemap | https://yuzhaozhang.com/sitemap.xml |
| LLM context | https://yuzhaozhang.com/llms.txt |

---

*When the site changes materially, update this file, `llms.txt`, and `sitemap.xml`/`rss.xml` in the same pass so planning agents and crawlers stay aligned.*