Refreshing my blog (is that still a thing?) for the first time in the last 5 years and I find that the tech I used to use, Gatsby, is no more. So it's time to start looking at a new tech and the easiest way to move everything over without rewriting it all. This is not a comparison of the best platform / framework etc. and I won't go into the reasons here but I landed on VitePress.
It's been pretty straightforward to get the basics in place but there are definitely a few quirks that may affect you if you stray from too far from the path. So far, they've all been fixable, but only time will tell...
The Situation
Having deployed the basics for a VitePress site I copied in my historical posts and wanted to display them in date descending order in the sidebar and be able to click through them using the next / prev buttons where next .
The posts all exist as markdown files named index.md in dated folders in the format yyyy-mm-dd--some-title. From a distant memory this was a condition that made transformation much easier in Gatsby.
All index files contain a yaml frontmatter section which includes the date that the post was written in ISO 8601 format, e.g.:
---
author: Russell Keane
date: 2025-01-01T08:14:33+00:00
excerpt: 'A January page'
layout: doc
slug: january-page
title: It's a January Page
---The sidebar data is populated in the themeConfig.sidebar attribute in the config.mts file and the posts landing page data is populated in the posts/index.data.ts file
Loading the data
The project is structured as follows (files omitted for brevity):
├── .vitepress/
│ └── config.mts
├── posts/
│ ├── 2025-01-01--january-page/
│ │ └── index.md
│ ├── 2025-02-15--february-page/
│ │ └── index.md
│ └── 2025-03-30--march-page/
│ │ └── index.md
│ ├── index.data.ts
│ ├── index.md
│ └── sidebar.tsFirst thing's first, let's load the posts to a posts landing page. This code is all available on at 1-start
In posts/index.data.ts file we add this:
import { createContentLoader } from 'vitepress';
export default createContentLoader('./posts/*/*.md', {
render: true,
includeSrc: true,
});And then within the posts/index.md we add this:
<script setup>
import { data as posts } from './index.data.ts';
</script>
<ul>
<li v-for="post of posts">
<a :href="post.url">{{ post.frontmatter.title }}</a>
<span> by {{ post.frontmatter.author }}</span>
</li>
</ul>
<style scoped>
ul {
list-style-type: none;
padding-left: 0;
font-size: 1.125rem;
line-height: 1.75;
}
li {
display: flex;
justify-content: space-between;
}
li span {
font-family: var(--vp-font-family-mono);
font-size: var(--vp-code-font-size);
}
</style>This renders the posts as a simple list and because we're loading the files from disk, they appear with the oldest post at the bottom. This is becasue they're ordered that way on disk, which is annoying...
Ok, so let's add them to the sidebar as well. In the posts/sidebar.ts file we add this:
import fm from 'front-matter';
import fs from 'fs';
import path from 'path';
type SidebarMeta = {
text: string;
link: string;
};
export const getPostMetaData = (): SidebarMeta[] => {
const files = readMarkdownFilesRecursively(path.resolve(__dirname, '.')).filter(
(file) => file !== path.resolve(__dirname, 'index.md'),
);
const meta = files.map((file) => {
const frontmatter = fm(fs.readFileSync(file, 'utf-8')).attributes as Record<string, any>;
return {
text: frontmatter.title || path.basename(file, '.md'),
link: `/${file.replace(/index\.md$/, '')}`,
} as SidebarMeta;
});
return meta;
};
const readMarkdownFilesRecursively = (dir: string): string[] => {
let mdFiles: string[] = [];
try {
const files = fs.readdirSync(dir, { withFileTypes: true });
for (const file of files) {
const fullPath = path.join(dir, file.name);
if (file.isDirectory()) {
// Recursively read from subdirectory
mdFiles = mdFiles.concat(readMarkdownFilesRecursively(fullPath));
} else if (file.isFile() && file.name.endsWith('.md')) {
mdFiles.push(fullPath);
}
}
} catch (error) {
console.error('Error reading directory:', error);
}
return mdFiles;
};This is probably more code than we need for demonstration but it's effectively just loading all index.md files from within the posts folder (excluding the posts/index.md file) and then loading information from the frontmatter section to get the posts' titles and so on.
And in the .vitepress/config.mts file we add this:
import { defineConfig } from 'vitepress';
import { getPostMetaData } from '../posts/sidebar';
const posts = getPostMetaData();
// https://vitepress.dev/reference/site-config
export default defineConfig({
title: 'My Awesome Project',
description: 'A VitePress Site',
themeConfig: {
// https://vitepress.dev/reference/default-theme-config
nav: [
{ text: 'Home', link: '/' },
{ text: 'Posts', link: '/posts/' },
],
sidebar: [
{
text: 'Examples',
items: posts,
},
],
socialLinks: [{ icon: 'github', link: 'https://github.com/vuejs/vitepress' }],
},
});This loads the posts' metadata from the sidebar.ts file and adds the info to the sidebar under the "Examples" heading.
We've now managed to load all the post data to the sidebar and to the posts landing page but it's back to front as you can see here:
The other issue is that the "Next page" button always points to the January post for some reason, but we'll come back to that later.
Ordering the data
Ok, so let's fix the ordering of the sidebar first. This update is available on github at 2-ordered
To update the landing page order, we change posts/index.data.ts to the following:
import { createContentLoader } from 'vitepress';
export default createContentLoader('./posts/*/*.md', {
render: true,
includeSrc: true,
transform(rawData) {
return rawData.sort((a, b) => {
return new Date(b.frontmatter.date).getTime() - new Date(a.frontmatter.date).getTime();
});
},
});This obviously assumes the created date appears in the frontmatter section, which it does in our case.
Then to update the sidebar order, within posts/sidebar.ts we simply add .reverse() to the loaded array of metadata:
export const getPostMetaData = (): SidebarMeta[] => {
const files = readMarkdownFilesRecursively(path.resolve(__dirname, '.')).filter(
(file) => file !== path.resolve(__dirname, 'index.md'),
);
const meta = files
.map((file) => {
const frontmatter = fm(fs.readFileSync(file, 'utf-8')).attributes as Record<string, any>;
return {
text: frontmatter.title || path.basename(file, '.md'),
link: `/${file.replace(/index\.md$/, '')}`,
} as SidebarMeta;
})
.reverse();
return meta;
};This is a very simplistic way of doing it (because we know the posts are loaded in an oldest first order) and we could equally use the date from the frontmatter section to maintain the same ordering algorythm as the posts landing page but I went for simple first. And so we've fixed the ordering:
We could use the same loader as the posts landing page but it's not quite that straight forward because createContentLoader within posts/index.data.ts returns a promise and defineConfig within .vitepress/config.mts is not able to directly use async functions. It can be done without too much difficulty but that's not the point of this post so I'll leave that refactoring as an exercise for the reader.
Fixing the next/prev buttons
Ok, so we now have the posts in the desired order but the next button still points at the wrong file and there's no prev button. All code for this section is available on github at 3-fixed
First we're going to update the metadata to include the next and prev link data. In posts/sidebar.ts:
import fm from 'front-matter';
import fs from 'fs';
import path from 'path';
type SidebarMeta = {
text: string;
link: string;
filePath: string;
prev?: { text: string; link: string };
next?: { text: string; link: string };
};
export const getPostMetaData = (): SidebarMeta[] => {
const files = readMarkdownFilesRecursively(path.resolve(__dirname, '.')).filter(
(file) => file !== path.resolve(__dirname, 'index.md'),
);
const meta = files
.map((file) => {
const frontmatter = fm(fs.readFileSync(file, 'utf-8')).attributes as Record<string, any>;
return {
text: frontmatter.title || path.basename(file, '.md'),
link: `/${file.replace(/index\.md$/, '')}`,
filePath: getFilePath(file),
} as SidebarMeta;
})
.reverse();
for (let i = 0; i < meta.length; i++) {
if (i !== 0) {
meta[i].next = { text: meta[i - 1].text, link: meta[i - 1].filePath };
} else {
meta[i].next = { text: 'Posts', link: '/posts' };
}
if (i !== meta.length - 1) {
meta[i].prev = { text: meta[i + 1].text, link: meta[i + 1].filePath };
}
}
return meta;
};
const getFilePath = (file: string) => {
return `posts${file.split('posts')[1].replace(/\\/g, '/')}`;
};What this is doing is iterating the ordered metadata list and adding the next / prev link data depending on what item is next to the one we're looking at.
We then need to update .vitepress/config.mts to the following:
import { defineConfig } from 'vitepress';
import { getPostMetaData } from '../posts/sidebar';
const posts = getPostMetaData();
// https://vitepress.dev/reference/site-config
export default defineConfig({
title: 'My Awesome Project',
description: 'A VitePress Site',
themeConfig: {
// https://vitepress.dev/reference/default-theme-config
nav: [
{ text: 'Home', link: '/' },
{ text: 'Posts', link: '/posts/' },
],
sidebar: [
{
text: 'Examples',
items: posts,
},
],
socialLinks: [{ icon: 'github', link: 'https://github.com/vuejs/vitepress' }],
},
async transformPageData(pageData, { siteConfig }) {
const post = posts.find((post) => post.filePath === pageData.filePath);
if (post) {
pageData.frontmatter.prev = post.prev;
pageData.frontmatter.next = post.next;
} else if (pageData.filePath === 'posts/index.md') {
pageData.frontmatter.next = { text: 'Home', link: '/' };
pageData.frontmatter.prev = {
text: posts[0]?.text,
link: posts[0]?.filePath,
};
}
},
});This tells vitepress to update the pageData frontmatter section to correctly set the prev and next links by looking up the current page's filePath in the post metadata list.
It also sets the prev and next links as appropriate for the posts landing page.
The reason we do this is because vitepress is loading the page frontmatter data directly from the individual pages. The problem is that they don't have that data in them. We could add that to the individual files by explicitly setting the prev/next data but I much prefer it to be dynamic as I might want to change the order or remove a post or something and it's painful having to update a load of links in hundreds (one day) of posts. However, if that's how you'd prefer to do it, I've created a copy of the ordered version and use static links here
So there we have it, ordered posts with fixed prev / next links.
I'm still not 100% happy with it as the next button on the posts page feel a little counter intuitive with the next button taking you back to home. Maybe I'd be better off swapping the prev and next links for all pages so they're the other way round. That works but then previous goes to newer posts and next goes to older posts and that makes my spidey senses tingle... 🤔
Either way, it's much easier to change the links now we're doing it dynamically. 👍