@decocms/apps-blog 7.71.6 → 8.0.0-next.0

package/README.md

@@ -0,0 +1,21 @@
+# `@decocms/apps-blog` (v7 only)
+
+This package is the v7 blog app. It has no next-major surface: the next major
+ships no blog package, and nothing new is added here.
+
+In the next major a blog is content plus code the site owns:
+
+| v7 (this package) | Next major |
+|---|---|
+| `BlogPost`, `Author`, `Category` and the other types | The blog template's own types. |
+| `getRecordsByPath` (reads the global decofile) | `client.list("post")`, `client.list("author")`, `client.list("category")` over saved blocks, with `where` / `sort` / `limit`. It reads the request's revision, so drafts work. |
+| `handlePosts` (filter, sort, paginate) | `client.list` options, or the template's own helper. |
+| `createBlogLoaders` and the `blog/loaders/*.ts` keys | Data-only blocks (`const post = (props: Post) => props`) in the template's block map. The `blog/loaders/*.ts` names stored by v7 content are registered as aliases, or as converter functions where the old shape differs, and loaders the site used are vendored under their old keys by the migration. |
+| `blog/sections/blocks/*.tsx` (post body blocks) | Data-only blocks plus a renderer in the template. |
+| `sections/Seo/SeoBlogPost*.tsx` | SEO helpers in the template. |
+| Ratings, reviews and view-count actions, and the `loaders/extensions/*` ratings/reviews loaders | Site code (see *Migrating from v7*, loaders and actions). |
+
+See the next-major docs: *Data-only blocks* (schema), `client.list` (API
+reference), *Pages and routing*, and *Migrating from v7*.
+
+Port notes for the v7 code are in [`src/README.md`](./src/README.md).

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@decocms/apps-blog",
-  "version": "7.71.6",
+  "version": "8.0.0-next.0",
   "type": "module",
-  "description": "Deco app: blog content and CMS integration",
+  "description": "v7 only: Deco blog app. The next major ships no blog package; blogs use data-only blocks and client.list in their template.",
   "repository": {
     "type": "git",
     "url": "https://github.com/decocms/blocks.git",
@@ -38,9 +38,9 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.71.6",
-    "@decocms/apps-commerce": "7.71.6",
-    "@decocms/apps-website": "7.71.6"
+    "@decocms/blocks": "8.0.0-next.0",
+    "@decocms/apps-commerce": "8.0.0-next.0",
+    "@decocms/apps-website": "8.0.0-next.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/__tests__/categoryTree.test.ts

@@ -0,0 +1,209 @@
+import { describe, expect, it } from "vitest";
+import {
+  ancestorsOf,
+  categoryPathname,
+  childrenOf,
+  descendantSlugs,
+  indexCategories,
+  MAX_CATEGORY_DEPTH,
+  withCategoryPath,
+} from "../core/categoryTree";
+import type { Category } from "../types";
+
+/**
+ * Categories come from a decofile a human types into, so every walk over
+ * `parentSlug` has to survive garbage: a slug pointing at nothing, at itself,
+ * or around a cycle. None of these may hang a request.
+ */
+const cat = (slug: string, parentSlug?: string): Category => ({
+  name: slug.toUpperCase(),
+  slug,
+  ...(parentSlug ? { parentSlug } : {}),
+});
+
+const slugsOf = (chain: Category[] | null) => chain?.map((c) => c.slug) ?? null;
+
+// ---------------------------------------------------------------------------
+// ancestorsOf / indexCategories
+// ---------------------------------------------------------------------------
+describe("ancestorsOf", () => {
+  it("returns the chain root first", () => {
+    const categories = [cat("root"), cat("mid", "root"), cat("leaf", "mid")];
+    const chain = ancestorsOf("leaf", indexCategories(categories));
+
+    expect(slugsOf(chain)).toEqual(["root", "mid", "leaf"]);
+    expect(categoryPathname(chain as Category[])).toEqual("root/mid/leaf");
+  });
+
+  it("returns null for an unknown slug", () => {
+    expect(ancestorsOf("ghost", indexCategories([cat("root")]))).toEqual(null);
+  });
+
+  it("yields no chain on a cycle instead of looping", () => {
+    const categories = [cat("a", "b"), cat("b", "a")];
+    // Walking up from `a` reaches `b`, whose parent is `a` again. The visited set
+    // stops the walk; the chain is reported as unusable rather than truncated,
+    // because a truncated one would name a canonical URL missing its top.
+    expect(ancestorsOf("a", indexCategories(categories))).toEqual(null);
+  });
+
+  it("treats a self-referencing category as a root", () => {
+    expect(slugsOf(ancestorsOf("a", indexCategories([cat("a", "a")])))).toEqual(["a"]);
+  });
+
+  it("stops the walk on a dangling parentSlug", () => {
+    const categories = [cat("leaf", "does-not-exist")];
+    expect(slugsOf(ancestorsOf("leaf", indexCategories(categories)))).toEqual(["leaf"]);
+  });
+
+  it("rejects a chain deeper than MAX_CATEGORY_DEPTH", () => {
+    const chainOf = (length: number) =>
+      Array.from({ length }, (_, i) => cat(`c${i}`, i === 0 ? undefined : `c${i - 1}`));
+
+    const deepest = chainOf(MAX_CATEGORY_DEPTH);
+    expect(ancestorsOf(`c${MAX_CATEGORY_DEPTH - 1}`, indexCategories(deepest))?.length).toEqual(
+      MAX_CATEGORY_DEPTH,
+    );
+
+    // One level past the ceiling: reporting the truncated chain would hand the
+    // canonical URL a path missing its topmost segments, so it reports nothing.
+    const tooDeep = chainOf(MAX_CATEGORY_DEPTH + 1);
+    expect(ancestorsOf(`c${MAX_CATEGORY_DEPTH}`, indexCategories(tooDeep))).toEqual(null);
+  });
+});
+
+describe("indexCategories", () => {
+  it("resolves duplicated slugs to the first record", () => {
+    const first: Category = { name: "First", slug: "dup" };
+    const second: Category = { name: "Second", slug: "dup", parentSlug: "dup" };
+    const index = indexCategories([first, second]);
+
+    expect(index.get("dup")?.name).toEqual("First");
+    expect(index.size).toEqual(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// descendantSlugs / childrenOf
+// ---------------------------------------------------------------------------
+describe("descendantSlugs", () => {
+  it("collects the whole subtree, itself included", () => {
+    const categories = [
+      cat("root"),
+      cat("a", "root"),
+      cat("b", "root"),
+      cat("a1", "a"),
+      cat("other"),
+    ];
+
+    expect(descendantSlugs("root", categories).sort()).toEqual(["a", "a1", "b", "root"]);
+  });
+
+  it("stays finite over a cycle", () => {
+    const categories = [cat("a", "b"), cat("b", "a")];
+    expect(descendantSlugs("a", categories).sort()).toEqual(["a", "b"]);
+  });
+
+  it("of an unknown slug is just the slug", () => {
+    expect(descendantSlugs("ghost", [cat("root")])).toEqual(["ghost"]);
+  });
+});
+
+describe("childrenOf", () => {
+  it("returns direct children, name sorted", () => {
+    const categories = [
+      cat("root"),
+      cat("zeta", "root"),
+      cat("alpha", "root"),
+      cat("deep", "alpha"),
+    ];
+
+    expect(childrenOf("root", categories).map((c) => c.slug)).toEqual(["alpha", "zeta"]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// withCategoryPath
+// ---------------------------------------------------------------------------
+describe("withCategoryPath", () => {
+  it("rewrites the requested path with the real chain", () => {
+    const chain = [cat("root"), cat("leaf", "root")];
+
+    // A request that reached the child through a flat path still gets the one
+    // canonical URL, so Google consolidates instead of seeing duplicates.
+    expect(
+      withCategoryPath("https://x.com/blog/leaf?page=2", chain, { requested: ["leaf"] }),
+    ).toEqual("https://x.com/blog/root/leaf");
+    expect(
+      withCategoryPath("https://x.com/blog/wrong/leaf", chain, { requested: ["wrong", "leaf"] }),
+    ).toEqual("https://x.com/blog/root/leaf");
+  });
+
+  it("declines when the slug isn't in the path", () => {
+    const chain = [cat("root"), cat("leaf", "root")];
+
+    // A listing hardcoded to a category on a plain /blog route: the pathname has
+    // no category segment, so rewriting it would strip the route prefix and
+    // point the canonical at a page that doesn't exist.
+    expect(withCategoryPath("https://x.com/blog", chain, { requested: ["leaf"] })).toEqual(null);
+    expect(withCategoryPath("https://x.com/blog/other", chain, { requested: ["leaf"] })).toEqual(
+      null,
+    );
+    expect(withCategoryPath("https://x.com/blog/leaf", chain, {})).toEqual(null);
+  });
+
+  it("keeps a trailing post slug", () => {
+    const chain = [cat("root"), cat("leaf", "root")];
+    const knownSlugs = new Set(["root", "leaf"]);
+
+    expect(
+      withCategoryPath("https://x.com/blog/leaf/my-post", chain, {
+        knownSlugs,
+        trailing: "my-post",
+      }),
+    ).toEqual("https://x.com/blog/root/leaf/my-post");
+    // A post route with no category segment keeps its own URL: injecting the
+    // chain would canonicalize to a path the site never serves.
+    expect(
+      withCategoryPath("https://x.com/blog/my-post", chain, { knownSlugs, trailing: "my-post" }),
+    ).toEqual(null);
+    // The categories collection failed to load, so nothing is a known slug —
+    // same outcome, rather than doubling the segment already in the path.
+    expect(
+      withCategoryPath("https://x.com/blog/leaf/my-post", chain, {
+        knownSlugs: new Set<string>(),
+        trailing: "my-post",
+      }),
+    ).toEqual(null);
+  });
+
+  it("keeps the route prefix when a category slug collides with it", () => {
+    // Category slugged "blog" on a /blog route. An unbounded strip of trailing
+    // known slugs would eat the prefix too and canonicalize to /blog/my-post,
+    // a path the site never serves.
+    const chain = [cat("blog")];
+
+    expect(
+      withCategoryPath("https://x.com/blog/blog/my-post", chain, {
+        knownSlugs: new Set(["blog"]),
+        trailing: "my-post",
+      }),
+    ).toEqual("https://x.com/blog/blog/my-post");
+  });
+
+  it("encodes each slug as one path segment", () => {
+    // Slugs are hand-authored; a stray "?" would otherwise turn the rest of the
+    // canonical into a query string pointing at a different page.
+    const chain = [cat("a?b"), cat("c/d", "a?b")];
+
+    expect(withCategoryPath("https://x.com/blog/leaf", chain, { requested: ["leaf"] })).toEqual(
+      "https://x.com/blog/a%3Fb/c%2Fd",
+    );
+  });
+
+  it("rewrites nothing with an empty chain", () => {
+    expect(withCategoryPath("https://x.com/blog/leaf?page=2", [], { requested: ["leaf"] })).toEqual(
+      null,
+    );
+  });
+});

package/src/__tests__/handlePosts.test.ts

@@ -123,6 +123,27 @@ describe("filterPostsByCategory", () => {
     const result = filterPostsByCategory(posts, "tech");
     expect(result.find((p) => p.slug === "b")).toBeTruthy();
   });
+
+  /**
+   * A parent category lists its descendants' posts by expanding its slug into
+   * the whole subtree, so the filter has to match on any slug of a list.
+   */
+  it("matches a post in any slug of a list", () => {
+    const inCategory = (slug: string) =>
+      makePost({ slug: `post-${slug}`, categories: [{ name: slug, slug }] });
+    const tree = [inCategory("root"), inCategory("child"), inCategory("other")];
+
+    expect(filterPostsByCategory(tree, ["root", "child"]).map((p) => p.slug)).toEqual([
+      "post-root",
+      "post-child",
+    ]);
+    expect(filterPostsByCategory(tree, "child").map((p) => p.slug)).toEqual(["post-child"]);
+    // No slug at all means no category filter, same as before.
+    expect(filterPostsByCategory(tree)).toHaveLength(3);
+    // An empty list is an explicit empty set of categories, which nothing
+    // belongs to — diverges from upstream, which answers every post here.
+    expect(filterPostsByCategory(tree, [])).toEqual([]);
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -193,6 +214,11 @@ describe("filterRelatedPosts", () => {
     const result = filterRelatedPosts(posts, ["news"]);
     expect(result.find((p) => p.slug === "c")).toBeUndefined();
   });
+
+  // Opposite of filterPostsByCategory, which reads an empty list as "no filter".
+  it("relates nothing on an empty slug list", () => {
+    expect(filterRelatedPosts(posts, [])).toEqual([]);
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/__tests__/loaders.test.ts

@@ -100,6 +100,22 @@ describe("BlogRelatedPostsLoader", () => {
     mockGetRecords.mockReturnValue([]);
     expect(await BlogRelatedPostsLoader({})).toBeNull();
   });
+
+  // A post with no categories arrives here as `slug: []`. Answering the whole
+  // blog would turn "related posts" into a second listing of everything.
+  it("returns null for an empty category list, not every post", async () => {
+    expect(await BlogRelatedPostsLoader({ slug: [] })).toBeNull();
+  });
+
+  it("still relates on a non-empty category list", async () => {
+    mockGetRecords.mockReturnValue([
+      makePost({ slug: "in", categories: [{ name: "News", slug: "news" }] }),
+      makePost({ slug: "out", categories: [{ name: "Tech", slug: "tech" }] }),
+    ]);
+
+    const result = await BlogRelatedPostsLoader({ slug: ["news"] });
+    expect(result?.map((p) => p.slug)).toEqual(["in"]);
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -185,6 +201,34 @@ describe("GetCategories", () => {
     mockGetRecords.mockReturnValue([]);
     expect(GetCategories({})).toBeNull();
   });
+
+  describe("parentSlug", () => {
+    const nested: Category[] = [
+      { name: "Root", slug: "root" },
+      { name: "Zeta", slug: "zeta", parentSlug: "root" },
+      { name: "Alpha", slug: "alpha", parentSlug: "root" },
+      { name: "Deep", slug: "deep", parentSlug: "alpha" },
+    ];
+
+    beforeEach(() => {
+      mockGetRecords.mockReturnValue([...nested]);
+    });
+
+    it("returns only direct children, not the whole subtree", () => {
+      const result = GetCategories({ parentSlug: "root" });
+      expect(result!.map((c) => c.slug)).toEqual(["Alpha", "Zeta"].map((n) => n.toLowerCase()));
+    });
+
+    it("slices the scoped children by count", () => {
+      expect(GetCategories({ parentSlug: "root", count: 1 })!.map((c) => c.slug)).toEqual([
+        "alpha",
+      ]);
+    });
+
+    it("returns an empty list for a category with no children", () => {
+      expect(GetCategories({ parentSlug: "deep" })).toEqual([]);
+    });
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/client.ts

@@ -29,11 +29,12 @@ export interface BlogSeoDefaults {
 
 export interface BlogConfig {
   /**
-   * Slug pattern of the category route, e.g. `/blog/:category`.
+   * Slug pattern of the category route, e.g. `/blog/:category*`. Categories can
+   * nest, so the route must be a catch-all for subcategories to resolve.
    */
   categorySlug?: string;
   /**
-   * Slug pattern of the post route, e.g. `/blog/:category/:slug`.
+   * Slug pattern of the post route, e.g. `/blog/:category*\/:slug`.
    */
   pageSlug?: string;
   /**

package/src/core/categoryTree.ts

@@ -0,0 +1,210 @@
+import type { Category } from "../types";
+
+/**
+ * Categories come from a decofile a human edits by hand, so `parentSlug` can
+ * point at nothing, at itself, or back into a cycle. Every walk below is
+ * bounded twice — by a visited set and by this ceiling — so a malformed record
+ * can never hang a request.
+ */
+export const MAX_CATEGORY_DEPTH = 4;
+
+const isValid = (c?: Category | null): c is Category =>
+  !!c &&
+  typeof c.slug === "string" &&
+  c.slug.length > 0 &&
+  typeof c.name === "string" &&
+  c.name.length > 0;
+
+/** Slug -> category. First entry wins when a slug is duplicated. */
+export const indexCategories = (
+  categories: Category[] | null | undefined,
+): Map<string, Category> => {
+  const index = new Map<string, Category>();
+  for (const category of categories ?? []) {
+    if (isValid(category) && !index.has(category.slug)) {
+      index.set(category.slug, category);
+    }
+  }
+  return index;
+};
+
+const parentOf = (category: Category, index: Map<string, Category>): Category | undefined => {
+  const parentSlug = category.parentSlug;
+  if (typeof parentSlug !== "string" || !parentSlug || parentSlug === category.slug) {
+    return undefined;
+  }
+  return index.get(parentSlug);
+};
+
+/**
+ * The ancestor chain of `slug`, root first and the category itself last —
+ * exactly the breadcrumb sequence.
+ *
+ * Returns null whenever the chain cannot be trusted: the slug is unknown, the
+ * walk ran into a cycle, or it went past MAX_CATEGORY_DEPTH. A truncated chain
+ * is worse than none — it would name a breadcrumb and a canonical URL missing
+ * their topmost segments — so callers fall back to the flat behaviour instead.
+ * A dangling `parentSlug` or a self-reference is not an error: the walk just
+ * ends there, treating the category as a root.
+ */
+export const ancestorsOf = (slug: string, index: Map<string, Category>): Category[] | null => {
+  const start = index.get(slug);
+  if (!start) {
+    return null;
+  }
+
+  const chain: Category[] = [];
+  const seen = new Set<string>();
+  let current: Category | undefined = start;
+
+  while (current) {
+    if (seen.has(current.slug) || chain.length >= MAX_CATEGORY_DEPTH) {
+      return null;
+    }
+    seen.add(current.slug);
+    chain.push(current);
+    current = parentOf(current, index);
+  }
+
+  return chain.reverse();
+};
+
+/** Children indexed by parent slug, skipping self-references. */
+const childrenIndex = (categories: Category[]): Map<string, Category[]> => {
+  const children = new Map<string, Category[]>();
+  for (const category of categories) {
+    const parentSlug = category.parentSlug;
+    if (
+      !isValid(category) ||
+      typeof parentSlug !== "string" ||
+      !parentSlug ||
+      parentSlug === category.slug
+    ) {
+      continue;
+    }
+    const siblings = children.get(parentSlug);
+    siblings ? siblings.push(category) : children.set(parentSlug, [category]);
+  }
+  return children;
+};
+
+/**
+ * `slug` plus every category below it. Breadth-first with a visited set, so a
+ * cycle yields a finite set instead of looping. Used to make a parent category
+ * list its children's posts.
+ */
+export const descendantSlugs = (
+  slug: string,
+  categories: Category[] | null | undefined,
+): string[] => {
+  const children = childrenIndex(categories ?? []);
+  const seen = new Set<string>([slug]);
+  let frontier = [slug];
+
+  for (let depth = 0; depth < MAX_CATEGORY_DEPTH && frontier.length; depth++) {
+    const next: string[] = [];
+    for (const parent of frontier) {
+      for (const child of children.get(parent) ?? []) {
+        if (!seen.has(child.slug)) {
+          seen.add(child.slug);
+          next.push(child.slug);
+        }
+      }
+    }
+    frontier = next;
+  }
+
+  return [...seen];
+};
+
+/** Direct children of `slug`, name-sorted. */
+export const childrenOf = (slug: string, categories: Category[] | null | undefined): Category[] =>
+  (childrenIndex(categories ?? []).get(slug) ?? []).sort((a, b) => a.name.localeCompare(b.name));
+
+/** "pai/filho" — the URL path a category chain occupies. */
+export const categoryPathname = (chain: Category[]): string => chain.map((c) => c.slug).join("/");
+
+interface PathOptions {
+  /**
+   * The category segments the router handed the loader. They must be the tail
+   * of the pathname, otherwise the slug was configured by hand and the URL
+   * carries no category to rewrite.
+   */
+  requested?: string[];
+  /**
+   * Known category slugs, for routes that don't hand the category over — the
+   * category segments are the trailing ones that name a real category.
+   */
+  knownSlugs?: Set<string>;
+  /** Segment that stays at the end of the path — a post slug. */
+  trailing?: string;
+}
+
+/**
+ * Rewrites the category portion of a URL with the canonical chain, keeping the
+ * route prefix (`/blog`) and an optional trailing post slug. A request that
+ * reaches a child through a stale or wrong path still renders; this is what
+ * points its canonical at the one true URL so Google consolidates instead of
+ * seeing duplicates.
+ *
+ * Returns null when the URL has no category portion to replace — a route
+ * without a category segment, or a slug that didn't come from the route. The
+ * caller keeps the request URL rather than inventing a path that 404s.
+ */
+export const withCategoryPath = (
+  url: string | URL,
+  chain: Category[],
+  { requested, knownSlugs, trailing }: PathOptions = {},
+): string | null => {
+  if (chain.length === 0) {
+    return null;
+  }
+
+  const parsed = new URL(url);
+  let segments = parsed.pathname.split("/").filter(Boolean);
+
+  if (trailing) {
+    if (segments[segments.length - 1] !== trailing) {
+      return null;
+    }
+    segments = segments.slice(0, -1);
+  }
+
+  if (requested) {
+    const size = requested.length;
+    const tail = segments.slice(Math.max(segments.length - size, 0));
+    if (size === 0 || tail.join("/") !== requested.join("/")) {
+      return null;
+    }
+    segments = segments.slice(0, segments.length - size);
+  } else if (knownSlugs) {
+    const before = segments.length;
+    // Bounded by the chain length: the request can carry at most as many
+    // category segments as the canonical chain has. Without the bound, a
+    // category whose slug collides with the route prefix — `/blog/blog/a-post`
+    // for a category slugged "blog" — strips the prefix too and canonicalizes
+    // to a path the site never serves.
+    while (
+      segments.length &&
+      before - segments.length < chain.length &&
+      knownSlugs.has(segments[segments.length - 1])
+    ) {
+      segments = segments.slice(0, -1);
+    }
+    if (segments.length === before) {
+      return null;
+    }
+  } else {
+    return null;
+  }
+
+  // Slugs are authored by hand, so a stray "/", "?" or "#" would otherwise stop
+  // being one path segment and start being a new segment, a query or a
+  // fragment. Encoded, a malformed slug yields a 404 instead of a canonical
+  // pointing at a different page.
+  const pathname = `/${[...segments, ...chain.map((c) => c.slug), ...(trailing ? [trailing] : [])]
+    .map(encodeURIComponent)
+    .join("/")}`;
+
+  return new URL(pathname, parsed.origin).href;
+};

package/src/core/handlePosts.ts

@@ -80,10 +80,22 @@ export const sortPosts = async (blogPosts: BlogPost[], sortBy: SortBy): Promise<
  * Returns a filtered BlogPost list.
  *
  * @param posts Posts to be handled
- * @param slug Category slug to filter by
+ * @param slug Category slug, or a list of slugs a post may belong to any of.
+ *   A list is how a parent category pulls in its descendants' posts.
+ *
+ * An omitted slug means "no category filter" and keeps every post. An *empty
+ * list* is the opposite — an explicit, empty set of categories to match, which
+ * nothing belongs to. Upstream conflates the two and answers every post to
+ * both, which turns a related-posts widget for a post with no categories into
+ * a second listing of the whole blog.
  */
-export const filterPostsByCategory = (posts: BlogPost[], slug?: string): BlogPost[] =>
-  slug ? posts.filter(({ categories }) => categories?.find((c) => c.slug === slug)) : posts;
+export const filterPostsByCategory = (posts: BlogPost[], slug?: string | string[]): BlogPost[] => {
+  if (slug === undefined || slug === "") {
+    return posts;
+  }
+  const slugs = new Set(Array.isArray(slug) ? slug : [slug]);
+  return posts.filter(({ categories }) => categories?.some((c) => slugs.has(c?.slug)));
+};
 
 /** Filter posts whose slug is in the given list. */
 export const filterPostsBySlugs = (posts: BlogPost[], postSlugs: string[]): BlogPost[] =>
@@ -97,7 +109,7 @@ export const filterPostsByTerm = (posts: BlogPost[], term: string): BlogPost[] =
 
 /** Filter posts whose categories overlap with the given slug array. */
 export const filterRelatedPosts = (posts: BlogPost[], slugs: string[]): BlogPost[] =>
-  posts.filter(({ categories }) => categories?.find((c) => slugs.includes(c.slug)));
+  filterPostsByCategory(posts, slugs);
 
 /** Slice posts for pagination. */
 export const slicePosts = (
@@ -134,19 +146,12 @@ const filterPosts = (
 ): BlogPost[] => {
   const posts = filterRoutablePosts(allPosts);
 
-  if (typeof slug === "string") {
-    const firstFilter =
-      postSlugs && postSlugs.length > 0
-        ? filterPostsBySlugs(posts, postSlugs)
-        : filterPostsByCategory(posts, slug);
-
-    return term ? filterPostsByTerm(firstFilter, term) : firstFilter;
-  }
-  if (Array.isArray(slug)) {
-    return filterRelatedPosts(posts, slug);
-  }
+  const byCategory =
+    postSlugs && postSlugs.length > 0
+      ? filterPostsBySlugs(posts, postSlugs)
+      : filterPostsByCategory(posts, slug);
 
-  return term ? filterPostsByTerm(posts, term) : posts;
+  return term ? filterPostsByTerm(byCategory, term) : byCategory;
 };
 
 /**

package/src/loaders/BlogPostPage.ts

@@ -1,9 +1,13 @@
+import { logger, serializeError } from "@decocms/blocks/sdk/logger";
+import { ancestorsOf, indexCategories, withCategoryPath } from "../core/categoryTree";
 import { getRecordsByPath } from "../core/records";
-import type { BlogPost, BlogPostPage } from "../types";
+import type { BlogPost, BlogPostPage, Category } from "../types";
 import { isLivePost } from "../types";
 
 const COLLECTION_PATH = "collections/blog/posts";
 const ACCESSOR = "post";
+const CATEGORIES_PATH = "collections/blog/categories";
+const CATEGORY_ACCESSOR = "category";
 
 export interface Props {
   slug: string;
@@ -26,13 +30,41 @@ export default function BlogPostPageLoader(
 
   if (!post) return null;
 
+  // The post lives under the full path of its primary category, so the
+  // breadcrumb and the canonical need that category's ancestor chain. A broken
+  // categories collection must not take the post page down with it.
+  let categories: Category[] = [];
+  try {
+    categories = getRecordsByPath<Category>(CATEGORIES_PATH, CATEGORY_ACCESSOR) ?? [];
+  } catch (e) {
+    const error = serializeError(e);
+    logger.error(error.message, { error, scope: "blog/BlogPostPage/categories" });
+  }
+
+  const primarySlug = post.categories?.[0]?.slug;
+  const chain =
+    typeof primarySlug === "string" && primarySlug
+      ? ancestorsOf(primarySlug, indexCategories(categories))
+      : null;
+
+  // Only a chain that came out of the records is trustworthy enough to name a
+  // canonical URL; withCategoryPath itself returns null when the route has no
+  // category segment to replace, so a /blog/:slug site keeps its own URL.
+  const canonical = chain
+    ? withCategoryPath(url, chain, {
+        knownSlugs: new Set(categories.map((c) => c?.slug)),
+        trailing: post.slug,
+      })
+    : null;
+
   return {
     "@type": "BlogPostPage",
     post,
+    categories: chain ?? (post.categories?.[0] ? [post.categories[0]] : null),
     seo: {
       title: post?.seo?.title || post?.title,
       description: post?.seo?.description || post?.excerpt,
-      canonical: post?.seo?.canonical || url.href,
+      canonical: post?.seo?.canonical || canonical || url.href,
       image: post?.seo?.image || post?.image,
       // A post that isn't live yet — unpublished, or scheduled for an instant
       // still ahead — renders anyway, because that page *is* the CMS preview.

package/src/loaders/BlogpostList.ts

@@ -1,10 +1,13 @@
 import { logger, serializeError } from "@decocms/blocks/sdk/logger";
+import { descendantSlugs } from "../core/categoryTree";
 import handlePosts, { slicePosts } from "../core/handlePosts";
 import { getRecordsByPath } from "../core/records";
-import type { BlogPost, SortBy } from "../types";
+import type { BlogPost, Category, SortBy } from "../types";
 
 const COLLECTION_PATH = "collections/blog/posts";
 const ACCESSOR = "post";
+const CATEGORIES_PATH = "collections/blog/categories";
+const CATEGORY_ACCESSOR = "category";
 
 export interface Props {
   /**
@@ -19,7 +22,9 @@ export interface Props {
   page?: number;
   /**
    * @title Category Slug
-   * @description Filter by a specific category slug.
+   * @description Filter by a category slug. May be a full path
+   * ("parent/child"); posts of every subcategory below the last segment are
+   * included.
    */
   slug?: string;
   /**
@@ -58,7 +63,22 @@ export default async function BlogPostList(
   const posts = getRecordsByPath<BlogPost>(COLLECTION_PATH, ACCESSOR);
 
   try {
-    const handledPosts = await handlePosts(posts, pageSort, slug, postSlugs, term);
+    // A parent category also lists its descendants' posts, so the slug expands
+    // into the whole subtree below it.
+    const leafSlug = (slug ?? "").split("/").filter(Boolean).pop();
+    let categorySlugs: string | string[] | undefined = leafSlug;
+
+    if (leafSlug && !postSlugs?.length) {
+      try {
+        const categories = getRecordsByPath<Category>(CATEGORIES_PATH, CATEGORY_ACCESSOR);
+        categorySlugs = descendantSlugs(leafSlug, categories);
+      } catch (e) {
+        const error = serializeError(e);
+        logger.error(error.message, { error, scope: "blog/BlogpostList/categories" });
+      }
+    }
+
+    const handledPosts = await handlePosts(posts, pageSort, categorySlugs, postSlugs, term);
 
     if (!handledPosts) return null;
 

package/src/loaders/BlogpostListing.ts

@@ -1,4 +1,10 @@
 import { logger, serializeError } from "@decocms/blocks/sdk/logger";
+import {
+  ancestorsOf,
+  descendantSlugs,
+  indexCategories,
+  withCategoryPath,
+} from "../core/categoryTree";
 import handlePosts, { slicePosts } from "../core/handlePosts";
 import { getRecordsByPath } from "../core/records";
 import type { BlogPost, BlogPostListingPage, Category, PageInfo, SortBy } from "../types";
@@ -11,7 +17,9 @@ const CATEGORY_ACCESSOR = "category";
 export interface Props {
   /**
    * @title Category Slug
-   * @description Filter by a specific category slug.
+   * @description Filter by a category slug. May be a full path
+   * ("parent/child"); posts of every subcategory below the last segment are
+   * included.
    */
   slug?: string;
   /**
@@ -72,13 +80,6 @@ export default async function BlogPostListing(
   const posts = getRecordsByPath<BlogPost>(COLLECTION_PATH, ACCESSOR);
 
   try {
-    const handledPosts = await handlePosts(posts, pageSort, slug, undefined, term);
-
-    if (!handledPosts) return null;
-
-    const slicedPosts = slicePosts(handledPosts, pageNumber, postsPerPage);
-    if (slicedPosts.length === 0) return null;
-
     let categories: Category[] | null = null;
     try {
       categories = loadCategories();
@@ -86,24 +87,52 @@ export default async function BlogPostListing(
       report("blog/BlogpostListing/categories", e);
     }
 
+    // The slug prop carries the whole category path ("pai/filho") when the
+    // site routes the listing as a catch-all; only the leaf identifies the
+    // category, the segments before it are its ancestors.
+    const requestedSegments = (slug ?? "").split("/").filter(Boolean);
+    const leafSlug = requestedSegments[requestedSegments.length - 1];
+
+    const index = indexCategories(categories);
+    const chain = leafSlug ? ancestorsOf(leafSlug, index) : null;
+
+    // A parent lists its own posts plus every descendant's.
+    const categorySlugs = leafSlug ? descendantSlugs(leafSlug, categories) : undefined;
+
+    const handledPosts = await handlePosts(posts, pageSort, categorySlugs, undefined, term);
+
+    if (!handledPosts) return null;
+
+    const slicedPosts = slicePosts(handledPosts, pageNumber, postsPerPage);
+    if (slicedPosts.length === 0) return null;
+
     let category: Category | null = null;
-    if (slug) {
+    if (leafSlug) {
       // Prefer the standalone category record (it carries description and
       // sections); fall back to the denormalized copy embedded in a post,
       // which is all a site that never created category records will have.
-      category = categories?.find((c) => c.slug === slug) ?? null;
-      category ??= slicedPosts[0]?.categories?.find((c) => c.slug === slug) ?? null;
+      category =
+        index.get(leafSlug) ??
+        slicedPosts[0]?.categories?.find((c) => c?.slug === leafSlug) ??
+        null;
     }
 
+    // Only a chain that came out of the records is trustworthy enough to name
+    // a canonical URL; a missing or broken one keeps the flat behaviour.
+    const canonical = chain ? withCategoryPath(url, chain, { requested: requestedSegments }) : null;
+
     return {
       posts: slicedPosts,
       category,
       categories,
+      categoryPath: chain ?? (category ? [category] : null),
       pageInfo: toPageInfo(handledPosts, postsPerPage, pageNumber, params),
       seo: {
         title: category?.name ?? "",
         description: category?.description,
-        canonical: new URL(url.pathname, url.origin).href,
+        // Reached through a stale or wrong path, the page still renders and
+        // points at the one canonical URL instead of 404ing.
+        canonical: canonical ?? new URL(url.pathname, url.origin).href,
       },
     };
   } catch (e) {

package/src/loaders/GetCategories.ts

@@ -1,3 +1,4 @@
+import { childrenOf } from "../core/categoryTree";
 import { getRecordsByPath } from "../core/records";
 import type { Category } from "../types";
 
@@ -10,6 +11,11 @@ export interface Props {
    * @description Get the category data from a specific slug.
    */
   slug?: string;
+  /**
+   * @title Parent category slug
+   * @description Return only the direct children of this category.
+   */
+  parentSlug?: string;
   /**
    * @title Items count
    * @description Number of categories to return
@@ -29,6 +35,7 @@ export interface Props {
 export default function GetCategories({
   count,
   slug,
+  parentSlug,
   sortBy = "title_desc",
 }: Props): Category[] | null {
   const categories = getRecordsByPath<Category>(COLLECTION_PATH, ACCESSOR);
@@ -53,7 +60,9 @@ export default function GetCategories({
 
   if (!validCategories.length) return null;
 
-  const sortedCategories = validCategories.sort((a, b) => {
+  const scoped = parentSlug ? childrenOf(parentSlug, validCategories) : validCategories;
+
+  const sortedCategories = scoped.sort((a, b) => {
     const comparison = a.name.localeCompare(b.name);
     return sortBy.endsWith("_desc") ? comparison : -comparison;
   });

package/src/mod.ts

@@ -22,14 +22,16 @@ import type { Publisher } from "./types";
 export interface Props {
   /**
    * @title Category Slug
-   * @description The slug of the Categories of the blogposts. Use :category
-   * @example /blog/:category
+   * @description The slug of the Categories of the blogposts. Use :category.
+   * Categories can nest, so the route must be a catch-all for subcategories to
+   * resolve.
+   * @example /blog/:category*
    */
   categorySlug?: string;
   /**
    * @title Page Slug
    * @description The slug of the BlogPostPage to embed. Use :category and :slug.
-   * @example /blog/:category/:slug
+   * @example /blog/:category*\/:slug
    */
   pageSlug?: string;
   /**

package/src/sections/Seo/SeoBlogPost.tsx

@@ -52,7 +52,9 @@ export function loader(props: Props, req?: Request, seo?: BlogSeoDefaults) {
         toBlogPosting(jsonLD.post, pageUrl, publisher),
         toBreadcrumbList(pageUrl, {
           currentName: jsonLD.post.title,
-          categories: jsonLD.post.categories,
+          // The ancestor chain, so every category segment of the canonical path
+          // resolves to its real name instead of a humanized slug.
+          categories: jsonLD.categories ?? jsonLD.post.categories,
         }),
       ]
     : [];

package/src/sections/Template.tsx

@@ -51,22 +51,27 @@ export default function Template({ post }: Props) {
     excerpt = "Excerpt",
     date,
     image,
+    mobileImage,
     alt,
     sections,
     slug,
     categories,
   } = post;
 
+  // Only the leaf slug, not the ancestor path: resolving the chain needs
+  // `getRecordsByPath`, which pulls the server-only `@decocms/blocks/cms`
+  // entry into this client-reachable section. The preview iframe lands on the
+  // flat URL, which still renders.
   const postCategorySlug = categories?.[0]?.slug ?? "";
 
   if (pageSlug) {
-    const resolvedUrl = pageSlug.replace(":category", postCategorySlug).replace(":slug", slug);
+    const resolvedUrl = pageSlug.replace(/:category\*?/, postCategorySlug).replace(":slug", slug);
 
     return <iframe src={resolvedUrl} style={iframeStyle} title={title} />;
   }
 
   if (categorySlug) {
-    const resolvedUrl = categorySlug.replace(":category", postCategorySlug);
+    const resolvedUrl = categorySlug.replace(/:category\*?/, postCategorySlug);
 
     return <iframe src={resolvedUrl} style={iframeStyle} title={title} />;
   }
@@ -87,7 +92,12 @@ export default function Template({ post }: Props) {
               })
             : ""}
         </p>
-        {image && <img className="w-full rounded-2xl bg-cover" src={image} alt={alt ?? title} />}
+        {image && (
+          <picture>
+            {mobileImage && <source media="(max-width: 767px)" srcSet={mobileImage} />}
+            <img className="w-full rounded-2xl bg-cover" src={image} alt={alt ?? title} />
+          </picture>
+        )}
         <div dangerouslySetInnerHTML={{ __html: content as string }} />
         <div className="content-sections">{sections?.map(renderSection)}</div>
       </div>

package/src/sections/blocks/BlockImage.tsx

@@ -1,17 +1,38 @@
 export type Props = {
   url: string;
+  /** @description Optional mobile-optimized image. Served below 768px. */
+  mobileUrl?: string;
   alt?: string;
   caption?: string;
   size?: "full" | "normal";
+  /** @description Loads eagerly with high fetch priority. Use for above-the-fold images. */
+  highPriority?: boolean;
 };
 
-export default function BlockImage({ url, alt, caption, size }: Props) {
+export default function BlockImage({
+  url,
+  mobileUrl,
+  alt,
+  caption,
+  size,
+  highPriority = false,
+}: Props) {
   const wrapperClass = size === "full" ? "my-8 -mx-[var(--gutter)]" : "my-8";
 
   return (
     <figure className={wrapperClass}>
       <div className="overflow-hidden bg-alt">
-        <img src={url} alt={alt ?? ""} loading="lazy" className="w-full h-auto block" />
+        <picture>
+          {mobileUrl && <source media="(max-width: 767px)" srcSet={mobileUrl} />}
+          <img
+            src={url}
+            alt={alt ?? ""}
+            {...(highPriority
+              ? { loading: "eager" as const, fetchPriority: "high" as const }
+              : { loading: "lazy" as const, decoding: "async" as const })}
+            className="w-full h-auto block"
+          />
+        </picture>
       </div>
       {caption && (
         <figcaption className="text-sm text-tertiary text-center mt-3 italic">{caption}</figcaption>

package/src/types.ts

@@ -36,12 +36,18 @@ export interface Author {
   avatar?: ImageWidget;
   jobTitle?: string;
   company?: string;
+  url?: string;
 }
 
 export interface Category {
   name: string;
   slug: string;
   description?: string;
+  /**
+   * @title Parent category
+   * @description Slug of the parent category. Leave empty for a root category.
+   */
+  parentSlug?: string;
   /**
    * @title Sections
    * @label hidden
@@ -61,6 +67,11 @@ export interface BlogPost {
    * @title Alt text for the image
    */
   alt?: string;
+  /**
+   * @title Mobile image
+   * @description Optional mobile-optimized version of the main image. Served below 768px. Falls back to the main image when empty.
+   */
+  mobileImage?: ImageWidget;
   /**
    * @widget blog
    * @collection authors
@@ -220,6 +231,11 @@ export interface Publisher {
 export interface BlogPostPage {
   "@type": "BlogPostPage";
   post: BlogPost;
+  /**
+   * @title Category path
+   * @description Ancestor chain of the post's primary category, root first.
+   */
+  categories?: Category[] | null;
   seo?: Seo | null;
 }
 
@@ -237,6 +253,11 @@ export interface BlogPostListingPage {
   category?: Category | null;
   /** @title Categories */
   categories?: Category[] | null;
+  /**
+   * @title Category path
+   * @description Ancestor chain of the active category, root first.
+   */
+  categoryPath?: Category[] | null;
   pageInfo: PageInfo;
   seo: Seo;
 }

package/src/utils/blocksToSections.ts

@@ -123,9 +123,14 @@ function blockToSection(
       case "image":
         return toSection(`${BASE}/BlockImage.tsx`, {
           url: content.url,
+          mobileUrl: content.mobileUrl,
           alt: content.alt,
           caption: content.caption,
           size: content.size,
+          // Upstream does not forward this, which leaves every block-pipeline
+          // image lazy-loaded and the prop reachable only on a hand-placed
+          // BlockImage section.
+          highPriority: content.highPriority,
         });
 
       case "video":

package/src/utils/jsonLD.ts

@@ -5,6 +5,9 @@ const toAuthor = (author: Author) => {
   return {
     "@type": type,
     name: author.name,
+    // url and image are valid on both Person and Organization
+    ...(author.url ? { url: author.url } : {}),
+    ...(author.avatar ? { image: author.avatar } : {}),
     // jobTitle and worksFor are Person-only properties
     ...(type === "Person" && author.jobTitle ? { jobTitle: author.jobTitle } : {}),
     ...(type === "Person" && author.company