[WordPress → Astro] Phần 6 – Xuất custom taxonomy và hỗ trợ phân cấp

Sau khi hoàn thành [Phần 4], blog Astro của mình đã chạy ngon trên Cloudflare Workers. Nhưng như đã đề cập trong bài viết, vẫn còn một số việc cần xử lý trước khi chính thức “khai tử” WordPress:

Trang category/tag đang hiển thị slug thay vì tên đầy đủ — ví dụ du-lich thay vì “Du Lịch”
Custom taxonomy (như destination) chưa được xuất ra khi chạy chuyển đổi từ xml qua markdown
Category chưa có cấu trúc phân cấp như bên WordPress

Bài viết [Phần 6] sẽ hướng dẫn cách mình khắc phục 3 vấn đề trên, sẵn sàng chính thức tắt WordPress và chuyển nhà cho blog balodeplao.com qua Astro.

I. Chi tiết về các vấn đề hiện tại

Khi chạy công cụ wordpress-export-to-markdown để chuyển nội dung WordPress sang file Markdown, frontmatter của mỗi bài viết sẽ trông như thế này:

1
---
2
title: "3 ngày ở Tokyo"
3
date: 2024-11-10
4
categories:
5
  - du-lich
6
tags:
7
  - nhat-ban
8
---

Nhìn qua thì có thể tạm ổn, nhưng trên thực tế phần frontmatter đang thiếu khá nhiều thứ:

Custom taxonomy bị bỏ qua hoàn toàn. Blog balodeplao.com của mình có taxonomy destination để gắn địa điểm cho bài viết — ví dụ Japan, Taiwan, Việt Nam. Sau khi export, toàn bộ thông tin này biến mất.
Category và tag chỉ có slug, không có tên đầy đủ. du-lich là slug, còn tên thật là “Du Lịch”. Khi Astro render trang category, nó dùng slug để hiển thị tiêu đề → vừa không thân thiện, vừa ảnh hưởng SEO.
Không có metadata cho taxonomy. Bên WordPress, mỗi category/tag có đầy đủ thông tin: tên hiển thị, mô tả, category cha (parent). Toàn bộ thông tin đó nằm trong file XML xuất ra nhưng công cụ bỏ qua các thông tin khi xử lý chuyển đổi qua markdown.

Trên thực tế, thông tin về custom taxonomy và metadata cho taxonomy đều có sẵn trong file xml khi xuất nội dung từ WordPress.

1
<!-- Metadata của category, có thông tin parent để xây phân cấp -->
2
<wp:category>
3
  <wp:category_nicename>chau-a</wp:category_nicename>
4
  <wp:cat_name><![CDATA[Châu Á]]></wp:cat_name>
5
  <wp:category_parent>du-lich</wp:category_parent>
6
  <wp:category_description><![CDATA[Các bài viết du lịch Châu Á]]></wp:category_description>
7
</wp:category>
8

9
<!-- Metadata của tag -->
10
<wp:tag>
11
  <wp:tag_slug>nhat-ban</wp:tag_slug>
12
  <wp:tag_name><![CDATA[Nhật Bản]]></wp:tag_name>
13
</wp:tag>
14

15
<!-- Metadata của custom taxonomy term -->
16
<wp:term>
17
  <wp:term_taxonomy>destination</wp:term_taxonomy>
18
  <wp:term_slug>japan</wp:term_slug>
19
  <wp:term_name><![CDATA[Japan]]></wp:term_name>
20
  <wp:term_parent></wp:term_parent>
21
</wp:term>

Vấn đề nằm ở chỗ công cụ wordpress-export-to-markdown không hỗ trợ xử lý custom taxonomy và metadata cho custom taxonomy.

II. Giải pháp: fork và bổ sung tính năng

Để giải quyết những vấn đề kể trên, mình quyết định fork công cụ wordpress-export-to-markdown và bổ sung thêm 2 tính năng cần thiết:

Hỗ trợ xử lý custom taxonomy cho từng bài viết: ghi vào frontmatter tương ứng.
Xử lý thông ting metadata cho taxonomy: đọc các block <wp:category>, <wp:tag>, <wp:term> và xuất ra file taxonomies.json.

Mọi người có thể tham khảo bản fork của mình ở đây:

https://github.com/10h30/wordpress-export-to-markdown/tree/feat/add_custom_taxonomy

1. Xử lý lại file xml

Để xử lý lại file markdown, cần phải clone repo này về máy

1
git clone -b feat/add_custom_taxonomy https://github.com/10h30/wordpress-export-to-markdown.git

Truy cập vào thư mục và cài đặt package

1
cd wordpress-export-to-markdown
2
npm install

Sau đó chạy lệnh sau để chuyển đổi file xml qua markdown.

1
node app \
2
  --prefix-date=true \
3
  --post-folders=false \
4
  --frontmatter-fields=title,author,date:pubDatetime,categories,tags,coverImage:image,draft,slug \
5
  --save-images=all \
6
  --date-folders=none \
7
  --include-custom-taxonomies=true \
8
  --save-taxonomy-data=true

2. Kết quả frontmatter sau khi sửa

Phần frontmatter của các file md giờ đã có thêm thông tin về Custom taxonomy destination

1
---
2
title: "3 ngày ở Tokyo"
3
date: 2024-11-10
4
categories:
5
  - du-lich
6
tags:
7
  - nhat-ban
8
destination:
9
  - japan
10
  - tokyo
11
---

3. Kết quả taxonomies.json

Trong thư mục output giờ sẽ có thêm thư mục taxonomies, gồm các file json của từng custom taxonomy.

1
taxonomies
2
├── advanced_ads_groups.json
3
├── category.json
4
├── cp_campaign.json
5
├── cp_connections.json
6
├── destination.json
7
├── nav_menu.json
8
└── post_tag.json

Và đây là nội dung của file category.json

1
[
2
  {
3
    "slug": "an-uong",
4
    "name": "Ẩm Thực",
5
    "description": "Cẩm nang trải nghiệm ẩm thực, giới thiệu các quán ăn ngon của Ba Lô Dép Lào"
6
  },
7
  {
8
    "slug": "cong-viec",
9
    "name": "Công Việc"
10
  },
11
  {
12
    "slug": "du-lich",
13
    "name": "Du Lịch",
14
    "description": "Chia sẻ trải nghiệm, kinh nghiệm du lịch khám phá thế giới của Ba Lô &amp; Dép Lào"
15
  },
16
  {
17
    "slug": "gia-dinh",
18
    "name": "Gia Đình"
19
  },
20
  {
21
    "slug": "kham-pha-cuoi-tuan",
22
    "name": "Khám Phá Cuối Tuần"
23
  },
24
  {
25
    "slug": "khuyen-mai",
26
    "name": "Khuyến Mãi",
27
    "description": "Tổng hợp các thông tin khuyến mãi khách sạn, vé máy bay, ăn uống,..."
28
  },
29
  {
30
    "slug": "lam-dep",
31
    "name": "Làm Đẹp",
32
    "description": "Chia sẻ kinh nghiệm làm đẹp từ các nguyên liệu tự nhiên :)"
33
  },
34
  {
35
    "slug": "me-con",
36
    "name": "Mẹ và Con",
37
    "description": "Các bài viết chia sẻ kinh nghiệm làm mẹ và nuôi con"
38
  },
39
  {
40
    "slug": "meo-hay",
41
    "name": "Mẹo Hay"
42
  },
43
  {
44
    "slug": "qua-tang",
45
    "name": "Quà Tặng"
46
  },
47
  {
48
    "slug": "tam-su",
49
    "name": "Tâm Sự"
50
  },
51
  {
52
    "slug": "thu-cung",
53
    "name": "Thú Cưng",
54
    "description": "Các bài viết về cách huấn luyện, nuôi dưỡng và vui chơi cùng thú cưng"
55
  },
56
  {
57
    "slug": "tin-tuc",
58
    "name": "Tin Tức"
59
  },
60
  {
61
    "slug": "yoga",
62
    "name": "Yoga",
63
    "description": "Chia sẻ kinh nghiệm tập Yoga."
64
  }
65
]

Mình sẽ xóa các file không cần thiết, chỉ giữ lại category, post_tag và destination là những custom taxonomy sử dụng trong bài viết. Các file này sẽ là nguồn dữ liệu cho taxonomy trên Astro blog — từ tên hiển thị, mô tả, đến cấu trúc phân cấp.

III. Tích hợp vào Astro

Việc cần làm tiếp theo là tích hợp các thông tin mới vào Astro

Tạo util taxonomy.ts để xử lý thông tin metadata cho taxonomy, lấy từ các file json.
Cập nhật component Category.astro, Tag.astro để hiển thị tên đầy đủ cho taxonomy thay vì slug
Tạo component Destination.astro cho custom taxonomy `destination, chèn vào [...slug].astro và PostItem.astro
Cập nhật lại URL cho category / destination hỗ trợ phân cấp, ví dụ: /destination/nhat-ban/tokyo

1. Copy các file json vào Astro

Copy các thư mục taxonomies vào thư mục src/content/ trong project Astro. Cấu trúc thư mục content giờ sẽ như sau

1
content
2
├── blog
3
└── taxonomies

2. Khai báo custom taxonomy

Cập nhật file content.config.ts, bổ sung khai báo cho custom taxonomy mới: destination

1
import { defineCollection, z } from "astro:content";
2
import { glob } from "astro/loaders";
3

4
const blog = defineCollection({
5
  loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/content/blog" }),
6
  schema: z.object({
7
    title: z.string(),
8
    description: z.string().optional(),
9
    pubDatetime: z.coerce.date(),
10
    author: z.string(),
11
    image: z.string().optional(),
12
    tags: z.array(z.string()).optional(),
13
    categories: z.array(z.string()).optional(),
14
    destination: z.array(z.string()).optional(),
15
  }),
16
});
17

18
export const collections = { blog };

3. Tạo util xử lý taxonomy

Tạo file src/util/taxonomy.ts:

1
import categoryData from "@/content/taxonomies/category.json";
2
import destinationData from "@/content/taxonomies/destination.json";
3
import tagData from "@/content/taxonomies/tag.json";
4

5
export type TaxonomyItem = {
6
  slug: string;
7
  name: string;
8
  parent?: string;
9
  description?: string;
10
};
11

12
export type TaxonomyMap = Map<string, TaxonomyItem>;
13

14
export type TaxonomyType = "category" | "destination" | "tag";
15

16
function isTaxonomyItem(value: unknown): value is TaxonomyItem {
17
  if (typeof value !== "object" || value === null) return false;
18
  const v = value as Record<string, unknown>;
19
  return (
20
    typeof v.slug === "string" &&
21
    typeof v.name === "string" &&
22
    (v.parent === undefined || typeof v.parent === "string") &&
23
    (v.description === undefined || typeof v.description === "string")
24
  );
25
}
26

27
function buildMap(data: TaxonomyItem[]): TaxonomyMap {
28
  if (!Array.isArray(data)) {
29
    throw new Error(`[taxonomy] expected an array but received ${typeof data}`);
30
  }
31
  return new Map(
32
    data.map((item, i) => {
33
      if (!isTaxonomyItem(item)) {
34
        throw new Error(
35
          `[taxonomy] invalid item at index ${i}: ${JSON.stringify(item)}`
36
        );
37
      }
38
      return [item.slug, item];
39
    })
40
  );
41
}
42

43
const taxonomies: Record<TaxonomyType, TaxonomyMap> = {
44
  category: buildMap(categoryData as TaxonomyItem[]),
45
  destination: buildMap(destinationData as TaxonomyItem[]),
46
  tag: buildMap(tagData as TaxonomyItem[]),
47
};
48

49
export function getTaxonomyMap(type: TaxonomyType): TaxonomyMap {
50
  if (!(type in taxonomies)) {
51
    throw new Error(
52
      `[taxonomy] unknown taxonomy type "${type}". Expected one of: ${Object.keys(taxonomies).join(", ")}`
53
    );
54
  }
55
  return taxonomies[type];
56
}
57

58
function buildHierarchicalPath(
59
  slug: string,
60
  map: TaxonomyMap,
61
  visited = new Set<string>()
62
): string {
63
  if (visited.has(slug)) return slug; // cycle protection
64
  visited.add(slug);
65
  const item = map.get(slug);
66
  if (!item?.parent) return slug;
67
  return `${buildHierarchicalPath(item.parent, map, visited)}/${slug}`;
68
}
69

70
export function getTaxonomyPath(type: TaxonomyType, slug: string): string {
71
  return buildHierarchicalPath(slug, getTaxonomyMap(type));
72
}
73

74
export function getTaxonomyItem(
75
  type: TaxonomyType,
76
  slug: string
77
): TaxonomyItem | undefined {
78
  return getTaxonomyMap(type).get(slug);
79
}
80

81
export function getDescendantSlugs(
82
  taxonomyType: string,
83
  slug: string
84
): string[] {
85
  const map = getTaxonomyMap(taxonomyType);
86
  const result: string[] = [];
87

88
  for (const [key, item] of map.entries()) {
89
    if (key === slug) continue;
90
    // Đi ngược từ node này lên root, kiểm tra xem có qua slug không
91
    let current: TaxonomyItem | undefined = item;
92
    while (current?.parent) {
93
      if (current.parent === slug) {
94
        result.push(key);
95
        break;
96
      }
97
      current = map.get(current.parent);
98
    }
99
  }
100

101
  return result;
102
}

3. Cập nhật Component để hiển thị tên đầy đủ

Mình cần cập nhật các file s`rc/components/ui/`Categories.astro và src/components/ui/Tags.astro để cập nhật đường dẫn URL (sử dụng hàm getTaxonomyPath) và tên hiển thị (sử dụng hàm getTaxonomyMap)

1
---
2
import { getTaxonomyMap, getTaxonomyPath } from "@/utils/taxonomy";
3

4
export interface Props {
5
  categories: string[];
6
  class?: string;
7
}
8

9
const { categories, class: className = "text-sm" } = Astro.props;
10
const categoryMap = getTaxonomyMap("category");
11
---
12

13
{
14
  categories && Array.isArray(categories) && (
15
    <ul class:list={["flex flex-wrap gap-2", className]}>
16
      {categories.map(category => (
17
        <li class="relative inline-block">
18
          <a
19
            href={`/category/${getTaxonomyPath("category", category)}`}
20
            class="bg-primary/10 hover:bg-primary/20 text-primary hover:text-primary border-primary/20 inline-block rounded-full border px-3 py-1 transition-colors duration-200"
21
          >
22
            {categoryMap.get(category)?.name ?? category}
23
          </a>
24
        </li>
25
      ))}
26
    </ul>
27
  )
28
}

Kết quả: phần tên của Category, thay vì hiện du-lich, sẽ hiện ra tên đầy đủ “Du Lịch” và trỏ đúng đến /category/du-lich.

4. Tạo component Destination.astro

Tạo file src/components/uiDestinations.astro — về cơ bản giống hệt file Categories.astro, chỉ thay taxonomy type từ "category" sang "destination" và prefix URL thành /destination/:

1
---
2
import { getTaxonomyMap, getTaxonomyPath } from "@/utils/taxonomy";
3

4
export interface Props {
5
  destinations: string[];
6
  class?: string;
7
}
8

9
const { destinations, class: className = "text-sm" } = Astro.props;
10
const destinationMap = getTaxonomyMap("destination");
11
---
12

13
{
14
  destinations && Array.isArray(destinations) && (
15
    <ul class:list={["flex flex-wrap gap-2", className]}>
16
      {destinations.map(destination => (
17
        <li class="relative inline-block">
18
          <a
19
            href={`/destination/${getTaxonomyPath("destination", destination)}`}
20
            class="inline-flex items-center gap-1 rounded-full border border-emerald-500/20 bg-emerald-500/10 px-3 py-1 text-emerald-700 transition-colors duration-200 hover:bg-emerald-500/20 hover:text-emerald-800 dark:text-emerald-400 dark:hover:text-emerald-300"
21
          >
22
            <svg
23
              xmlns="http://www.w3.org/2000/svg"
24
              class="h-3 w-3"
25
              viewBox="0 0 24 24"
26
              fill="none"
27
              stroke="currentColor"
28
              stroke-width="2"
29
              stroke-linecap="round"
30
              stroke-linejoin="round"
31
              aria-hidden="true"
32
            >
33
              <path d="M20 10c0 6-8 12-8 12s-8-6-8-12a8 8 0 0 1 16 0Z" />
34
              <circle cx="12" cy="10" r="3" />
35
            </svg>
36
            {destinationMap.get(destination)?.name ?? destination}
37
          </a>
38
        </li>
39
      ))}
40
    </ul>
41
  )
42
}

Sau đó chèn component này vào hai nơi:

Trong [...slug].astro (trang bài viết đầy đủ):

1
---
2
import Destinations from "@/components/ui/Destinations.astro";
3

4
// ...
5
const {
6
  title,
7
  description,
8
  pubDatetime,
9
  author,
10
  image,
11
  categories,
12
  tags,
13
  destination, // thêm destination vào danh sách
14
} = post.data;
15
---
16

17
<BaseLayout metadata={metadata}>
18
  // ...
19
  <h1
20
    class="font-heading mt-2 text-3xl leading-tight font-bold tracking-tighter text-foreground sm:text-4xl md:text-5xl"
21
  >
22
    {title}
23
  </h1>
24
  // Hiển thị dưới tên bài viết
25
  {
26
    destination && destination.length > 0 && (
27
      <div class="mt-4 flex flex-wrap justify-center gap-2">
28
        <Destinations destinations={destination} />
29
      </div>
30
    )
31
  }
32
  // ...
33
</BaseLayout>

Trong PostItem.astro (card bài viết trong listing)

1
---
2
import Destinations from "@/components/ui/Destinations.astro";
3
// ...
4
---
5

6
{/* Trong phần meta của card */}
7
{
8
  post.data.destination && post.data.destination.length > 0 && (
9
    <div class="relative z-20 mt-4">
10
      <Destinations destinations={post.data.destination} />
11
    </div>
12
  )
13
}

5. Trang category với URL phân cấp

Đây là phần rắc rối nhất, vì mình vừa muốn URL hỗ trợ phân cấp (/desitnation/nhat-ban/tokyo), vừa muốn sử dụng pagination chia bài viết theo trang (`/desitnation/nhat-ban/tokyo`/page/2).

Nếu dùng route [...slug].astro thông thường sẽ không xử lý được pagination.. Nếu dùng [page].astro thì không tùy chỉnh được cấu trúc URL.

Giải pháp là dùng [...rest].astro giữ toàn bộ phần URL sau taxonomy prefix (/destination hoặc /category/) - bao gồm cả path phân cấp lẫn số trang, rồi tự build danh sách path trong getStaticPaths thông qua hàm buildPaginatedPaths có sẵn.

Tạo file src/pages/category/[...rest].astro với nội dung sau

1
---
2
import BaseLayout from "@/layouts/BaseLayout.astro";
3
import { getCollection } from "astro:content";
4
import type { CollectionEntry } from "astro:content";
5
import Headline from "@/components/ui/Headline.astro";
6
import PostItem from "@/components/blog/PostItem.astro";
7
import Pagination from "@/components/ui/Pagination.astro";
8
import {
9
  getTaxonomyMap,
10
  getTaxonomyPath,
11
  getDescendantSlugs,
12
  type TaxonomyItem,
13
} from "@/utils/taxonomy";
14
import { buildPaginatedPaths } from "@/utils/paginate";
15

16
interface Props {
17
  cat: TaxonomyItem;
18
  posts: CollectionEntry<"blog">[];
19
  currentPage: number;
20
  lastPage: number;
21
  total: number;
22
  prevUrl?: string;
23
  nextUrl?: string;
24
}
25

26
export async function getStaticPaths() {
27
  const allPosts = await getCollection("blog");
28
  const posts = allPosts.filter(post => post.data && post.data.pubDatetime);
29

30
  const catSlugs = new Set<string>();
31
  posts.forEach(post => post.data.categories?.forEach(c => catSlugs.add(c)));
32

33
  return Array.from(catSlugs).flatMap(slug => {
34
    const descendants = getDescendantSlugs("category", slug);
35
    const allSlugs = [slug, ...descendants];
36

37
    const catPosts = posts
38
      .filter(post => post.data.categories?.some(d => allSlugs.includes(d)))
39
      .sort(
40
        (a, b) => b.data.pubDatetime.valueOf() - a.data.pubDatetime.valueOf()
41
      );
42

43
    const fullPath = getTaxonomyPath("category", slug);
44
    const cat =
45
      getTaxonomyMap("category").get(slug) ??
46
      ({ slug, name: slug } as TaxonomyItem);
47

48
    return buildPaginatedPaths(catPosts, `/category/${fullPath}`).map(
49
      ({ pageParam, page }) => ({
50
        params: { rest: pageParam ? `${fullPath}/${pageParam}` : fullPath },
51
        props: {
52
          cat,
53
          posts: page.data,
54
          currentPage: page.currentPage,
55
          lastPage: page.lastPage,
56
          total: page.total,
57
          prevUrl: page.url.prev,
58
          nextUrl: page.url.next,
59
        },
60
      })
61
    );
62
  });
63
}
64

65
const { cat, posts, currentPage, lastPage, total, prevUrl, nextUrl } =
66
  Astro.props as Props;
67

68
const page = {
69
  currentPage,
70
  lastPage,
71
  url: { prev: prevUrl, next: nextUrl },
72
};
73

74
const metadata = {
75
  title: cat.name,
76
  description: cat.description ?? `Các bài viết trong danh mục ${cat.name}.`,
77
};
78
---
79

80
<BaseLayout metadata={metadata}>
81
  <section class="relative px-4 py-8 sm:px-6 md:py-12 lg:px-8">
82
    <div class="relative mx-auto max-w-5xl">
83
      <Headline
84
        tagline="Category"
85
        title={cat.name}
86
        subtitle={cat.description ?? `Hiển thị ${total} bài viết.`}
87
        classes={{
88
          container: "mb-12 text-center",
89
          title:
90
            "font-heading mb-4 text-4xl font-bold tracking-tight text-foreground md:text-6xl capitalized",
91
          subtitle: "mx-auto max-w-3xl text-xl text-muted-foreground",
92
        }}
93
      />
94

95
      <div class="mb-8 text-center">
96
        <a href="/blog" class="text-primary hover:underline">← Quay lại blog</a>
97
      </div>
98

99
      <div class="grid gap-8 md:grid-cols-2 lg:grid-cols-3">
100
        {posts.map(post => <PostItem post={post} />)}
101
      </div>
102
      <Pagination page={page} />
103
    </div>
104
  </section>
105
</BaseLayout>

Với cách này, Astro sẽ tự sinh ra đầy đủ các URL tại build time:

/category/du-lich
/category/du-lich/page/2, /category/du-lich//page/3…
/category/du-lich/chau-a
/category/du-lich/chau-a/nhat-ban/page/2

Áp dụng tương tự cho destination, đổi taxonomy type từ category sang destination

Tổng kết

Đến đây, toàn bộ những việc cần làm mình đã liệt kê ở [Phần 4] đã được giải quyết xong - custom taxonomy đã có trong frontmatter, tên taxonomy hiển thị đầy đủ, URL phân cấp hoạt động đúng, pagination chạy ngon.

Blog balodeplao.com đã được chính thức được chuyển qua sử dụng Astro. Bye bye WordPress!

Ngay sau đó, mình cũng đã chuyển blog supersilk.vn qua Astro dựa theo kinh nghiệm đúc kết từ lần đầu tiên. Lần này chỉ mất khoảng 30’ là xong việc dọn nhà so với lần đầu tiên tốn gần cả tuần mày mò.

Series hướng dẫn WordPress to Astro Migration đến đây xin hết. Các bạn có thể tham khảo toàn bộ mã nguồn mình đã chia sẻ trong 6 phần vừa qua ở đây: https://github.com/10h30/blog-balodeplao

Nhìn lại cả quá trình, mình cực kỳ hài lòng với kết quả đạt được: blog tải siêu nhanh, dễ dàng tùy biến tính năng qua VS Code, không phải bận tâm quản lý server hay database, toàn bộ nội dung và hình ảnh được lưu trữ trên Cloudflare miễn phí.

Quan trọng hơn, mình học được rất nhiều kiến thức mới trong quá trình này: Jamstack, CI/CD, Cloudflare Workers, Cloudflare Image Transformation, Astro framework - những công nghệ web hiện đại mà trước giờ chưa có dịp đụng tới. Các kiến thức này chắc chắn không chỉ hữu ích cho việc xây dựng, mà còn mở ra khá nhiều hướng để áp dụng vào công việc về sau.

Nếu bạn đang cân nhắc chuyển blog từ WordPress sang Astro, hy vọng series này giúp ích được phần nào.

Hẹn gặp lại ở các bài viết tiếp theo!