Global parameters

[Karlstens]

I'm very new to VitePress and learning the ropes, and enjoying many aspects of this fantastic project.

After reading through the available documentation that I could find, I was still stuck on a method of introducing global parameters into my docs. Perhaps I missed a chapter, or misunderstood the guides I've been reading... regardless, I set out this morning to resolve a workflow that at least allows me to move forward with a solution, albeit a hack-solution at that (or maybe it;s a perfectly acceptable one? 😁 )

This is a module I created that does a word-for-word swap during dev/build process. Here, you can see what I consider global parameters such as "$appversion", "$animal" and "$colour", with the intent for them to swapout with the value they've been assigned, "1.0.0", "Cat" and "Blue".

..vitepress\enhanceMarkdown.mjs

export default function enhanceMarkdown(md) {
    const replacements = {
        "$appversion": "1.0.0",
        "$animal": "Cat",
        "$colour": "Blue",
        // Add more replacements as needed
    };

    // Create a regex pattern from the keys of the replacements object
    const regexPattern = new RegExp(
        Object.keys(replacements)
            .map(key => key.replace(/[-\/\\^$*+?.()|[\]{}]/g, '\\$&')) // Escape regex special characters
            .join('|'), 'g'
    );

    const replaceText = (str) => {
        return str.replace(regexPattern, (match) => {
            return replacements[match];
        });
    };

    const defaultRender =
        md.renderer.rules.text ||
        function (tokens, idx, options, env, self) {
            return self.renderToken(tokens, idx, options);
        };

    md.renderer.rules.text = function (tokens, idx, options, env, self) {
        tokens[idx].content = replaceText(tokens[idx].content);
        return defaultRender(tokens, idx, options, env, self);
    };
}

I import my enhanceMarkdown.mjs file into my vitePress config as such;

./.vitepress/config.mjs

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

// https://vitepress.dev/reference/site-config
export default defineConfig({
	title: "My Amazing Site",
	description: "Sandbox Testing",

	// Register the markdownIt plugin
	markdown: {
		config: (md) => {
			md.use(enhanceMarkdown);
		},
	},
...
}

And I author my markdown content, including the global variables where I need them.

---
title: Yay Amazing!
---

## App Version $appversion

The current application version is $appversion.

My favourite thing is a $colour $animal.

Which renders as;

App Version 1.0.0

The current application version is 1.0.0.

My favourite thing is a Blue Cat.

My question, is this the way to go about working with vitepress when it comes to setting up global parameters / global variables in a vitepress project? Or, am I actually building a mountain out of a molehill for what I assumed to be an out-of-the-box feature that I've somehow missed, and there's actually a far simplier method to implement this?

Side quest: Assuming that what I've created is one way of resolving the problem, perhaps there's actually a better/simpler way to resolve this same requirement for global parameters?

Edit: Also worth noting this method so that the values can return as expected within a Codeblock.

https://vitepress.dev/guide/using-vue#unescape-in-code-blocks

[IgnisDa]

@Karlstens Did you find a solution for this?

[brc-dd]

Did you read the issue? It has a solution mentioned.

Instead of replacing in markdown, you can also do something like this - https://stackblitz.com/edit/vite-hfhocux9?file=docs/index.md,docs/.vitepress/theme/index.ts. But either is fine IMO.

[SimonEast]

I spent some time attempting this today, as I wanted to store a key URL in one central location and refer to it in various documentation pages. I found two approaches to this, in addition to @Karlstens' solution:

Option 1: globalProperties

This is based on @brc-dd's example (thank you!):

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme';
export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
	  // Define global properties:
	  // Accessible in all pages via {{ propertyName }}
	  app.config.globalProperties.$someProperty = '...'; 

Then in any markdown page, you can refer to the property as:

{{ $someProperty }}

The $ prefix is not essential, but is probably good practice to avoid clashes with Vue built-in properties.

Option 2: useData()

On a standard install, useData() in markdown pages can be cumbersome, as you normally need to add a <script> tag and import the function, but with the unplugin-auto-import library you can avoid this step. Here's how I did it:

npm install unplugin-auto-import

Then:

// .vitepress/config.js
import AutoImport from 'unplugin-auto-import/vite'

export default {
vite: {
  plugins: [
  AutoImport({
    imports: [ 'vitepress' ],  // or {vitepress: ['useData', 'useRouter', 'useRoute'] },
    vueTemplate: true,
    include: [/\.vue$/, /\.vue\?vue/, /\.md$/], // Auto-import in Vue and Markdown files

Then in any markdown page you can call:

{{ useData().isDark }}
{{ useData().page }}
{{ useData().params }}
{{ useData().site }}
{{ useData().theme }}
etc...

You can add variables to your .vitepress/config.js object and they will be accessible via {{ useData().site }}.

A note about markdown links

I found that you cannot embed Vue variables into markdown-style links. For example you CANNOT do this:

[My Link]({{ $globalUrl }})

I think this is because the markdown parser runs before the Vue variable gets interpreted. Instead you need to use HTML:

<a :href="$globalUrl">My Link</a>

It looks like @Karlstens' original solution might actually parse the global variables before the markdown, in which case it might work even smoother when used in links like this.

Hope that helps others looking for clean ways to do this.