From 17afa16e33e934c7e73a95fca768444fe0b0ad43 Mon Sep 17 00:00:00 2001
From: Michael M Slusarz <slusarz@users.noreply.github.com>
Date: Wed, 23 Oct 2024 15:18:11 -0600
Subject: [PATCH 1/9] local.js: Move watch paths out of local config file

---
 .vitepress/config.js              | 13 ++++++++++++-
 .vitepress/local.js.dist          |  9 ---------
 README.md                         | 14 ++++++++++++++
 lib/data/doveadm.data.js          |  7 +++----
 lib/data/event_categories.data.js |  7 +++----
 lib/data/event_reasons.data.js    |  7 +++----
 lib/data/events.data.js           |  7 +++----
 lib/data/lua.data.js              |  7 +++----
 lib/data/settings.data.js         |  7 +++----
 lib/utility.js                    | 24 ++++++++----------------
 10 files changed, 52 insertions(+), 50 deletions(-)

diff --git a/.vitepress/config.js b/.vitepress/config.js
index b9f6082e0..6882328a7 100644
--- a/.vitepress/config.js
+++ b/.vitepress/config.js
@@ -12,6 +12,14 @@ const base = '/2.4'
 // processing will begin before Dovecot link markup is enabled
 await initDovecotMd(base)
 
+export const dovecotConfig = {
+	watch_paths: [
+		'docs/**/*.md',
+		'docs/**/*.inc',
+		'data/**/*'
+	]
+}
+
 export default defineConfig({
 	title: "Dovecot CE",
 	description: "Dovecot CE Documentation",
@@ -103,7 +111,10 @@ export default defineConfig({
 		gitrev: {
 			align: 'right',
 			hash: gitCommitInfo().shortHash,
-		}
+		},
+
+		/* Dovecot config. */
+		dovecot: dovecotConfig,
 	},
 
 	markdown: {
diff --git a/.vitepress/local.js.dist b/.vitepress/local.js.dist
index a43e56659..d2c668a37 100644
--- a/.vitepress/local.js.dist
+++ b/.vitepress/local.js.dist
@@ -13,15 +13,6 @@ export const data_paths = {
 	// doveadm: '../data/doveadm.js',
 }
 
-// A listing of files to watch to refresh data loaders in dev mode.
-// See: https://vitepress.dev/guide/data-loading#data-from-local-files
-// Paths are relative to project base.
-//
-// Supports fast-glob: https://github.com/mrmlnc/fast-glob#pattern-syntax
-//
-// Default: [ 'docs/**/*.md', 'docs/**/*.inc', 'data/**/*' ]
-export const watch_paths = []
-
 // A listing of paths containing man files.
 // Paths are relative to project base.
 //
diff --git a/README.md b/README.md
index 18a6b4c34..809af4f6a 100644
--- a/README.md
+++ b/README.md
@@ -158,6 +158,20 @@ The data files live in the base `/data` directory. Each file attempts to be
 self-documenting, but they are all essentially large JSON objects. Developers
 should need to know basically no JavaScript to be able to edit the files.
 
+### Dovecot VitePress Configuration
+
+Additional configuration options required for VitePress static generation are
+defined using the `dovecot` object in the `themeConfig` VitePress
+configuration setting.
+
+#### watch_paths
+
+An array of file patterns to watch to refresh data loaders in dev mode.
+See: https://vitepress.dev/guide/data-loading#data-from-local-files
+Paths are relative to project base.
+
+Supports fast-glob: https://github.com/mrmlnc/fast-glob#pattern-syntax
+
 ### Dovecot Markdown Extensions
 
 Markdown has been extended to allow various Dovecot-specific tasks to be
diff --git a/lib/data/doveadm.data.js b/lib/data/doveadm.data.js
index c76fd5e93..1c54c7e47 100644
--- a/lib/data/doveadm.data.js
+++ b/lib/data/doveadm.data.js
@@ -1,6 +1,6 @@
 import { doveadm_arg_types, doveadm_flag_types, getDoveadmCmdLine } from '../doveadm.js'
 import { getVitepressMd } from '../markdown.js'
-import { loadData, normalizeArrayData, watchFiles } from '../utility.js'
+import { addWatchPaths, loadData, normalizeArrayData } from '../utility.js'
 import slugify from '@sindresorhus/slugify'
 
 const doveadm_userargs = {
@@ -147,11 +147,10 @@ async function normalizeDoveadm(doveadm) {
 	}
 }
 
-export default {
-	watch: await watchFiles(),
+export default addWatchPaths({
 	async load() {
 		return await normalizeDoveadm(
 			structuredClone((await loadData('doveadm')).doveadm)
 		)
 	}
-}
+})
diff --git a/lib/data/event_categories.data.js b/lib/data/event_categories.data.js
index 4e009ab4f..37edcb12a 100644
--- a/lib/data/event_categories.data.js
+++ b/lib/data/event_categories.data.js
@@ -1,5 +1,5 @@
 import { getVitepressMd } from '../markdown.js'
-import { loadData, watchFiles } from '../utility.js'
+import { addWatchPaths, loadData } from '../utility.js'
 
 async function normalizeEventCategories(categories) {
 	const md = await getVitepressMd()
@@ -11,11 +11,10 @@ async function normalizeEventCategories(categories) {
 	return categories
 }
 
-export default {
-	watch: await watchFiles(),
+export default addWatchPaths({
 	async load() {
 		return await normalizeEventCategories(
 			structuredClone((await loadData('event_categories')).categories)
 		)
 	}
-}
+})
diff --git a/lib/data/event_reasons.data.js b/lib/data/event_reasons.data.js
index 9ddd930ac..5f3cdb11f 100644
--- a/lib/data/event_reasons.data.js
+++ b/lib/data/event_reasons.data.js
@@ -1,5 +1,5 @@
 import { getVitepressMd } from '../markdown.js'
-import { loadData, watchFiles } from '../utility.js'
+import { addWatchPaths, loadData } from '../utility.js'
 
 async function normalizeEventReasons(reasons) {
 	const md = await getVitepressMd()
@@ -11,11 +11,10 @@ async function normalizeEventReasons(reasons) {
 	return reasons
 }
 
-export default {
-	watch: await watchFiles(),
+export default addWatchPaths({
 	async load() {
 		return await normalizeEventReasons(
 			structuredClone((await loadData('event_reasons')).reasons)
 		)
 	}
-}
+})
diff --git a/lib/data/events.data.js b/lib/data/events.data.js
index 82696b976..e3446f255 100644
--- a/lib/data/events.data.js
+++ b/lib/data/events.data.js
@@ -1,4 +1,4 @@
-import { loadData, normalizeArrayData, watchFiles } from '../utility.js'
+import { addWatchPaths, loadData, normalizeArrayData } from '../utility.js'
 import { getVitepressMd } from '../markdown.js'
 
 /* Take the events list and normalize entries and process inheritance. */
@@ -124,8 +124,7 @@ async function normalizeEvents(events, global_inherits, inherits) {
 	return events
 }
 
-export default {
-	watch: await watchFiles(),
+export default addWatchPaths({
 	async load() {
 		const data = await loadData('events')
 		return await normalizeEvents(
@@ -134,4 +133,4 @@ export default {
 			structuredClone(data.inherits)
 		)
 	}
-}
+})
diff --git a/lib/data/lua.data.js b/lib/data/lua.data.js
index 9490c5c87..363982f5f 100644
--- a/lib/data/lua.data.js
+++ b/lib/data/lua.data.js
@@ -1,5 +1,5 @@
 import { getVitepressMd } from '../markdown.js'
-import { loadData, watchFiles } from '../utility.js'
+import { addWatchPaths, loadData } from '../utility.js'
 
 async function normalizeLuaConstants(lua) {
 	const md = await getVitepressMd()
@@ -62,8 +62,7 @@ async function normalizeLuaVariables(lua) {
 	return out
 }
 
-export default {
-	watch: await watchFiles(),
+export default addWatchPaths({
 	async load() {
 		const data = await(loadData('lua'))
 
@@ -73,4 +72,4 @@ export default {
 			variables: await normalizeLuaVariables(data.lua_variables)
 		}
 	}
-}
+})
diff --git a/lib/data/settings.data.js b/lib/data/settings.data.js
index 9311ee2a4..7df26c155 100644
--- a/lib/data/settings.data.js
+++ b/lib/data/settings.data.js
@@ -1,4 +1,4 @@
-import { loadData, normalizeArrayData, watchFiles } from '../utility.js'
+import { addWatchPaths, loadData, normalizeArrayData } from '../utility.js'
 import { getVitepressMd } from '../markdown.js'
 
 async function normalizeSettings(settings) {
@@ -69,11 +69,10 @@ async function normalizeSettings(settings) {
 	return data
 }
 
-export default {
-	watch: await watchFiles(),
+export default addWatchPaths({
 	async load() {
 		return await normalizeSettings(
 			structuredClone((await loadData('settings')).settings)
 		)
 	}
-}
+})
diff --git a/lib/utility.js b/lib/utility.js
index dbb5d10cf..997f199b2 100644
--- a/lib/utility.js
+++ b/lib/utility.js
@@ -66,26 +66,18 @@ export async function loadData(id) {
 	}
 }
 
-export async function watchFiles() {
-	/* Check for config override file. */
-	const lconf = await loadLocalConf()
-
-	return lconf?.watch_paths ??
-		[ 'docs/**/*.md', 'docs/**/*.inc', 'data/**/*' ]
-}
+export function dovecotSetting(name) {
+	const setting = globalThis.VITEPRESS_CONFIG.userConfig.themeConfig.dovecot?.[name]
 
-export async function manFiles() {
-	/* Check for config override file. */
-	const lconf = await loadLocalConf()
+	if (setting === undefined) {
+		throw new Error("Missing '" + name + "' setting")
+	}
 
-	return lconf?.man_paths ??
-		[ 'docs/core/man/*.[[:digit:]].md' ]
+	return setting
 }
 
-export async function manIncludes() {
-	const lconf = await loadLocalConf()
-	return lconf?.man_includes ??
-		[ 'docs/core/man/include/*.inc' ]
+export function addWatchPaths(obj) {
+	return { ...obj, ...{ watch: dovecotSetting('watch_paths') } }
 }
 
 export async function pluginFiles() {

From cb963a82773249868c2b056ac63b9124cf35b514 Mon Sep 17 00:00:00 2001
From: Michael M Slusarz <slusarz@users.noreply.github.com>
Date: Mon, 28 Oct 2024 14:20:02 -0600
Subject: [PATCH 2/9] config.js: Move gitrev config into dovecot config
 namespace

Since this is also Dovecot-specifc config, store in the same main
namespace we will use for all other Dovecot specific config.
---
 .github/actions/spelling/expect.txt |  2 +-
 .vitepress/config.js                | 10 ++++------
 .vitepress/theme/DovecotLayout.vue  |  4 ++--
 README.md                           | 13 +++++++++++++
 4 files changed, 20 insertions(+), 9 deletions(-)

diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt
index d8176990d..75aedc35c 100644
--- a/.github/actions/spelling/expect.txt
+++ b/.github/actions/spelling/expect.txt
@@ -92,7 +92,6 @@ cnf
 cnrilrgfclra
 codahale
 codinghorror
-coi
 CONDSTORE
 convertpw
 copybox
@@ -247,6 +246,7 @@ gethosterror
 getmail
 getscript
 gitlab
+gitrev
 Gluster
 gmatch
 gno
diff --git a/.vitepress/config.js b/.vitepress/config.js
index 6882328a7..92a97f646 100644
--- a/.vitepress/config.js
+++ b/.vitepress/config.js
@@ -13,6 +13,10 @@ const base = '/2.4'
 await initDovecotMd(base)
 
 export const dovecotConfig = {
+	gitrev: {
+		align: 'right',
+		hash: gitCommitInfo().shortHash,
+	},
 	watch_paths: [
 		'docs/**/*.md',
 		'docs/**/*.inc',
@@ -107,12 +111,6 @@ export default defineConfig({
 			{ icon: 'github', link: 'https://github.com/dovecot/' },
 		],
 
-		/* Dovecot specific config: return gitrev for this build. */
-		gitrev: {
-			align: 'right',
-			hash: gitCommitInfo().shortHash,
-		},
-
 		/* Dovecot config. */
 		dovecot: dovecotConfig,
 	},
diff --git a/.vitepress/theme/DovecotLayout.vue b/.vitepress/theme/DovecotLayout.vue
index c8d501309..9e7f603ca 100644
--- a/.vitepress/theme/DovecotLayout.vue
+++ b/.vitepress/theme/DovecotLayout.vue
@@ -10,9 +10,9 @@ const { Layout } = DefaultTheme
  <Layout>
   <template #doc-footer-before>
    <div class="edit-info">
-    <div :class="'edit-rev edit-rev-' + theme.gitrev.align">
+    <div :class="'edit-rev edit-rev-' + theme.dovecot.gitrev.align">
      <div>
-      <p class="edit-updated">Revision: {{ theme.gitrev.hash }}</p>
+      <p class="edit-updated">Revision: {{ theme.dovecot.gitrev.hash }}</p>
      </div>
     </div>
    </div>
diff --git a/README.md b/README.md
index 809af4f6a..117561ff4 100644
--- a/README.md
+++ b/README.md
@@ -164,6 +164,19 @@ Additional configuration options required for VitePress static generation are
 defined using the `dovecot` object in the `themeConfig` VitePress
 configuration setting.
 
+#### gitrev
+
+Configures how the current git revision information is displayed in the
+page footer.
+
+##### align
+
+Alignment of the text. Either `left` or `right`.
+
+##### hash
+
+The git hash of the branch tip.
+
 #### watch_paths
 
 An array of file patterns to watch to refresh data loaders in dev mode.

From c3af0e4b0421a2f5abcb82e1efe6ec4919ba99bd Mon Sep 17 00:00:00 2001
From: Michael M Slusarz <slusarz@users.noreply.github.com>
Date: Mon, 28 Oct 2024 13:40:52 -0600
Subject: [PATCH 3/9] local.js: Move man paths out of local config file

---
 .vitepress/config.js     |  6 ++++++
 .vitepress/local.js.dist |  8 --------
 README.md                | 12 ++++++++++++
 lib/markdown.js          | 21 ++++++++++++++-------
 lib/utility.js           | 19 ++++++++++++++++---
 util/generate_man.js     |  9 +++++----
 6 files changed, 53 insertions(+), 22 deletions(-)

diff --git a/.vitepress/config.js b/.vitepress/config.js
index 92a97f646..de9ad8aa9 100644
--- a/.vitepress/config.js
+++ b/.vitepress/config.js
@@ -17,6 +17,12 @@ export const dovecotConfig = {
 		align: 'right',
 		hash: gitCommitInfo().shortHash,
 	},
+	man_includes: [
+		'docs/core/man/include/*.inc'
+	],
+	man_paths: [
+		'docs/core/man/*.[[:digit:]].md'
+	],
 	watch_paths: [
 		'docs/**/*.md',
 		'docs/**/*.inc',
diff --git a/.vitepress/local.js.dist b/.vitepress/local.js.dist
index d2c668a37..c5274b0a2 100644
--- a/.vitepress/local.js.dist
+++ b/.vitepress/local.js.dist
@@ -13,14 +13,6 @@ export const data_paths = {
 	// doveadm: '../data/doveadm.js',
 }
 
-// A listing of paths containing man files.
-// Paths are relative to project base.
-//
-// Supports fast-glob: https://github.com/mrmlnc/fast-glob#pattern-syntax
-//
-// Default: [ 'docs/core/man/*.[[:digit:]].md' ]
-export const man_paths = []
-
 // A listing of paths containing plugin files.
 // Paths are relative to project base.
 //
diff --git a/README.md b/README.md
index 117561ff4..c0b0cc7dd 100644
--- a/README.md
+++ b/README.md
@@ -177,6 +177,18 @@ Alignment of the text. Either `left` or `right`.
 
 The git hash of the branch tip.
 
+#### man_includes
+
+A list of additional paths (other than the `include/` directory of the man
+folder) where include files can live.
+
+#### man_paths
+
+A listing of paths containing man files.
+Paths are relative to project base.
+
+Supports fast-glob: https://github.com/mrmlnc/fast-glob#pattern-syntax
+
 #### watch_paths
 
 An array of file patterns to watch to refresh data loaders in dev mode.
diff --git a/lib/markdown.js b/lib/markdown.js
index 9949e0ea1..5764b6600 100644
--- a/lib/markdown.js
+++ b/lib/markdown.js
@@ -3,7 +3,7 @@ import fg from 'fast-glob'
 import deflistPlugin from 'markdown-it-deflist'
 import path from 'path'
 import { createMarkdownRenderer } from 'vitepress'
-import { frontmatterIter, loadData, manFiles, markdownExtension, pluginFiles, resolveURL } from './utility.js'
+import { dovecotSetting, frontmatterIter, loadData, markdownExtension, pluginFiles, resolveURL } from './utility.js'
 
 let md_conf = null
 export async function initDovecotMd(base) {
@@ -17,12 +17,6 @@ export async function initDovecotMd(base) {
 			doveadm: (await loadData('doveadm')).doveadm,
 			events: (await loadData('events')).events,
 			linkoverrides: (await loadData('links_overrides')).links_overrides,
-			man: (await manFiles()).flatMap((x) => {
-				return fg.sync(x).map((y) => {
-					const str = path.basename(y)
-					return str.substring(0, str.indexOf('.'))
-				})
-			}),
 			plugins: (await pluginFiles()).flatMap((x) =>
 				fg.sync(x).map((y) => path.basename(y, '.md'))
 			),
@@ -219,6 +213,8 @@ function dovecot_markdown(md, opts) {
 			hash = parts[2] ? parts[2] : false;
 			env.args = parts[3] ? parts[3] : 1;
 
+			initManFiles()
+
 			if (!opts.man.includes(env.inner)) {
 				handle_error('man link missing: ' + env.inner)
 				return '<a><code>'
@@ -426,6 +422,17 @@ function dovecot_markdown(md, opts) {
 		opts.dovecotlinks = { ...links, ...opts.linkoverrides }
 	}
 
+	function initManFiles() {
+		if (!opts.man) {
+			opts.man = dovecotSetting('man_paths').flatMap((x) => {
+				return fg.sync(x).map((y) => {
+					const str = path.basename(y)
+					return str.substring(0, str.indexOf('.'))
+				})
+			})
+		}
+	}
+
 	md.inline.ruler.after('emphasis', 'dovecot_brackets', process_brackets)
 	md.renderer.rules.dovecot_open = dovecot_open
 	md.renderer.rules.dovecot_body = dovecot_body
diff --git a/lib/utility.js b/lib/utility.js
index 997f199b2..251ccb532 100644
--- a/lib/utility.js
+++ b/lib/utility.js
@@ -66,9 +66,7 @@ export async function loadData(id) {
 	}
 }
 
-export function dovecotSetting(name) {
-	const setting = globalThis.VITEPRESS_CONFIG.userConfig.themeConfig.dovecot?.[name]
-
+function _dovecotSetting(name, setting) {
 	if (setting === undefined) {
 		throw new Error("Missing '" + name + "' setting")
 	}
@@ -76,6 +74,21 @@ export function dovecotSetting(name) {
 	return setting
 }
 
+/* Bootstrap the configuration by reading the .vitepress/config.js file. */
+export async function dovecotSettingBootstrap(name) {
+	return _dovecotSetting(
+		name,
+		(await import(process.cwd() + '/.vitepress/config.js')).dovecotConfig?.[name]
+	)
+}
+
+export function dovecotSetting(name) {
+	return _dovecotSetting(
+		name,
+		globalThis.VITEPRESS_CONFIG.userConfig.themeConfig.dovecot?.[name]
+	)
+}
+
 export function addWatchPaths(obj) {
 	return { ...obj, ...{ watch: dovecotSetting('watch_paths') } }
 }
diff --git a/util/generate_man.js b/util/generate_man.js
index a9e566775..dcf3ebd3b 100755
--- a/util/generate_man.js
+++ b/util/generate_man.js
@@ -14,7 +14,7 @@ import matter from 'gray-matter'
 import pdc from 'pdc'
 import path from 'path'
 import { VFile } from 'vfile'
-import { manFiles, manIncludes } from '../lib/utility.js'
+import { dovecotSettingBootstrap } from '../lib/utility.js'
 import remarkDeflist from 'remark-definition-list'
 import remarkMan from 'remark-man'
 import remarkParse from 'remark-parse'
@@ -43,7 +43,6 @@ program
 const debug = program.opts().debug
 
 
-
 const doInclude = (content, includes, f) => {
 	const result = content.replace(includesRE, (m, m1) => {
 		if (!m1.length) return m
@@ -126,8 +125,10 @@ const main = async (component, outPath) => {
 	}
 
 	/* Generate list of man files. */
-	const files = (await manFiles()).flatMap((x) => fg.sync(x))
-	const includes = (await manIncludes()).flatMap((x) => fg.sync(x))
+	const files = (await dovecotSettingBootstrap('man_paths'))
+		.flatMap((x) => fg.sync(x))
+	const includes = (await dovecotSettingBootstrap('man_includes'))
+		.flatMap((x) => fg.sync(x))
 
 	/* Get hash of last git commit. */
 	const gitHash = gitCommitInfo().shortHash

From 5b5d26875477e133cdab9d17e82ba92da262747f Mon Sep 17 00:00:00 2001
From: Michael M Slusarz <slusarz@users.noreply.github.com>
Date: Wed, 23 Oct 2024 15:36:22 -0600
Subject: [PATCH 4/9] local.js: Move plugin paths out of local config file

---
 .vitepress/config.js     |  3 +++
 .vitepress/local.js.dist |  8 --------
 README.md                |  7 +++++++
 lib/markdown.js          | 15 +++++++++++----
 lib/utility.js           |  8 --------
 5 files changed, 21 insertions(+), 20 deletions(-)

diff --git a/.vitepress/config.js b/.vitepress/config.js
index de9ad8aa9..de148be13 100644
--- a/.vitepress/config.js
+++ b/.vitepress/config.js
@@ -23,6 +23,9 @@ export const dovecotConfig = {
 	man_paths: [
 		'docs/core/man/*.[[:digit:]].md'
 	],
+	plugin_paths: [
+		'docs/core/plugins/*.md'
+	],
 	watch_paths: [
 		'docs/**/*.md',
 		'docs/**/*.inc',
diff --git a/.vitepress/local.js.dist b/.vitepress/local.js.dist
index c5274b0a2..8c0cd0316 100644
--- a/.vitepress/local.js.dist
+++ b/.vitepress/local.js.dist
@@ -13,14 +13,6 @@ export const data_paths = {
 	// doveadm: '../data/doveadm.js',
 }
 
-// A listing of paths containing plugin files.
-// Paths are relative to project base.
-//
-// Supports fast-glob: https://github.com/mrmlnc/fast-glob#pattern-syntax
-//
-// Default: [ 'docs/core/plugins/*.md' ]
-export const plugin_paths = []
-
 // Enable additional labels to support in Dovecot-specific markdown
 // processing (i.e. [[xyz,...]]).
 export const markdown_extend = {
diff --git a/README.md b/README.md
index c0b0cc7dd..356d8ea94 100644
--- a/README.md
+++ b/README.md
@@ -189,6 +189,13 @@ Paths are relative to project base.
 
 Supports fast-glob: https://github.com/mrmlnc/fast-glob#pattern-syntax
 
+#### plugin_paths
+
+A listing of paths containing plugin files.
+Paths are relative to project base.
+
+Supports fast-glob: https://github.com/mrmlnc/fast-glob#pattern-syntax
+
 #### watch_paths
 
 An array of file patterns to watch to refresh data loaders in dev mode.
diff --git a/lib/markdown.js b/lib/markdown.js
index 5764b6600..731b2074a 100644
--- a/lib/markdown.js
+++ b/lib/markdown.js
@@ -3,7 +3,7 @@ import fg from 'fast-glob'
 import deflistPlugin from 'markdown-it-deflist'
 import path from 'path'
 import { createMarkdownRenderer } from 'vitepress'
-import { dovecotSetting, frontmatterIter, loadData, markdownExtension, pluginFiles, resolveURL } from './utility.js'
+import { dovecotSetting, frontmatterIter, loadData, markdownExtension, resolveURL } from './utility.js'
 
 let md_conf = null
 export async function initDovecotMd(base) {
@@ -17,9 +17,6 @@ export async function initDovecotMd(base) {
 			doveadm: (await loadData('doveadm')).doveadm,
 			events: (await loadData('events')).events,
 			linkoverrides: (await loadData('links_overrides')).links_overrides,
-			plugins: (await pluginFiles()).flatMap((x) =>
-				fg.sync(x).map((y) => path.basename(y, '.md'))
-			),
 			settings: (await loadData('settings')).settings,
 			updates: (await loadData('updates')).updates
 		},
@@ -229,6 +226,8 @@ function dovecot_markdown(md, opts) {
 			env.args = parts[2] ? parts[2] : undefined
 			const plugin = env.inner.replaceAll('-', '_')
 
+			initPluginFiles()
+
 			if (!opts.plugins.includes(plugin)) {
 				handle_error('plugin link missing: ' + env.inner)
 				return '<a>'
@@ -433,6 +432,14 @@ function dovecot_markdown(md, opts) {
 		}
 	}
 
+	function initPluginFiles() {
+		if (!opts.plugins) {
+			opts.plugins = dovecotSetting('plugin_paths').flatMap((x) =>
+				fg.sync(x).map((y) => path.basename(y, '.md'))
+			)
+		}
+	}
+
 	md.inline.ruler.after('emphasis', 'dovecot_brackets', process_brackets)
 	md.renderer.rules.dovecot_open = dovecot_open
 	md.renderer.rules.dovecot_body = dovecot_body
diff --git a/lib/utility.js b/lib/utility.js
index 251ccb532..8fb148126 100644
--- a/lib/utility.js
+++ b/lib/utility.js
@@ -93,14 +93,6 @@ export function addWatchPaths(obj) {
 	return { ...obj, ...{ watch: dovecotSetting('watch_paths') } }
 }
 
-export async function pluginFiles() {
-	/* Check for config override file. */
-	const lconf = await loadLocalConf()
-
-	return lconf?.plugin_paths ??
-		[ 'docs/core/plugins/*.md' ]
-}
-
 export function getExcludes(srcDirs = [ 'docs' ]) {
 	const excludes = []
 

From e5ac780838452c0398990b126311ea3be14d8b79 Mon Sep 17 00:00:00 2001
From: Michael M Slusarz <slusarz@users.noreply.github.com>
Date: Wed, 23 Oct 2024 16:16:38 -0600
Subject: [PATCH 5/9] local.js: Move markdown_extend out of local config file

---
 .vitepress/local.js.dist | 19 -------------------
 README.md                | 23 +++++++++++++++++++++++
 lib/markdown.js          | 25 +++++++++++++++----------
 lib/utility.js           | 11 -----------
 4 files changed, 38 insertions(+), 40 deletions(-)

diff --git a/.vitepress/local.js.dist b/.vitepress/local.js.dist
index 8c0cd0316..7dc117c70 100644
--- a/.vitepress/local.js.dist
+++ b/.vitepress/local.js.dist
@@ -12,22 +12,3 @@
 export const data_paths = {
 	// doveadm: '../data/doveadm.js',
 }
-
-// Enable additional labels to support in Dovecot-specific markdown
-// processing (i.e. [[xyz,...]]).
-export const markdown_extend = {
-
-	// Init function. Return value is configuration options to add to markdown
-	// object.
-	// init: () => { return {} },
-
-	// Opening tag function. Returns opening tag.
-	// open: (mode, parts, opts, env) => { return '' },
-
-	// Body function. Returns body text.
-	// body: (mode, env) => { return '' },
-
-	// Close tag function. Returns closing tag.
-	// close: (mode, env) => { return '' },
-
-}
diff --git a/README.md b/README.md
index 356d8ea94..dc8820d8f 100644
--- a/README.md
+++ b/README.md
@@ -189,6 +189,29 @@ Paths are relative to project base.
 
 Supports fast-glob: https://github.com/mrmlnc/fast-glob#pattern-syntax
 
+#### markdown_extend
+
+An object containing callbacks that enable additional labels to support in
+Dovecot-specific markdown processing (i.e. [[xyz,...]]).
+
+##### open
+
+Opening tag function. Returns opening tag.
+
+Example: `open: (mode, parts, opts, env) => { return '' }`
+
+##### body
+
+Body function. Returns body text.
+
+Example: `body: (mode, env) => { return '' }`
+
+##### close
+
+Close tag function. Returns closing tag.
+
+Example: `close: (mode, env) => { return '' }`
+
 #### plugin_paths
 
 A listing of paths containing plugin files.
diff --git a/lib/markdown.js b/lib/markdown.js
index 731b2074a..2ca2ce16e 100644
--- a/lib/markdown.js
+++ b/lib/markdown.js
@@ -3,7 +3,7 @@ import fg from 'fast-glob'
 import deflistPlugin from 'markdown-it-deflist'
 import path from 'path'
 import { createMarkdownRenderer } from 'vitepress'
-import { dovecotSetting, frontmatterIter, loadData, markdownExtension, resolveURL } from './utility.js'
+import { dovecotSetting, frontmatterIter, loadData, resolveURL } from './utility.js'
 
 let md_conf = null
 export async function initDovecotMd(base) {
@@ -12,15 +12,12 @@ export async function initDovecotMd(base) {
 	}
 
 	md_conf = {
-		...{
-			base: base,
-			doveadm: (await loadData('doveadm')).doveadm,
-			events: (await loadData('events')).events,
-			linkoverrides: (await loadData('links_overrides')).links_overrides,
-			settings: (await loadData('settings')).settings,
-			updates: (await loadData('updates')).updates
-		},
-		...(await markdownExtension())
+		base: base,
+		doveadm: (await loadData('doveadm')).doveadm,
+		events: (await loadData('events')).events,
+		linkoverrides: (await loadData('links_overrides')).links_overrides,
+		settings: (await loadData('settings')).settings,
+		updates: (await loadData('updates')).updates
 	}
 }
 
@@ -291,6 +288,8 @@ function dovecot_markdown(md, opts) {
 					opts.base) + '">'
 
 		default:
+			initMarkdownExtend()
+
 			return handle_default(mode,
 				opts.markdown?.open?.(mode, parts, opts, env))
 		}
@@ -432,6 +431,12 @@ function dovecot_markdown(md, opts) {
 		}
 	}
 
+	function initMarkdownExtend() {
+		if (!opts.markdown) {
+			opts.markdown = dovecotSetting('markdown_extend') ?? {}
+		}
+	}
+
 	function initPluginFiles() {
 		if (!opts.plugins) {
 			opts.plugins = dovecotSetting('plugin_paths').flatMap((x) =>
diff --git a/lib/utility.js b/lib/utility.js
index 8fb148126..d1eb1218b 100644
--- a/lib/utility.js
+++ b/lib/utility.js
@@ -41,17 +41,6 @@ async function loadLocalConf() {
 	return local_conf
 }
 
-export async function markdownExtension() {
-	const lconf = await loadLocalConf()
-
-	return {
-		...{
-			markdown: lconf.markdown_extend ?? {},
-		},
-		...(lconf.markdown_extend?.init?.() ?? {})
-	}
-}
-
 export async function loadData(id) {
 	/* Check for config override file. */
 	const lconf = await loadLocalConf()

From b86e86b97d5937c238519c5651ef2e797909ec9c Mon Sep 17 00:00:00 2001
From: Michael M Slusarz <slusarz@users.noreply.github.com>
Date: Wed, 23 Oct 2024 16:34:13 -0600
Subject: [PATCH 6/9] local.js: Move data_paths out of local config file

---
 .vitepress/config.js     | 19 ++++++++++++-------
 .vitepress/local.js.dist | 14 --------------
 README.md                | 10 ++++++++++
 lib/markdown.js          | 29 ++++++++++-------------------
 lib/utility.js           |  6 ++----
 5 files changed, 34 insertions(+), 44 deletions(-)
 delete mode 100644 .vitepress/local.js.dist

diff --git a/.vitepress/config.js b/.vitepress/config.js
index de148be13..6f0fae83b 100644
--- a/.vitepress/config.js
+++ b/.vitepress/config.js
@@ -2,17 +2,22 @@ import gitCommitInfo from 'git-commit-info'
 import { defineConfig } from 'vitepress'
 import { pagefindPlugin } from 'vitepress-plugin-pagefind'
 import { generateSidebar } from 'vitepress-sidebar'
-import { dovecotMdExtend, initDovecotMd } from '../lib/markdown.js'
+import { dovecotMdExtend } from '../lib/markdown.js'
 import { getExcludes } from '../lib/utility.js'
 
 const base = '/2.4'
 
-// 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 const dovecotConfig = {
+	data_paths: {
+		doveadm: '../data/doveadm.js',
+		event_categories: '../data/event_categories.js',
+		event_reasons: '../data/event_reasons.js',
+		events: '../data/events.js',
+		links_overrides: '../data/links_overrides.js',
+		lua: '../data/lua.js',
+		settings: '../data/settings.js',
+		updates: '../data/updates.js',
+	},
 	gitrev: {
 		align: 'right',
 		hash: gitCommitInfo().shortHash,
@@ -125,7 +130,7 @@ export default defineConfig({
 	},
 
 	markdown: {
-		config: (md) => dovecotMdExtend(md),
+		config: async (md) => await dovecotMdExtend(md),
 		image: {
 			lazyLoading: true,
 		},
diff --git a/.vitepress/local.js.dist b/.vitepress/local.js.dist
deleted file mode 100644
index 7dc117c70..000000000
--- a/.vitepress/local.js.dist
+++ /dev/null
@@ -1,14 +0,0 @@
-/* This file allows configuration overrides of various core settings. */
-
-// Allows custom mapping of data sources.
-// It is used by the VitePress data loaders to determine what data to
-// load for export.
-//
-// By default, all data files are loaded from "../data" directory
-// (paths are relative to "<base>/lib").
-//
-// Keys are data identifiers, Values are location RELATIVE TO
-// * "<base>/lib" DIRECTORY.
-export const data_paths = {
-	// doveadm: '../data/doveadm.js',
-}
diff --git a/README.md b/README.md
index dc8820d8f..19302ea91 100644
--- a/README.md
+++ b/README.md
@@ -164,6 +164,16 @@ Additional configuration options required for VitePress static generation are
 defined using the `dovecot` object in the `themeConfig` VitePress
 configuration setting.
 
+#### data_paths
+
+Allows custom mapping of data sources.
+
+It is used by the VitePress data loaders to determine what data to
+load for export.
+
+Keys are data identifiers, Values are location RELATIVE TO `<base>/lib`
+DIRECTORY.
+
 #### gitrev
 
 Configures how the current git revision information is displayed in the
diff --git a/lib/markdown.js b/lib/markdown.js
index 2ca2ce16e..d3eaf7af2 100644
--- a/lib/markdown.js
+++ b/lib/markdown.js
@@ -6,22 +6,7 @@ import { createMarkdownRenderer } from 'vitepress'
 import { dovecotSetting, frontmatterIter, loadData, resolveURL } from './utility.js'
 
 let md_conf = null
-export async function initDovecotMd(base) {
-	if (md_conf !== null) {
-		return
-	}
-
-	md_conf = {
-		base: base,
-		doveadm: (await loadData('doveadm')).doveadm,
-		events: (await loadData('events')).events,
-		linkoverrides: (await loadData('links_overrides')).links_overrides,
-		settings: (await loadData('settings')).settings,
-		updates: (await loadData('updates')).updates
-	}
-}
-
-export function dovecotMdExtend(md) {
+export async function dovecotMdExtend(md) {
 	md.use(containerPlugin, 'todo', {
 		render: function(tokens, idx) {
 			if (tokens[idx].nesting === 1) {
@@ -34,7 +19,14 @@ export function dovecotMdExtend(md) {
 	md.use(deflistPlugin)
 
 	if (md_conf === null) {
-		throw new Error('Must call initDovecotMd() before calling this function!')
+		md_conf = {
+			base: globalThis.VITEPRESS_CONFIG.site.base,
+			doveadm: (await loadData('doveadm')).doveadm,
+			events: (await loadData('events')).events,
+			linkoverrides: (await loadData('links_overrides')).links_overrides,
+			settings: (await loadData('settings')).settings,
+			updates: (await loadData('updates')).updates
+		}
 	}
 	md.use(dovecot_markdown, md_conf)
 
@@ -46,8 +38,7 @@ export async function getVitepressMd() {
 	if (vitepress_md === null) {
 		const config = globalThis.VITEPRESS_CONFIG
 
-		await initDovecotMd(config.site.base)
-		vitepress_md = dovecotMdExtend(await createMarkdownRenderer(
+		vitepress_md = await dovecotMdExtend(await createMarkdownRenderer(
 			config.srcDir,
 			config.markdown,
 			config.site.base,
diff --git a/lib/utility.js b/lib/utility.js
index d1eb1218b..93919e255 100644
--- a/lib/utility.js
+++ b/lib/utility.js
@@ -42,10 +42,8 @@ async function loadLocalConf() {
 }
 
 export async function loadData(id) {
-	/* Check for config override file. */
-	const lconf = await loadLocalConf()
-	const path = lconf?.data_paths?.[id] ??
-		('../data/' + id + '.js')
+	const path = globalThis.VITEPRESS_CONFIG.userConfig.themeConfig.dovecot?.data_paths?.[id]
+		?? ('../data/' + id + '.js')
 
 	try {
 		return await import(__dirname + '/' + path)

From 187977ccecd7a073e9bb192fd605333d97f6a94f Mon Sep 17 00:00:00 2001
From: Michael M Slusarz <slusarz@users.noreply.github.com>
Date: Wed, 23 Oct 2024 16:46:51 -0600
Subject: [PATCH 7/9] utility.js: Remove no longer used local configuration
 path code

---
 lib/utility.js | 15 ---------------
 1 file changed, 15 deletions(-)

diff --git a/lib/utility.js b/lib/utility.js
index 93919e255..058e4bf98 100644
--- a/lib/utility.js
+++ b/lib/utility.js
@@ -9,8 +9,6 @@ import { fileURLToPath } from 'url'
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-const local_conf_path = __dirname + '/../.vitepress/local.js'
-
 export function normalizeArrayData(data, keys) {
 	for (const [k, v] of Object.entries(data)) {
 		if (v) {
@@ -28,19 +26,6 @@ export function normalizeArrayData(data, keys) {
 	return data
 }
 
-let local_conf = null
-async function loadLocalConf() {
-	if (local_conf === null) {
-		if (fs.existsSync(local_conf_path)) {
-			local_conf = await import(local_conf_path)
-		} else {
-			local_conf = false
-		}
-	}
-
-	return local_conf
-}
-
 export async function loadData(id) {
 	const path = globalThis.VITEPRESS_CONFIG.userConfig.themeConfig.dovecot?.data_paths?.[id]
 		?? ('../data/' + id + '.js')

From c159a55799698475d626cf71c342ffe722b77053 Mon Sep 17 00:00:00 2001
From: Michael M Slusarz <slusarz@users.noreply.github.com>
Date: Fri, 25 Oct 2024 13:38:58 -0600
Subject: [PATCH 8/9] utility.js: resolveURL() is now only used in markdown.js

opts.removeURL() is now an alias to the function, so configs that use
markdown_extend config can access it
---
 README.md       |  3 +++
 lib/markdown.js | 25 +++++++++++++++----------
 lib/utility.js  |  4 ----
 3 files changed, 18 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 19302ea91..5b40a701a 100644
--- a/README.md
+++ b/README.md
@@ -208,6 +208,9 @@ Dovecot-specific markdown processing (i.e. [[xyz,...]]).
 
 Opening tag function. Returns opening tag.
 
+The opts argument contains a "resolveURL" key that allows access to the
+internal Dovecot Markdown `resolveURL()` function.
+
 Example: `open: (mode, parts, opts, env) => { return '' }`
 
 ##### body
diff --git a/lib/markdown.js b/lib/markdown.js
index d3eaf7af2..fc60b1d2a 100644
--- a/lib/markdown.js
+++ b/lib/markdown.js
@@ -3,7 +3,7 @@ import fg from 'fast-glob'
 import deflistPlugin from 'markdown-it-deflist'
 import path from 'path'
 import { createMarkdownRenderer } from 'vitepress'
-import { dovecotSetting, frontmatterIter, loadData, resolveURL } from './utility.js'
+import { dovecotSetting, frontmatterIter, loadData } from './utility.js'
 
 let md_conf = null
 export async function dovecotMdExtend(md) {
@@ -174,8 +174,8 @@ function dovecot_markdown(md, opts) {
 			}
 
 			return '<code><a href="' +
-				resolveURL('core/summaries/' + page + '.html#' + env.inner,
-					opts.base) + '">'
+				resolveURL('core/summaries/' + page + '.html#' + env.inner) +
+				'">'
 
 		case 'link':
 			let url = '#'
@@ -206,8 +206,8 @@ function dovecot_markdown(md, opts) {
 			}
 
 			return '<code><a href="' +
-				resolveURL('core/man/' + env.inner + '.' + env.args,
-					opts.base) + '.html' + (hash ? '#' + hash : '') + '">'
+				resolveURL('core/man/' + env.inner + '.' + env.args) +
+				'.html' + (hash ? '#' + hash : '') + '">'
 
 		case 'plugin':
 			env.inner = parts[1]
@@ -222,8 +222,7 @@ function dovecot_markdown(md, opts) {
 			}
 
 			return '<a href="' +
-				resolveURL('core/plugins/' + plugin + '.html', opts.base) +
-					'">'
+				resolveURL('core/plugins/' + plugin + '.html') + '">'
 
 		case 'removed':
 			env.args = parts[1]
@@ -275,8 +274,7 @@ function dovecot_markdown(md, opts) {
 			}
 
 			return '<code><a href="' +
-				resolveURL('core/settings/variables.html' + hash,
-					opts.base) + '">'
+				resolveURL('core/settings/variables.html' + hash) + '">'
 
 		default:
 			initMarkdownExtend()
@@ -394,7 +392,7 @@ function dovecot_markdown(md, opts) {
 				}
 
 				links[k] = {
-					url: resolveURL(rewrites[f].substring(0, rewrites[f].lastIndexOf('.')) + '.html', opts.base)
+					url: resolveURL(rewrites[f].substring(0, rewrites[f].lastIndexOf('.')) + '.html')
 				}
 
 				if ((typeof v) == 'object') {
@@ -436,8 +434,15 @@ function dovecot_markdown(md, opts) {
 		}
 	}
 
+	function resolveURL(url) {
+		return (opts.base.endsWith('/') ? opts.base.slice(0, -1) : opts.base) +
+			'/' + url
+	}
+
 	md.inline.ruler.after('emphasis', 'dovecot_brackets', process_brackets)
 	md.renderer.rules.dovecot_open = dovecot_open
 	md.renderer.rules.dovecot_body = dovecot_body
 	md.renderer.rules.dovecot_close = dovecot_close
+
+	opts.resolveURL = resolveURL
 }
diff --git a/lib/utility.js b/lib/utility.js
index 058e4bf98..185f5385d 100644
--- a/lib/utility.js
+++ b/lib/utility.js
@@ -93,7 +93,3 @@ export function frontmatterIter(files, callback) {
 		}
 	}
 }
-
-export function resolveURL(url, base) {
-	return (base.endsWith('/') ? base.slice(0, -1) : base) + '/' + url
-}

From b57843a9926ff9ab64e65b3deff1de1fe63693fd Mon Sep 17 00:00:00 2001
From: Michael M Slusarz <slusarz@users.noreply.github.com>
Date: Fri, 25 Oct 2024 13:50:28 -0600
Subject: [PATCH 9/9] markdown.js: Allow Dovecot markdown generated URLs to be
 rewritten

---
 .vitepress/config.js | 1 +
 README.md            | 7 +++++++
 lib/markdown.js      | 8 +++++++-
 3 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/.vitepress/config.js b/.vitepress/config.js
index 6f0fae83b..89ea56ba9 100644
--- a/.vitepress/config.js
+++ b/.vitepress/config.js
@@ -31,6 +31,7 @@ export const dovecotConfig = {
 	plugin_paths: [
 		'docs/core/plugins/*.md'
 	],
+	url_rewrite: false,
 	watch_paths: [
 		'docs/**/*.md',
 		'docs/**/*.inc',
diff --git a/README.md b/README.md
index 5b40a701a..11aa318da 100644
--- a/README.md
+++ b/README.md
@@ -232,6 +232,13 @@ Paths are relative to project base.
 
 Supports fast-glob: https://github.com/mrmlnc/fast-glob#pattern-syntax
 
+#### url_rewrite
+
+A callback where Markdown generated URLs can be rewritten.
+Function is called the original URL and returns the (modified) URL.
+
+Example: `url_rewrite: (url) => { return url + '.foo' }`
+
 #### watch_paths
 
 An array of file patterns to watch to refresh data loaders in dev mode.
diff --git a/lib/markdown.js b/lib/markdown.js
index fc60b1d2a..43c26d879 100644
--- a/lib/markdown.js
+++ b/lib/markdown.js
@@ -435,8 +435,14 @@ function dovecot_markdown(md, opts) {
 	}
 
 	function resolveURL(url) {
-		return (opts.base.endsWith('/') ? opts.base.slice(0, -1) : opts.base) +
+		if (!('url_rewrite' in opts)) {
+			opts.url_rewrite = dovecotSetting('url_rewrite')
+		}
+
+		const new_url =
+			(opts.base.endsWith('/') ? opts.base.slice(0, -1) : opts.base) +
 			'/' + url
+		return (opts.url_rewrite) ? opts.url_rewrite(new_url) : new_url
 	}
 
 	md.inline.ruler.after('emphasis', 'dovecot_brackets', process_brackets)