vitepress: Require initDovecotMd() to be called before configuration

Author: slusarz

.vitepress/config.js

@@ -3,7 +3,7 @@ import path from 'path'
 import { defineConfig } from 'vitepress'
 import { pagefindPlugin } from 'vitepress-plugin-pagefind'
 import { generateSidebar } from 'vitepress-sidebar'
-import { dovecotMdExtend } from '../lib/markdown.js'
+import { dovecotMdExtend, initDovecotMd } from '../lib/markdown.js'
 import { frontmatterIter } from '../lib/utility.js'
 import { checkExternalLinks, outputBrokenLinks } from '../lib/link_checker.js'
 
@@ -18,6 +18,11 @@ await frontmatterIter(function (f, data) {
 	}
 })
 
+// Need to bootstrap configuration for Dovecot markdown driver (specifically,
+// loading all data files to allow existence checking), or else the markdown
+// processing will begin before Dovecot link markup is enabled
+await initDovecotMd(base)
+
 export default defineConfig({
 	title: "Dovecot CE",
 	description: "Dovecot CE Documentation",
@@ -103,7 +108,7 @@ export default defineConfig({
 	},
 
 	markdown: {
-		config: async (md) => await dovecotMdExtend(md),
+		config: (md) => dovecotMdExtend(md),
 		image: {
 			lazyLoading: true,
 		},

lib/markdown.js

@@ -5,20 +5,16 @@ import path from 'path'
 import { createMarkdownRenderer } from 'vitepress'
 import { loadData, loadDovecotLinks, manFiles, pluginFiles, resolveURL } from './utility.js'
 
-export async function dovecotMdExtend(md) {
-	md.use(containerPlugin, 'todo', {
-		render: function(tokens, idx) {
-			if (tokens[idx].nesting === 1) {
-				return '<div class="caution custom-block">\n<p class="custom-block-title">⚠️ TODO</p>'
-			} else {
-				return '</div>\n'
-			}
-		}
-	})
-	md.use(deflistPlugin)
-	md.use(dovecot_markdown, {
+let md_conf = null
+export async function initDovecotMd(base) {
+	if (md_conf !== null) {
+		return
+	}
+
+	md_conf = {
+		base: base,
 		doveadm: (await loadData('doveadm')).doveadm,
-		dovecotlinks: await loadDovecotLinks(),
+		dovecotlinks: await loadDovecotLinks(base),
 		events: (await loadData('events')).events,
 		man: (await manFiles()).flatMap((x) => {
 			return fg.sync(x).map((y) => {
@@ -31,18 +27,36 @@ export async function dovecotMdExtend(md) {
 		),
 		settings: (await loadData('settings')).settings,
 		updates: (await loadData('updates')).updates
+	}
+}
+
+export function dovecotMdExtend(md) {
+	md.use(containerPlugin, 'todo', {
+		render: function(tokens, idx) {
+			if (tokens[idx].nesting === 1) {
+				return '<div class="caution custom-block">\n<p class="custom-block-title">⚠️ TODO</p>'
+			} else {
+				return '</div>\n'
+			}
+		}
 	})
+	md.use(deflistPlugin)
+
+	if (md_conf === null) {
+		throw new Error('Must call initDovecotMd() before calling this function!')
+	}
+	md.use(dovecot_markdown, md_conf)
 
 	return md
 }
 
 let vitepress_md = null
-
 export async function getVitepressMd() {
 	if (vitepress_md === null) {
 		const config = globalThis.VITEPRESS_CONFIG
 
-		vitepress_md = await dovecotMdExtend(await createMarkdownRenderer(
+		await initDovecotMd(config.site.base)
+		vitepress_md = dovecotMdExtend(await createMarkdownRenderer(
 			config.srcDir,
 			config.markdown,
 			config.site.base,
@@ -173,8 +187,8 @@ function dovecot_markdown(md, opts) {
 			}
 
 			return '<code><a href="' +
-				resolveURL('core/summaries/' + page + '.html#' + env.inner) +
-				'">'
+				resolveURL('core/summaries/' + page + '.html#' + env.inner,
+					opts.base) + '">'
 
 		case 'link':
 			let url = '#'
@@ -199,8 +213,8 @@ function dovecot_markdown(md, opts) {
 			}
 
 			return '<code><a href="' +
-				resolveURL('core/man/' + env.inner + '.' + env.args) +
-				'.html' + (hash ? '#' + hash : '') + '">'
+				resolveURL('core/man/' + env.inner + '.' + env.args,
+					opts.base) + '.html' + (hash ? '#' + hash : '') + '">'
 
 		case 'plugin':
 			env.inner = parts[1]
@@ -212,7 +226,7 @@ function dovecot_markdown(md, opts) {
 
 			return '<a href="' +
 				resolveURL('core/plugins/' + plugin + '.html' +
-					(parts[2] ? '#' + parts[2] : '')) + '">'
+					(parts[2] ? '#' + parts[2] : ''), opts.base) + '">'
 
 		case 'removed':
 			env.args = parts[1]
@@ -264,7 +278,8 @@ function dovecot_markdown(md, opts) {
 			}
 
 			return '<code><a href="' +
-				resolveURL('core/settings/variables.html' + hash) + '">'
+				resolveURL('core/settings/variables.html' + hash,
+					opts.base) + '">'
 
 		default:
 			throw new Error('Unknown dovecot markdown command: ' + mode)

lib/utility.js

@@ -132,7 +132,7 @@ export async function frontmatterIter(callback) {
 	}
 }
 
-export async function loadDovecotLinks() {
+export async function loadDovecotLinks(base) {
 	const links = {}
 
 	await frontmatterIter(function (f, data) {
@@ -146,7 +146,7 @@ export async function loadDovecotLinks() {
 			}
 
 			links[k] = {
-				url: resolveURL(f.substring(0, f.lastIndexOf('.')) + '.html')
+				url: resolveURL(f.substring(0, f.lastIndexOf('.')) + '.html', base)
 			}
 
 			if ((typeof v) == 'object') {
@@ -166,8 +166,7 @@ export async function loadDovecotLinks() {
 	return { ...links, ...data.links_overrides }
 }
 
-export function resolveURL(url) {
-	const base = globalThis.VITEPRESS_CONFIG.site.base
+export function resolveURL(url, base) {
 	return (base.endsWith('/') ? base.slice(0, -1) : base) + '/' + url
 }