diff --git a/.vitepress/config.js b/.vitepress/config.js index a7f41ce4d..b9f6082e0 100644 --- a/.vitepress/config.js +++ b/.vitepress/config.js @@ -1,22 +1,12 @@ import gitCommitInfo from 'git-commit-info' -import path from 'path' import { defineConfig } from 'vitepress' import { pagefindPlugin } from 'vitepress-plugin-pagefind' import { generateSidebar } from 'vitepress-sidebar' import { dovecotMdExtend, initDovecotMd } from '../lib/markdown.js' -import { frontmatterIter } from '../lib/utility.js' +import { getExcludes } from '../lib/utility.js' const base = '/2.4' -// No need to include the "dummy" index files, used to build titles -// for the sidebar, into the final documentation bundles -const excludes = [] -await frontmatterIter(function (f, data) { - if (data.exclude) { - excludes.push(path.relative('docs/', f)) - } -}) - // 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 @@ -27,8 +17,11 @@ export default defineConfig({ description: "Dovecot CE Documentation", lang: "en-us", - srcDir: "docs", - srcExclude: excludes, + srcDir: ".", + srcExclude: [ '*.md' ].concat(getExcludes()), + rewrites: { + 'docs/:path(.*)': ':path', + }, base: base, sitemap: { diff --git a/.vitepress/local.js.dist b/.vitepress/local.js.dist index 8e560d296..a43e56659 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 source files (.md) for the documentation. -// Paths are relative to project base. -// -// Supports fast-glob: https://github.com/mrmlnc/fast-glob#pattern-syntax -// -// Default: [ 'docs/**/*.md' ] -export const source_paths = [] - // 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. @@ -30,14 +22,6 @@ export const source_paths = [] // Default: [ 'docs/**/*.md', 'docs/**/*.inc', 'data/**/*' ] export const watch_paths = [] -// A listing of source path translations. -// -// This is the same format as VitePress' 'rewrite' setting: -// https://vitepress.dev/reference/site-config#rewrites -// -// Default: { 'docs/:path(.*)': ':path' } -export const source_path_translations = {} - // A listing of paths containing man files. // Paths are relative to project base. // diff --git a/data/updates.js b/data/updates.js index fc146fc67..5267d7080 100644 --- a/data/updates.js +++ b/data/updates.js @@ -23,6 +23,7 @@ export const updates = { auth_server_common_secured: '2.4.0', dcrypt_same_cipher_algo_added: '2.4.0', dict_idle_timeout_added: '2.4.0', + dict_protocol_v4: '2.4.0', dict_slow_warn_added: '2.4.0', doveadm_ex_expired_code: '2.4.0', doveadm_mailbox_commands_user: '2.4.0', diff --git a/docs/developers/design/arrays.md b/docs/core/design/arrays.md similarity index 100% rename from docs/developers/design/arrays.md rename to docs/core/design/arrays.md diff --git a/docs/developers/design/auth_process.md b/docs/core/design/auth_process.md similarity index 100% rename from docs/developers/design/auth_process.md rename to docs/core/design/auth_process.md diff --git a/docs/developers/design/auth_protocol.md b/docs/core/design/auth_protocol.md similarity index 100% rename from docs/developers/design/auth_protocol.md rename to docs/core/design/auth_protocol.md diff --git a/docs/developers/design/buffers.md b/docs/core/design/buffers.md similarity index 100% rename from docs/developers/design/buffers.md rename to docs/core/design/buffers.md diff --git a/docs/developers/design/dcrypt.md b/docs/core/design/dcrypt.md similarity index 100% rename from docs/developers/design/dcrypt.md rename to docs/core/design/dcrypt.md diff --git a/docs/developers/design/dict_protocol.md b/docs/core/design/dict_protocol.md similarity index 98% rename from docs/developers/design/dict_protocol.md rename to docs/core/design/dict_protocol.md index 360147c82..3c05e2d05 100644 --- a/docs/developers/design/dict_protocol.md +++ b/docs/core/design/dict_protocol.md @@ -11,8 +11,8 @@ dovecotlinks: This document describes Dovecot Dict protocol v3.2 which is supported in Dovecot v2.3.17+. -Dovecot Core v2.4.0 changed the version to v4, but it's otherwise compatible -with v3.2 +[[changed,dict_protocol_v4]] Dict protocol version was updated to v4, but +it's otherwise compatible with v3.2. ::: Dovecot's dict protocol is a line based protocol between the dict client and diff --git a/docs/developers/design/doveadm_protocol.md b/docs/core/design/doveadm_protocol.md similarity index 100% rename from docs/developers/design/doveadm_protocol.md rename to docs/core/design/doveadm_protocol.md diff --git a/docs/developers/design/dsync.md b/docs/core/design/dsync.md similarity index 100% rename from docs/developers/design/dsync.md rename to docs/core/design/dsync.md diff --git a/docs/developers/design/events.md b/docs/core/design/events.md similarity index 100% rename from docs/developers/design/events.md rename to docs/core/design/events.md diff --git a/docs/developers/design/images/auth.drawio b/docs/core/design/images/auth.drawio similarity index 100% rename from docs/developers/design/images/auth.drawio rename to docs/core/design/images/auth.drawio diff --git a/docs/developers/design/images/auth.png b/docs/core/design/images/auth.png similarity index 100% rename from docs/developers/design/images/auth.png rename to docs/core/design/images/auth.png diff --git a/docs/developers/design/index.md b/docs/core/design/index.md similarity index 100% rename from docs/developers/design/index.md rename to docs/core/design/index.md diff --git a/docs/developers/design/indexes/images/lib-index.drawio b/docs/core/design/indexes/images/lib-index.drawio similarity index 100% rename from docs/developers/design/indexes/images/lib-index.drawio rename to docs/core/design/indexes/images/lib-index.drawio diff --git a/docs/developers/design/indexes/images/lib-index.png b/docs/core/design/indexes/images/lib-index.png similarity index 100% rename from docs/developers/design/indexes/images/lib-index.png rename to docs/core/design/indexes/images/lib-index.png diff --git a/docs/developers/design/indexes/images/mail-index-cache.drawio b/docs/core/design/indexes/images/mail-index-cache.drawio similarity index 100% rename from docs/developers/design/indexes/images/mail-index-cache.drawio rename to docs/core/design/indexes/images/mail-index-cache.drawio diff --git a/docs/developers/design/indexes/images/mail-index-cache.png b/docs/core/design/indexes/images/mail-index-cache.png similarity index 100% rename from docs/developers/design/indexes/images/mail-index-cache.png rename to docs/core/design/indexes/images/mail-index-cache.png diff --git a/docs/developers/design/indexes/images/mail-index-log.drawio b/docs/core/design/indexes/images/mail-index-log.drawio similarity index 100% rename from docs/developers/design/indexes/images/mail-index-log.drawio rename to docs/core/design/indexes/images/mail-index-log.drawio diff --git a/docs/developers/design/indexes/images/mail-index-log.png b/docs/core/design/indexes/images/mail-index-log.png similarity index 100% rename from docs/developers/design/indexes/images/mail-index-log.png rename to docs/core/design/indexes/images/mail-index-log.png diff --git a/docs/developers/design/indexes/images/mail-index-map.drawio b/docs/core/design/indexes/images/mail-index-map.drawio similarity index 100% rename from docs/developers/design/indexes/images/mail-index-map.drawio rename to docs/core/design/indexes/images/mail-index-map.drawio diff --git a/docs/developers/design/indexes/images/mail-index-map.png b/docs/core/design/indexes/images/mail-index-map.png similarity index 100% rename from docs/developers/design/indexes/images/mail-index-map.png rename to docs/core/design/indexes/images/mail-index-map.png diff --git a/docs/developers/design/indexes/index.md b/docs/core/design/indexes/index.md similarity index 100% rename from docs/developers/design/indexes/index.md rename to docs/core/design/indexes/index.md diff --git a/docs/developers/design/indexes/index_cache.md b/docs/core/design/indexes/index_cache.md similarity index 100% rename from docs/developers/design/indexes/index_cache.md rename to docs/core/design/indexes/index_cache.md diff --git a/docs/developers/design/indexes/index_format.md b/docs/core/design/indexes/index_format.md similarity index 100% rename from docs/developers/design/indexes/index_format.md rename to docs/core/design/indexes/index_format.md diff --git a/docs/developers/design/indexes/index_format_main.md b/docs/core/design/indexes/index_format_main.md similarity index 100% rename from docs/developers/design/indexes/index_format_main.md rename to docs/core/design/indexes/index_format_main.md diff --git a/docs/developers/design/indexes/index_log.md b/docs/core/design/indexes/index_log.md similarity index 100% rename from docs/developers/design/indexes/index_log.md rename to docs/core/design/indexes/index_log.md diff --git a/docs/developers/design/indexes/mail_index_api.md b/docs/core/design/indexes/mail_index_api.md similarity index 100% rename from docs/developers/design/indexes/mail_index_api.md rename to docs/core/design/indexes/mail_index_api.md diff --git a/docs/developers/design/istreams.md b/docs/core/design/istreams.md similarity index 100% rename from docs/developers/design/istreams.md rename to docs/core/design/istreams.md diff --git a/docs/developers/design/mail.md b/docs/core/design/mail.md similarity index 100% rename from docs/developers/design/mail.md rename to docs/core/design/mail.md diff --git a/docs/developers/design/mail_namespace.md b/docs/core/design/mail_namespace.md similarity index 100% rename from docs/developers/design/mail_namespace.md rename to docs/core/design/mail_namespace.md diff --git a/docs/developers/design/mail_plugins.md b/docs/core/design/mail_plugins.md similarity index 100% rename from docs/developers/design/mail_plugins.md rename to docs/core/design/mail_plugins.md diff --git a/docs/developers/design/mail_storage.md b/docs/core/design/mail_storage.md similarity index 100% rename from docs/developers/design/mail_storage.md rename to docs/core/design/mail_storage.md diff --git a/docs/developers/design/mail_user.md b/docs/core/design/mail_user.md similarity index 100% rename from docs/developers/design/mail_user.md rename to docs/core/design/mail_user.md diff --git a/docs/developers/design/mailbox.md b/docs/core/design/mailbox.md similarity index 100% rename from docs/developers/design/mailbox.md rename to docs/core/design/mailbox.md diff --git a/docs/developers/design/mailbox_list.md b/docs/core/design/mailbox_list.md similarity index 100% rename from docs/developers/design/mailbox_list.md rename to docs/core/design/mailbox_list.md diff --git a/docs/developers/design/mailbox_saving.md b/docs/core/design/mailbox_saving.md similarity index 100% rename from docs/developers/design/mailbox_saving.md rename to docs/core/design/mailbox_saving.md diff --git a/docs/developers/design/mailbox_searching.md b/docs/core/design/mailbox_searching.md similarity index 100% rename from docs/developers/design/mailbox_searching.md rename to docs/core/design/mailbox_searching.md diff --git a/docs/developers/design/mailbox_syncing.md b/docs/core/design/mailbox_syncing.md similarity index 100% rename from docs/developers/design/mailbox_syncing.md rename to docs/core/design/mailbox_syncing.md diff --git a/docs/developers/design/mailbox_transaction.md b/docs/core/design/mailbox_transaction.md similarity index 100% rename from docs/developers/design/mailbox_transaction.md rename to docs/core/design/mailbox_transaction.md diff --git a/docs/developers/design/memory.md b/docs/core/design/memory.md similarity index 100% rename from docs/developers/design/memory.md rename to docs/core/design/memory.md diff --git a/docs/developers/design/ostreams.md b/docs/core/design/ostreams.md similarity index 100% rename from docs/developers/design/ostreams.md rename to docs/core/design/ostreams.md diff --git a/docs/developers/design/overview.md b/docs/core/design/overview.md similarity index 100% rename from docs/developers/design/overview.md rename to docs/core/design/overview.md diff --git a/docs/developers/design/plugins.md b/docs/core/design/plugins.md similarity index 100% rename from docs/developers/design/plugins.md rename to docs/core/design/plugins.md diff --git a/docs/developers/design/processes.md b/docs/core/design/processes.md similarity index 100% rename from docs/developers/design/processes.md rename to docs/core/design/processes.md diff --git a/docs/developers/design/storage_errors.md b/docs/core/design/storage_errors.md similarity index 100% rename from docs/developers/design/storage_errors.md rename to docs/core/design/storage_errors.md diff --git a/docs/developers/design/strings.md b/docs/core/design/strings.md similarity index 100% rename from docs/developers/design/strings.md rename to docs/core/design/strings.md diff --git a/lib/markdown.js b/lib/markdown.js index 69ca44885..9949e0ea1 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 { loadData, loadDovecotLinks, manFiles, markdownExtension, pluginFiles, resolveURL } from './utility.js' +import { frontmatterIter, loadData, manFiles, markdownExtension, pluginFiles, resolveURL } from './utility.js' let md_conf = null export async function initDovecotMd(base) { @@ -15,8 +15,8 @@ export async function initDovecotMd(base) { ...{ base: base, doveadm: (await loadData('doveadm')).doveadm, - dovecotlinks: await loadDovecotLinks(base), 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) @@ -202,6 +202,8 @@ function dovecot_markdown(md, opts) { let url = '#' env.inner = false + initDovecotLinks() + if (!opts.dovecotlinks[parts[1]]) { handle_error('Dovecot link missing: ' + parts[1]) return '' @@ -388,6 +390,42 @@ function dovecot_markdown(md, opts) { console.error(msg) } + function initDovecotLinks() { + if (opts.dovecotlinks) { + return + } + + const links = {} + const rewrites = globalThis.VITEPRESS_CONFIG.rewrites.map + + frontmatterIter(Object.keys(rewrites), function (f, data) { + if (!data.dovecotlinks) { + return + } + + for (const [k, v] of Object.entries(data.dovecotlinks)) { + if (links[k]) { + throw new Error("Duplicate Dovecot Link key: " + k) + } + + links[k] = { + url: resolveURL(rewrites[f].substring(0, rewrites[f].lastIndexOf('.')) + '.html', opts.base) + } + + if ((typeof v) == 'object') { + links[k].text = v.text + if (v.hash) { + links[k].url += '#' + v.hash + } + } else { + links[k].text = v + } + } + }) + + opts.dovecotlinks = { ...links, ...opts.linkoverrides } + } + 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 05f467b0b..dbb5d10cf 100644 --- a/lib/utility.js +++ b/lib/utility.js @@ -3,9 +3,8 @@ import fg from 'fast-glob' import fs from 'fs' import matter from 'gray-matter' -import { dirname } from 'path'; -import { compile, match } from 'path-to-regexp' -import { fileURLToPath } from 'url'; +import { dirname } from 'path' +import { fileURLToPath } from 'url' const __filename = fileURLToPath(import.meta.url); const __dirname = dirname(__filename); @@ -67,13 +66,6 @@ export async function loadData(id) { } } -export async function sourceFiles() { - /* Check for config override file. */ - const lconf = await loadLocalConf() - - return lconf?.source_paths ?? [ 'docs/**/*.md' ] -} - export async function watchFiles() { /* Check for config override file. */ const lconf = await loadLocalConf() @@ -104,68 +96,33 @@ export async function pluginFiles() { [ 'docs/core/plugins/*.md' ] } -export async function frontmatterIter(callback) { - const sf = await sourceFiles() - const files = sf.flatMap((x) => fg.sync(x)) - - /* Check for config override file. */ - const lconf = await loadLocalConf() - const spt_conf = lconf?.source_path_translations ?? - { 'docs/:path': ':path' } - - const spt = Object.entries(spt_conf).map(([from, to]) => ({ - toPath: compile(`/${to}`, { validate: false }), - matchUrl: match(from) - })) +export function getExcludes(srcDirs = [ 'docs' ]) { + const excludes = [] - for (let f of files) { - const str = fs.readFileSync(f, 'utf8') - const data = matter(str).data - - for (const { matchUrl, toPath } of spt) { - const res = matchUrl(f) - if (res) { - f = toPath(res.params).slice(1) - break + frontmatterIter( + srcDirs.flatMap((x) => fg.sync(x + '/**/*.md')), + function (f, data) { + /* Exclude all pages with "exclude" frontmatter present. */ + if (data.exclude) { + excludes.push(f) } } + ) - callback(f, data) - } + return excludes } -export async function loadDovecotLinks(base) { - const links = {} - - await frontmatterIter(function (f, data) { - if (!data.dovecotlinks) { - return - } - - for (const [k,v] of Object.entries(data.dovecotlinks)) { - if (links[k]) { - throw new Error("Duplicate Dovecot Link key: " + k) - } - - links[k] = { - url: resolveURL(f.substring(0, f.lastIndexOf('.')) + '.html', base) - } - - if ((typeof v) == 'object') { - links[k].text = v.text - if (v.hash) { - links[k].url += '#' + v.hash - } - } else { - links[k].text = v - } +export function frontmatterIter(files, callback) { + for (let f of files) { + try { + const str = fs.readFileSync(f, 'utf8') + callback(f, matter(str).data) + } catch (err) { + /* Ignore file not exist errors, since they can occur for + * dynamically generated paths (e.g. Release Notes). */ + if (err.code !== 'ENOENT') throw err } - }) - - const data = await loadData('links_overrides') - - /* Merge the two lists together. */ - return { ...links, ...data.links_overrides } + } } export function resolveURL(url, base) { diff --git a/package-lock.json b/package-lock.json index 716fdd531..7b89509a0 100644 --- a/package-lock.json +++ b/package-lock.json @@ -14,7 +14,6 @@ "markdown-it-deflist": "^3.0.0", "markdown-it-mathjax3": "^4.3.2", "pagefind": "^1.1.1", - "path-to-regexp": "^8.1.0", "pdc": "^0.2.3", "remark-definition-list": "^2.0.0", "remark-man": "^9.0.0", @@ -4052,15 +4051,6 @@ "node": ">=8" } }, - "node_modules/path-to-regexp": { - "version": "8.1.0", - "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.1.0.tgz", - "integrity": "sha512-Bqn3vc8CMHty6zuD+tG23s6v2kwxslHEhTj4eYaVKGIEB+YX/2wd0/rgXLFD9G9id9KCtbVy/3ZgmvZjpa0UdQ==", - "dev": true, - "engines": { - "node": ">=16" - } - }, "node_modules/pdc": { "version": "0.2.3", "resolved": "https://registry.npmjs.org/pdc/-/pdc-0.2.3.tgz", diff --git a/package.json b/package.json index 1d1aaa57f..9d59f77f4 100644 --- a/package.json +++ b/package.json @@ -9,7 +9,6 @@ "markdown-it-deflist": "^3.0.0", "markdown-it-mathjax3": "^4.3.2", "pagefind": "^1.1.1", - "path-to-regexp": "^8.1.0", "pdc": "^0.2.3", "remark-definition-list": "^2.0.0", "remark-man": "^9.0.0",