Setting set link text

README.md

@@ -242,14 +242,24 @@ Links to the RFC page (external).
 #### Settings
 
 ***Syntax: `[[setting,setting_name(,args)]]`***
+***Syntax: `[[setting_text,setting_name(,text)]]`***
 
-If args is set, it is appended to the display as a setting value. Example:
+For the `setting` variant, if args is set, it is appended to the display as a
+setting value. Example:
 
 ```
 # [[setting,foo,5]] results in:
 <a href="PATH_TO_FOO_SETTING">foo = 5</a>
 ```
 
+For the `setting_text` variant, if text is set, it is used as the link text.
+Example:
+
+```
+# [[setting_text,foo,bar]] results in:
+<a href="PATH_TO_FOO_SETTING">bar</a>
+```
+
 #### Variable
 
 ***Syntax: `[[variable(,section)]]`***

docs/core/admin/guides/spam_reporting.md

@@ -26,7 +26,7 @@ messages in/out of the Spam mailbox.
 **You cannot run scripts anywhere you want.**
 
 Sieve allows you to only run scripts under
-[[setting,sieve_>extension<_bin_dir,sieve_pipe_bin_dir]]. You
+[[setting_text,sieve_<extension>_bin_dir,sieve_pipe_bin_dir]]. You
 can't use `/usr/local/bin/my-sieve-filter.sh`, you have to put the
 script under `sieve_pipe_bin_dir` and use `my-sieve-filter.sh` in the
 script instead.

docs/core/config/auth/userdb.md

@@ -328,7 +328,7 @@ namespace default {
 ```
 
 The separator setting can be overridden by returning
-[[setting,namespace/separator,namespace/default/separator]] extra field.
+[[setting_text,namespace/separator,namespace/default/separator]] extra field.
 
 ### Examples
 

docs/installation/upgrade/include/2.3-to-2.3.x.inc

@@ -11,9 +11,10 @@
 ### v2.3.x to v2.3.14
 
 * Removed autocreate plugin. Use
-  [[setting,namespace/mailbox/auto,mailbox { auto }]] instead.
+  [[setting_text,namespace/mailbox/auto,mailbox { auto }]] instead.
 * Removed expire plugin. Use
-  [[setting,namespace/mailbox/autoexpunge,mailbox { autoexpunge }]] instead.
+  [[setting_text,namespace/mailbox/autoexpunge,mailbox { autoexpunge }]]
+  instead.
 * Removed xz write support from zlib plugin. (Reading xz compressed mails
   is still supported.) Use another compression algorithm.
 

lib/markdown.js

@@ -156,6 +156,7 @@ function dovecot_markdown(md, opts) {
 		case 'doveadm':
 		case 'event':
 		case 'setting':
+		case 'setting_text':
 			env.inner = parts[1]
 			env.args = parts[2] ? parts[2] : undefined;
 
@@ -179,16 +180,17 @@ function dovecot_markdown(md, opts) {
 				break
 
 			case 'setting':
+			case 'setting_text':
 				/* Settings names can have brackets, so we need to unescape
 				 * input for purposes of searching settings keys. */
-				const search_str = env.inner.replaceAll('&gt;', '<')
-						.replaceAll('&lt;', '>')
+				const search_str = env.inner.replaceAll('&gt;', '>')
+						.replaceAll('&lt;', '<')
 
 				if (!opts.settings[search_str]) {
 					handle_error('setting link missing: ' + env.inner)
 					return '<code><a>'
 				}
-				page += 's'
+				page = 'settings'
 				break
 			}
 
@@ -334,6 +336,9 @@ function dovecot_markdown(md, opts) {
 		case 'setting':
 			return env.inner + (env.args ? ' = ' + env.args : '')
 
+		case 'setting_text':
+			return env.args ?? env.inner
+
 		case 'variable':
 			return env.inner
 
@@ -357,6 +362,7 @@ function dovecot_markdown(md, opts) {
 		case 'event':
 		case 'man':
 		case 'setting':
+		case 'setting_text':
 		case 'variable':
 			return '</a></code>'