@astro-minimax/core 0.1.0

package/src/utils/getPath.ts

@@ -0,0 +1,52 @@
+import { BLOG_PATH } from "@/content.config";
+import { slugifyStr } from "./slugify";
+
+/**
+ * Get full path of a blog post
+ * @param id - id of the blog post (aka slug)
+ * @param filePath - the blog post full file location
+ * @param includeBase - whether to include `/posts` in return value
+ * @returns blog post path
+ */
+export function getPath(
+  id: string,
+  filePath: string | undefined,
+  includeBase = true
+) {
+  const pathSegments = filePath
+    ?.replace(BLOG_PATH, "")
+    .split("/")
+    .filter(path => path !== "") // remove empty string in the segments ["", "other-path"] <- empty string will be removed
+    .filter(path => !path.startsWith("_")) // exclude directories start with underscore "_"
+    .slice(0, -1) // remove the last segment_ file name_ since it's unnecessary
+    .map(segment => slugifyStr(segment)); // slugify each segment path
+
+  const basePath = includeBase ? "/posts" : "";
+
+  // Making sure `id` does not contain the directory
+  const blogId = id.split("/");
+  const slug = blogId.length > 0 ? blogId.slice(-1) : blogId;
+
+  // If not inside the sub-dir, simply return the file path
+  if (!pathSegments || pathSegments.length < 1) {
+    return [basePath, slug].join("/");
+  }
+
+  return [basePath, ...pathSegments, slug].join("/");
+}
+
+/** Slug for URL (filename without path, for use with [lang] routing) */
+export function getPostSlug(id: string): string {
+  const parts = id.split("/");
+  return parts.length > 0 ? parts[parts.length - 1] : id;
+}
+
+/** Localized post path: /{lang}/posts/{slug} */
+export function getLocalizedPostPath(
+  lang: string,
+  id: string,
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  _filePath?: string
+): string {
+  return `/${lang}/posts/${getPostSlug(id)}`;
+}

package/src/utils/getPostsByCategory.ts

@@ -0,0 +1,17 @@
+import type { CollectionEntry } from "astro:content";
+import getSortedPosts from "./getSortedPosts";
+
+const getPostsByCategory = (
+  posts: CollectionEntry<"blog">[],
+  category: string
+) =>
+  getSortedPosts(
+    posts.filter(
+      post =>
+        post.data.category &&
+        (post.data.category === category ||
+          post.data.category.startsWith(category + "/"))
+    )
+  );
+
+export default getPostsByCategory;

package/src/utils/getPostsByGroupCondition.ts

@@ -0,0 +1,25 @@
+import type { CollectionEntry } from "astro:content";
+
+type GroupKey = string | number | symbol;
+
+interface GroupFunction<T> {
+  (item: T, index?: number): GroupKey;
+}
+
+const getPostsByGroupCondition = (
+  posts: CollectionEntry<"blog">[],
+  groupFunction: GroupFunction<CollectionEntry<"blog">>
+) => {
+  const result: Record<GroupKey, CollectionEntry<"blog">[]> = {};
+  for (let i = 0; i < posts.length; i++) {
+    const item = posts[i];
+    const groupKey = groupFunction(item, i);
+    if (!result[groupKey]) {
+      result[groupKey] = [];
+    }
+    result[groupKey].push(item);
+  }
+  return result;
+};
+
+export default getPostsByGroupCondition;

package/src/utils/getPostsByLang.ts

@@ -0,0 +1,27 @@
+import type { CollectionEntry } from "astro:content";
+
+/**
+ * Detect language from post filePath (directory-based).
+ * Posts under .../zh/ → "zh", posts under .../en/ → "en".
+ * Fallback: check id for "zh/" or "en/" prefix. Default "zh".
+ */
+export function getPostLang(post: CollectionEntry<"blog">): "zh" | "en" {
+  const path = post.filePath ?? post.id;
+  if (path.includes("/zh/")) return "zh";
+  if (path.includes("/en/")) return "en";
+  if (post.id.startsWith("zh/")) return "zh";
+  if (post.id.startsWith("en/")) return "en";
+  return "zh";
+}
+
+/**
+ * Filter blog posts by language (directory-based).
+ */
+export function getPostsByLang(
+  posts: CollectionEntry<"blog">[],
+  lang: "zh" | "en" | string
+): CollectionEntry<"blog">[] {
+  return posts.filter(post => getPostLang(post) === lang);
+}
+
+export default getPostsByLang;

package/src/utils/getPostsByTag.ts

@@ -0,0 +1,10 @@
+import type { CollectionEntry } from "astro:content";
+import getSortedPosts from "./getSortedPosts";
+import { slugifyAll } from "./slugify";
+
+const getPostsByTag = (posts: CollectionEntry<"blog">[], tag: string) =>
+  getSortedPosts(
+    posts.filter(post => slugifyAll(post.data.tags).includes(tag))
+  );
+
+export default getPostsByTag;

package/src/utils/getReadingTime.ts

@@ -0,0 +1,33 @@
+const CJK_REGEX = /[\u4e00-\u9fff\u3400-\u4dbf\uf900-\ufaff]/g;
+const WORD_REGEX = /\b[a-zA-Z0-9]+(?:[-'][a-zA-Z0-9]+)*\b/g;
+
+const CJK_WPM = 350;
+const EN_WPM = 230;
+
+export function getReadingTime(content: string): {
+  minutes: number;
+  words: number;
+} {
+  const text = content
+    .replace(/```[\s\S]*?```/g, "")
+    .replace(/`[^`]*`/g, "")
+    .replace(/!\[.*?\]\(.*?\)/g, "")
+    .replace(/\[([^\]]*)\]\(.*?\)/g, "$1")
+    .replace(/<[^>]*>/g, "")
+    .replace(/^---[\s\S]*?---/m, "")
+    .replace(/#+\s/g, "")
+    .replace(/[*_~]/g, "");
+
+  const cjkChars = text.match(CJK_REGEX) || [];
+  const enWords = text.match(WORD_REGEX) || [];
+
+  const cjkCount = cjkChars.length;
+  const enCount = enWords.filter(
+    w => !CJK_REGEX.test(w) && w.length > 0
+  ).length;
+
+  const totalWords = cjkCount + enCount;
+  const minutes = Math.max(1, Math.ceil(cjkCount / CJK_WPM + enCount / EN_WPM));
+
+  return { minutes, words: totalWords };
+}

package/src/utils/getRelatedPosts.ts

@@ -0,0 +1,59 @@
+import type { CollectionEntry } from "astro:content";
+import { slugifyStr } from "./slugify";
+
+/**
+ * Calculate content similarity score between two posts
+ * based on shared tags and category overlap.
+ */
+function getSimilarityScore(
+  a: CollectionEntry<"blog">,
+  b: CollectionEntry<"blog">
+): number {
+  if (a.id === b.id) return -1;
+
+  let score = 0;
+
+  const aTags = new Set(a.data.tags.map(t => slugifyStr(t)));
+  const bTags = new Set(b.data.tags.map(t => slugifyStr(t)));
+  for (const tag of aTags) {
+    if (bTags.has(tag)) score += 3;
+  }
+
+  if (a.data.category && b.data.category) {
+    if (a.data.category === b.data.category) {
+      score += 5;
+    } else {
+      const aParts = a.data.category.split("/");
+      const bParts = b.data.category.split("/");
+      if (aParts[0] === bParts[0]) score += 2;
+    }
+  }
+
+  if (
+    a.data.series &&
+    b.data.series &&
+    a.data.series.name === b.data.series.name
+  ) {
+    score += 4;
+  }
+
+  return score;
+}
+
+/**
+ * Get related posts sorted by similarity score.
+ */
+export function getRelatedPosts(
+  currentPost: CollectionEntry<"blog">,
+  allPosts: CollectionEntry<"blog">[],
+  count = 3
+): CollectionEntry<"blog">[] {
+  return allPosts
+    .map(post => ({ post, score: getSimilarityScore(currentPost, post) }))
+    .filter(({ score }) => score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, count)
+    .map(({ post }) => post);
+}
+
+export default getRelatedPosts;

package/src/utils/getSeriesData.ts

@@ -0,0 +1,57 @@
+import type { CollectionEntry } from "astro:content";
+import postFilter from "./postFilter";
+import { slugifyStr } from "./slugify";
+
+export interface SeriesInfo {
+  name: string;
+  slug: string;
+  posts: CollectionEntry<"blog">[];
+  description?: string;
+  totalPosts: number;
+  latestDate: Date;
+}
+
+function slugifySeries(name: string): string {
+  return slugifyStr(name);
+}
+
+export function getSeriesFromPosts(
+  posts: CollectionEntry<"blog">[]
+): SeriesInfo[] {
+  const seriesMap = new Map<string, CollectionEntry<"blog">[]>();
+
+  posts.filter(postFilter).forEach(post => {
+    const series = post.data.series;
+    if (!series) return;
+    const existing = seriesMap.get(series.name) ?? [];
+    existing.push(post);
+    seriesMap.set(series.name, existing);
+  });
+
+  return Array.from(seriesMap.entries())
+    .map(([name, seriesPosts]) => {
+      const sorted = seriesPosts.sort(
+        (a, b) => (a.data.series?.order ?? 0) - (b.data.series?.order ?? 0)
+      );
+      const latestDate = sorted.reduce((latest, p) => {
+        const d = new Date(p.data.modDatetime ?? p.data.pubDatetime);
+        return d > latest ? d : latest;
+      }, new Date(0));
+
+      return {
+        name,
+        slug: slugifySeries(name),
+        posts: sorted,
+        totalPosts: sorted.length,
+        latestDate,
+      };
+    })
+    .sort((a, b) => b.latestDate.getTime() - a.latestDate.getTime());
+}
+
+export function getSeriesByName(
+  posts: CollectionEntry<"blog">[],
+  name: string
+): SeriesInfo | undefined {
+  return getSeriesFromPosts(posts).find(s => s.name === name);
+}

package/src/utils/getSortedPosts.ts

@@ -0,0 +1,18 @@
+import type { CollectionEntry } from "astro:content";
+import postFilter from "./postFilter";
+
+const getSortedPosts = (posts: CollectionEntry<"blog">[]) => {
+  return posts
+    .filter(postFilter)
+    .sort(
+      (a, b) =>
+        Math.floor(
+          new Date(b.data.modDatetime ?? b.data.pubDatetime).getTime() / 1000
+        ) -
+        Math.floor(
+          new Date(a.data.modDatetime ?? a.data.pubDatetime).getTime() / 1000
+        )
+    );
+};
+
+export default getSortedPosts;

package/src/utils/getTagsWithCount.ts

@@ -0,0 +1,38 @@
+import type { CollectionEntry } from "astro:content";
+import { slugifyStr } from "./slugify";
+import postFilter from "./postFilter";
+
+interface TagWithCount {
+  tag: string;
+  tagName: string;
+  count: number;
+}
+
+const getTagsWithCount = (posts: CollectionEntry<"blog">[]) => {
+  const tagMap = new Map<string, { tagName: string; count: number }>();
+
+  posts
+    .filter(postFilter)
+    .flatMap(post => post.data.tags)
+    .forEach(tag => {
+      const slug = slugifyStr(tag);
+      const existing = tagMap.get(slug);
+      if (existing) {
+        existing.count++;
+      } else {
+        tagMap.set(slug, { tagName: tag, count: 1 });
+      }
+    });
+
+  const tags: TagWithCount[] = Array.from(tagMap.entries())
+    .map(([tag, data]) => ({
+      tag,
+      tagName: data.tagName,
+      count: data.count,
+    }))
+    .sort((a, b) => b.count - a.count);
+
+  return tags;
+};
+
+export default getTagsWithCount;

package/src/utils/getUniqueCategories.ts

@@ -0,0 +1,81 @@
+import type { CollectionEntry } from "astro:content";
+
+export type CategoryEntry = { category: string; count: number };
+
+export type CategoryTreeNode = {
+  name: string;
+  fullPath: string;
+  count: number;
+  children: CategoryTreeNode[];
+};
+
+const getUniqueCategories = (
+  posts: CollectionEntry<"blog">[]
+): CategoryEntry[] => {
+  const countMap = new Map<string, number>();
+
+  posts.forEach(post => {
+    if (post.data.category) {
+      countMap.set(
+        post.data.category,
+        (countMap.get(post.data.category) ?? 0) + 1
+      );
+    }
+  });
+
+  return Array.from(countMap.entries())
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([category, count]) => ({ category, count }));
+};
+
+export function getCategoryTree(
+  posts: CollectionEntry<"blog">[]
+): CategoryTreeNode[] {
+  const flat = getUniqueCategories(posts);
+  const root: CategoryTreeNode[] = [];
+
+  for (const { category, count } of flat) {
+    const parts = category.split("/");
+    let current = root;
+
+    for (let i = 0; i < parts.length; i++) {
+      const fullPath = parts.slice(0, i + 1).join("/");
+      let node = current.find(n => n.fullPath === fullPath);
+
+      if (!node) {
+        node = { name: parts[i], fullPath, count: 0, children: [] };
+        current.push(node);
+      }
+
+      if (i === parts.length - 1) {
+        node.count = count;
+      }
+
+      current = node.children;
+    }
+  }
+
+  return root;
+}
+
+/**
+ * Get all category paths including parent categories (for generating category pages).
+ * This extracts all possible category paths from the category tree.
+ */
+export function getAllCategoryPaths(tree: CategoryTreeNode[]): string[] {
+  const paths: string[] = [];
+
+  function traverse(nodes: CategoryTreeNode[]) {
+    for (const node of nodes) {
+      paths.push(node.fullPath);
+      if (node.children.length > 0) {
+        traverse(node.children);
+      }
+    }
+  }
+
+  traverse(tree);
+  return paths;
+}
+
+export default getUniqueCategories;

package/src/utils/getUniqueTags.ts

@@ -0,0 +1,23 @@
+import type { CollectionEntry } from "astro:content";
+import { slugifyStr } from "./slugify";
+import postFilter from "./postFilter";
+
+interface Tag {
+  tag: string;
+  tagName: string;
+}
+
+const getUniqueTags = (posts: CollectionEntry<"blog">[]) => {
+  const tags: Tag[] = posts
+    .filter(postFilter)
+    .flatMap(post => post.data.tags)
+    .map(tag => ({ tag: slugifyStr(tag), tagName: tag }))
+    .filter(
+      (value, index, self) =>
+        self.findIndex(tag => tag.tag === value.tag) === index
+    )
+    .sort((tagA, tagB) => tagA.tag.localeCompare(tagB.tag));
+  return tags;
+};
+
+export default getUniqueTags;