How to execute a script on docs/markdown.md update

[Karlstens]

Hello,

I created a script that I'm looking to further integrate into my vitePress dev process "statusCheck.mjs".

Initially, I added the script into my package.json file, so that it executes upon calling docs:dev.

package.json

"scripts": {
		"docs:dev": "node statusCheck.mjs && vitepress dev docs",

But then I realised how it would be nice to have it execute when saving my config.js file, so I updated my config.js file like this;

config.js

import "../../statusCheck.mjs";
import { defineConfig } from "vitepress";

export default defineConfig({
	title: "My VitePress Project",
	...
	})

This seems to trigger my script as desired.

But then it had me thinking how I'd really prefer my script to execute when any of my markdown files are updated. How can I integrate my script into my vitepress project so that it triggers upon any of my docs being saved whilst in dev?

The output of this script simply scans all frontmatter from each docs\markdown.md file, and is creating a summary markdown page.

[brc-dd]

You can simply write data loader files instead - https://vitepress.dev/guide/data-loading#createcontentloader You don't need to write a separate script to generate a summary page. However, if you want to write a separate script, you'll need to use something like @parcel/watcher or chokidar.

[Karlstens]

Thanks for this. I've attempted the following.

docs\status\posts.data.js

import { createContentLoader } from "vitepress";

export default createContentLoader("sizes/*.md" /* { options } */);

docs\status\posts.md

Testing Posts

<script setup>
import { data as posts } from './posts.data.js'
</script>

<template>
  <h1>All Blog Posts</h1>
  <ul>
    <li v-for="post of posts">
      <a :href="post.url">{{ post.frontmatter.title }}</a>
    </li>
  </ul>
</template>

And I have markdown files with JSON frontmatter here;

docs\sizes\large.md
docs\sizes\medium.md
docs\sizes\small.md

---
{
    "title": "Large",
    "category": "Large category details",
    "description": "A very large description",
    "status": "Published",
    "head":
        [
            ["meta", { "name": "myPropA", "content": "AAA" }],
            ["meta", { "name": "myPropB", "content": "BBB" }],
            ["meta", { "name": "myPropC", "content": "CCC" }],
        ],
}
---

Large is a size descriptor indicating that something is bigger than average or usual. In user interfaces, large elements are often used for important interactive components or to attract the user's attention.

When I run docs:dev, the post.md page only renders "Testing Posts". There's no obvious error that I can see, would appreciate the technique needed to further troubleshoot this. If I change the posts.data.js file name, then I get an obvious error...

Does the posts.data.js file need to live in the docs.vitepress\theme folder?

Would appreciate any further detail on this file and method.

[brc-dd]

You don't need to write <template> while writing vue in markdown. That's only needed inside SFCs.

[Karlstens]

With your help, I've been able to get a working proof of concept using createContentLoader to compare to my previously crafted solution, and am now comparing the pros/cons of both methods.

My modern JS script, statusCheck.mjs - at its heart simply creates/updates pure markdown.md files after checking the front matter of docs.

_writeToMarkdownFiles(data) {
		const statusCategories = {
			Draft: [],
			"For Review": [],
			"Technical Review": [],
			Published: [],
			"All Articles": data,
		};

		data.forEach((item) => {
			const category = item.status || "Status undefined";
			if (statusCategories.hasOwnProperty(category)) {
				statusCategories[category].push(item);
			}
		});
		let allArticlesContent = "";

		const statusTypeMap = {
			Draft: "tip",
			"Technical Review": "danger",
			Published: "warning",
		};

//Note this line below, where the markdown is written.

		Object.entries(statusCategories).forEach(([status, items]) => {
			const markdownContent = items
				.map((item) => {
					const statusType = statusTypeMap[item.status] || "info"; // Default to 'info' if status is not in the map
					return (
						`## ${item.title}\n` +
						`::: ${statusType} ${item.status}\n` +
						`Document Name: '${item.docName}'\n\n` +
						`Title: '${item.title}'\n\n` +
						`Category: '${item.category}'\n\n` +
						`Description: '${item.description}'\n\n` +
						`URL: ${item.liveSiteURL}\n` +
						`:::\n`
					);
				})
				.join("\n");

			// Append to all articles content
			allArticlesContent += markdownContent + "\n";

			// Write to individual status file
			const outputFilePath = path.join(
				statusDirectoryPath,
				`${status.toLowerCase().replace(/\s/g, "-")}.md`
			);
			fs.writeFileSync(outputFilePath, markdownContent, "utf8");
		});

		// Write all articles content to all-articles.md
		const allArticlesFilePath = path.join(
			statusDirectoryPath,
			"all-articles.md"
		);
		fs.writeFileSync(allArticlesFilePath, allArticlesContent, "utf8");
	}

My method above vs the out-of-the-box VitePress createContentLoader technique below;

<script setup>
    import { computed } from 'vue';
    import { data as posts } from '../../docs/.vitepress/theme/posts.data.js'

    const postCategories = [
        { name: 'Draft', filter: 'Draft' },
        { name: 'Technical Review', filter: 'Technical Review' },
        { name: 'Editor Review', filter: 'Editor Review' },
        { name: 'Published', filter: 'Published' },
        { name: 'Other', filter: null }
    ];

    const filteredPosts = computed(() => {
    return postCategories.map(category => {
        return {
        name: category.name,
        posts: category.filter
            ? posts.filter(post => post.frontmatter.status === category.filter)
            : posts.filter(post => !['Draft', 'Technical Review', 'Editor Review', 'Published'].includes(post.frontmatter.status))
        };
    });
    });
</script>

<div>
    <h1>Article Listing</h1>
    <div v-for="category in filteredPosts" :key="category.name">
        <h2>{{ category.name }}</h2>
        <div v-for="post in category.posts" :key="post.url" class="post">
        <h3 v-if="post.frontmatter.title">
            <a :href="post.url">{{ post.frontmatter.title }}</a>
        </h3>
        <h3 v-else>
            <a :href="post.url">{{ post.url }}</a>
        </h3>
        <div v-if="post.frontmatter.category" class="post-category">Category: {{ post.frontmatter.category }}</div>
        <div v-if="post.frontmatter.description" class="post-description">Description: {{ post.frontmatter.description }}</div>
        <div v-if="post.frontmatter.status" class="post-status">Status: <span :class="`status-${post.frontmatter.status.toLowerCase().replace(' ', '-')}`">{{ post.frontmatter.status || 'Undefined' }}</span></div>
        </div>
    </div>
</div>

Comparing the two, the createContentLoader runtime is perfect. As I update any article then the posts.md file updates accordingly and as expected. However, the markdown doesn't exist and thus is not executing within posts, resulting in a document that lacks hash navigation when using createContentLoader.

In comparison, the main advantage of my script is that it's outputting raw markdown and thus is still parsed like any other markdown file, including headings and hash navigation. But it's runtime is clunky and needs to be manually triggered.

If there's any suggestions on how to get Hash Navigation headings or Extended Markdown (::: tip / info / danger / warning ::: ) working with createContentLoader then I'll be completely sold on the idea! 😀