feat: load the sidebar data and titles/excerpts from the blog post markdown document and its frontmatter (#2981)

Author: pd93

website/.vitepress/blog.data.ts

@@ -0,0 +1,53 @@
+import { createContentLoader } from 'vitepress';
+
+export interface Post {
+  title: string;
+  url: string;
+  date: {
+    time: number;
+    string: string;
+  };
+  author: string;
+  tags: string[];
+  excerpt?: string;
+}
+
+declare const data: Post[];
+export { data };
+
+// extractExcerpt renders the whole document first so that links which have
+// `[ref]: url` style definitions outside of the excerpt still resolve. The
+// rendered HTML is then cut at the `<!-- more -->` marker leaving just the
+// excerpt text.
+function extractExcerpt(html: string): string | undefined {
+  const markerIndex = html.indexOf('<!-- more -->');
+  if (markerIndex === -1) return undefined;
+  return html
+    .slice(0, markerIndex)
+    .replace(/<h1[^>]*>[\s\S]*?<\/h1>/, '')
+    .replace(/<AuthorCard\b[^>]*\/?>/gi, '')
+    .trim();
+}
+
+export default createContentLoader('blog/*.md', {
+  render: true,
+  transform(raw) {
+    return raw
+      .filter(({ url }) => url !== '/blog/')
+      .map(({ frontmatter, html, url }) => {
+        const date = new Date(frontmatter.date);
+        return {
+          title: frontmatter.title,
+          url,
+          date: {
+            time: date.getTime(),
+            string: date.toISOString().slice(0, 10)
+          },
+          author: frontmatter.author,
+          tags: frontmatter.tags ?? [],
+          excerpt: html ? extractExcerpt(html) : undefined
+        };
+      })
+      .sort((a, b) => b.date.time - a.date.time);
+  }
+});

website/.vitepress/components/BlogPost.vue

@@ -20,7 +20,7 @@
       <div class="post-text">
         <AuthorCard :author="author" />
 
-        <p class="post-description">{{ description }}</p>
+        <div class="post-description" v-html="description"></div>
 
         <div class="post-footer">
           <div class="post-tags" v-if="tags?.length">

website/.vitepress/config.ts

@@ -1,7 +1,8 @@
 import { defineConfig, HeadConfig } from 'vitepress';
 import githubLinksPlugin from './plugins/github-links';
-import { readFileSync } from 'fs';
+import { readdirSync, readFileSync } from 'fs';
 import { resolve } from 'path';
+import matter from 'gray-matter';
 import { tabsMarkdownPlugin } from 'vitepress-plugin-tabs';
 import {
   groupIconMdPlugin,
@@ -19,6 +20,39 @@ const version = readFileSync(
   'utf8'
 ).trim();
 
+// Builds the "/blog/" sidebar from each blog post's frontmatter.
+function buildBlogSidebar() {
+  const blogDir = resolve(__dirname, '../src/blog');
+  const posts = readdirSync(blogDir)
+    .filter((file) => file.endsWith('.md') && file !== 'index.md')
+    .map((file) => {
+      const { data: frontmatter } = matter(
+        readFileSync(resolve(blogDir, file), 'utf8')
+      );
+      return {
+        slug: file.replace(/\.md$/, ''),
+        title: frontmatter.sidebarTitle ?? frontmatter.title,
+        date: new Date(frontmatter.date)
+      };
+    })
+    .sort((a, b) => b.date.getTime() - a.date.getTime());
+
+  const byYear = new Map<number, { text: string; link: string }[]>();
+  for (const post of posts) {
+    const year = post.date.getFullYear();
+    if (!byYear.has(year)) byYear.set(year, []);
+    byYear.get(year)!.push({ text: post.title, link: `/blog/${post.slug}` });
+  }
+
+  return [...byYear.entries()]
+    .sort((a, b) => b[0] - a[0])
+    .map(([year, items]) => ({
+      text: String(year),
+      collapsed: false,
+      items
+    }));
+}
+
 const urlVersion =
   process.env.NODE_ENV === 'development'
     ? {
@@ -311,56 +345,7 @@ export default defineConfig({
     ],
 
     sidebar: {
-      '/blog/': [
-        {
-          text: '2026',
-          collapsed: false,
-          items: [
-            {
-              text: 'GitHub SOSF',
-              link: '/blog/github-secure-open-source-program'
-            },
-            {
-              text: 'Using `go tool task`',
-              link: '/blog/go-tool-task'
-            },
-            {
-              text: 'Conditionals Statements',
-              link: '/blog/if-and-variable-prompt'
-            }
-          ]
-        },
-        {
-          text: '2025',
-          collapsed: false,
-          items: [
-            {
-              text: 'Built-in Core Utilities',
-              link: '/blog/windows-core-utils'
-            }
-          ]
-        },
-        {
-          text: '2024',
-          collapsed: false,
-          items: [
-            {
-              text: 'Any Variables',
-              link: '/blog/any-variables'
-            }
-          ]
-        },
-        {
-          text: '2023',
-          collapsed: false,
-          items: [
-            {
-              text: 'Introducing Experiments',
-              link: '/blog/task-in-2023'
-            }
-          ]
-        }
-      ],
+      '/blog/': buildBlogSidebar(),
       '/': [
         {
           text: 'Installation',

website/package.json

@@ -15,6 +15,7 @@
   "devDependencies": {
     "@types/markdown-it": "^14.1.2",
     "@types/node": "^24.1.0",
+    "gray-matter": "^4.0.3",
     "netlify-cli": "^27.0.0",
     "prettier": "^3.6.2",
     "vitepress": "^1.6.3",

website/pnpm-lock.yaml

@@ -1,7 +1,11 @@
 ---
 title: Any Variables
+description:
+  Task now supports most variable types, including booleans, integers, floats
+  and arrays!
 author: pd93
 date: 2024-05-09
+tags: ['experiments', 'variables']
 outline: deep
 editLink: false
 ---
@@ -17,6 +21,8 @@ simple problems. Starting from [v3.37.0][v3.37.0], this is no longer the case!
 Task now supports most variable types, including **booleans**, **integers**,
 **floats** and **arrays**!
 
+<!-- more -->
+
 ## What's the big deal?
 
 These changes allow you to use variables in a much more natural way and opens up