feat: added a tag to allow for featured notes

src/_utils/sort-posts.js

@@ -0,0 +1,59 @@
+/**
+ * Safely extracts a numeric timestamp from an Eleventy item or its frontmatter data.
+ * @param {object} item Eleventy page / post object
+ * @returns {number} Unix timestamp in ms
+ */
+export function getPostTimestamp(item) {
+  if (!item || typeof item !== "object") return 0;
+  const rawDate = item.date ?? item.data?.date ?? item.data?.created;
+  if (rawDate instanceof Date) {
+    const t = rawDate.getTime();
+    return Number.isNaN(t) ? 0 : t;
+  }
+  if (typeof rawDate === "string" || typeof rawDate === "number") {
+    const t = new Date(rawDate).getTime();
+    return Number.isNaN(t) ? 0 : t;
+  }
+  return 0;
+}
+
+/**
+ * Determines whether a post is flagged as pinned or featured.
+ * Explicit boolean true or truthy values are supported;
+ * missing, null, or false values return false.
+ *
+ * @param {object} item Eleventy page / post object
+ * @returns {boolean}
+ */
+export function isPostPinned(item) {
+  if (!item || typeof item !== "object") return false;
+  const data = item.data;
+  if (!data || typeof data !== "object") return false;
+  return Boolean(data.pinned || data.featured);
+}
+
+/**
+ * Comparator for sorting blog posts:
+ * 1. Pinned or featured posts are prioritized at the top of the collection.
+ * 2. Within the same priority group (both pinned or both unpinned), posts
+ *    are sorted chronologically in descending order (newest first).
+ *
+ * @param {object} a First post
+ * @param {object} b Second post
+ * @returns {number} Negative if a comes before b, positive if b comes before a, 0 if equal
+ */
+export function postComparator(a, b) {
+  const aPinned = isPostPinned(a);
+  const bPinned = isPostPinned(b);
+
+  if (aPinned !== bPinned) {
+    return bPinned ? 1 : -1;
+  }
+
+  const timeA = getPostTimestamp(a);
+  const timeB = getPostTimestamp(b);
+
+  return timeB - timeA;
+}
+
+export default postComparator;