summary refs log tree commit diff
path: root/nixos/modules/services/misc
diff options
context:
space:
mode:
Diffstat (limited to 'nixos/modules/services/misc')
-rw-r--r--nixos/modules/services/misc/autorandr.nix4
-rw-r--r--nixos/modules/services/misc/docker-registry.nix4
-rw-r--r--nixos/modules/services/misc/fstrim.nix4
-rw-r--r--nixos/modules/services/misc/geoipupdate.nix4
-rw-r--r--nixos/modules/services/misc/gitea.nix4
-rw-r--r--nixos/modules/services/misc/gitit.nix104
-rw-r--r--nixos/modules/services/misc/gitlab.nix4
-rw-r--r--nixos/modules/services/misc/nix-daemon.nix22
-rw-r--r--nixos/modules/services/misc/nix-gc.nix8
-rw-r--r--nixos/modules/services/misc/nix-optimise.nix4
-rw-r--r--nixos/modules/services/misc/snapper.nix8
-rw-r--r--nixos/modules/services/misc/sourcehut/default.nix178
-rw-r--r--nixos/modules/services/misc/sourcehut/service.nix18
-rw-r--r--nixos/modules/services/misc/taskserver/default.nix16
14 files changed, 191 insertions, 191 deletions
diff --git a/nixos/modules/services/misc/autorandr.nix b/nixos/modules/services/misc/autorandr.nix
index 079b2b39579fa..06f24d7c7e75e 100644
--- a/nixos/modules/services/misc/autorandr.nix
+++ b/nixos/modules/services/misc/autorandr.nix
@@ -114,9 +114,9 @@ let
             [ 0.0 0.0 1.0 ]
           ]
         '';
-        description = ''
+        description = lib.mdDoc ''
           Refer to
-          <citerefentry><refentrytitle>xrandr</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+          {manpage}`xrandr(1)`
           for the documentation of the transform matrix.
         '';
       };
diff --git a/nixos/modules/services/misc/docker-registry.nix b/nixos/modules/services/misc/docker-registry.nix
index 734a7f6c87d89..7a9907fd35104 100644
--- a/nixos/modules/services/misc/docker-registry.nix
+++ b/nixos/modules/services/misc/docker-registry.nix
@@ -103,9 +103,9 @@ in {
     garbageCollectDates = mkOption {
       default = "daily";
       type = types.str;
-      description = ''
+      description = lib.mdDoc ''
         Specification (in the format described by
-        <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>) of the time at
+        {manpage}`systemd.time(7)`) of the time at
         which the garbage collect will occur.
       '';
     };
diff --git a/nixos/modules/services/misc/fstrim.nix b/nixos/modules/services/misc/fstrim.nix
index 6d57cef350d2d..83e7ca359b224 100644
--- a/nixos/modules/services/misc/fstrim.nix
+++ b/nixos/modules/services/misc/fstrim.nix
@@ -16,12 +16,12 @@ in {
       interval = mkOption {
         type = types.str;
         default = "weekly";
-        description = ''
+        description = lib.mdDoc ''
           How often we run fstrim. For most desktop and server systems
           a sufficient trimming frequency is once a week.
 
           The format is described in
-          <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+          {manpage}`systemd.time(7)`.
         '';
       };
     };
diff --git a/nixos/modules/services/misc/geoipupdate.nix b/nixos/modules/services/misc/geoipupdate.nix
index 68c6bf69a2258..c2007f25fb34c 100644
--- a/nixos/modules/services/misc/geoipupdate.nix
+++ b/nixos/modules/services/misc/geoipupdate.nix
@@ -19,10 +19,10 @@ in
       interval = lib.mkOption {
         type = lib.types.str;
         default = "weekly";
-        description = ''
+        description = lib.mdDoc ''
           Update the GeoIP databases at this time / interval.
           The format is described in
-          <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+          {manpage}`systemd.time(7)`.
         '';
       };
 
diff --git a/nixos/modules/services/misc/gitea.nix b/nixos/modules/services/misc/gitea.nix
index 91cf0bc6ed091..257143bfdc108 100644
--- a/nixos/modules/services/misc/gitea.nix
+++ b/nixos/modules/services/misc/gitea.nix
@@ -162,11 +162,11 @@ in
           type = types.str;
           default = "04:31";
           example = "hourly";
-          description = ''
+          description = lib.mdDoc ''
             Run a gitea dump at this interval. Runs by default at 04:31 every day.
 
             The format is described in
-            <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+            {manpage}`systemd.time(7)`.
           '';
         };
 
diff --git a/nixos/modules/services/misc/gitit.nix b/nixos/modules/services/misc/gitit.nix
index 223fa76d9106b..f00c03337d918 100644
--- a/nixos/modules/services/misc/gitit.nix
+++ b/nixos/modules/services/misc/gitit.nix
@@ -31,14 +31,14 @@ let
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = "Enable the gitit service.";
+        description = lib.mdDoc "Enable the gitit service.";
       };
 
       haskellPackages = mkOption {
         default = pkgs.haskellPackages;
         defaultText = literalExpression "pkgs.haskellPackages";
         example = literalExpression "pkgs.haskell.packages.ghc784";
-        description = "haskellPackages used to build gitit and plugins.";
+        description = lib.mdDoc "haskellPackages used to build gitit and plugins.";
       };
 
       extraPackages = mkOption {
@@ -59,31 +59,31 @@ let
       address = mkOption {
         type = types.str;
         default = "0.0.0.0";
-        description = "IP address on which the web server will listen.";
+        description = lib.mdDoc "IP address on which the web server will listen.";
       };
 
       port = mkOption {
         type = types.int;
         default = 5001;
-        description = "Port on which the web server will run.";
+        description = lib.mdDoc "Port on which the web server will run.";
       };
 
       wikiTitle = mkOption {
         type = types.str;
         default = "Gitit!";
-        description = "The wiki title.";
+        description = lib.mdDoc "The wiki title.";
       };
 
       repositoryType = mkOption {
         type = types.enum ["git" "darcs" "mercurial"];
         default = "git";
-        description = "Specifies the type of repository used for wiki content.";
+        description = lib.mdDoc "Specifies the type of repository used for wiki content.";
       };
 
       repositoryPath = mkOption {
         type = types.path;
         default = homeDir + "/wiki";
-        description = ''
+        description = lib.mdDoc ''
           Specifies the path of the repository directory. If it does not
           exist, gitit will create it on startup.
         '';
@@ -92,7 +92,7 @@ let
       requireAuthentication = mkOption {
         type = types.enum [ "none" "modify" "read" ];
         default = "modify";
-        description = ''
+        description = lib.mdDoc ''
           If 'none', login is never required, and pages can be edited
           anonymously.  If 'modify', login is required to modify the wiki
           (edit, add, delete pages, upload files).  If 'read', login is
@@ -103,7 +103,7 @@ let
       authenticationMethod = mkOption {
         type = types.enum [ "form" "http" "generic" "github" ];
         default = "form";
-        description = ''
+        description = lib.mdDoc ''
           'form' means that users will be logged in and registered using forms
           in the gitit web interface.  'http' means that gitit will assume that
           HTTP authentication is in place and take the logged in username from
@@ -121,7 +121,7 @@ let
       userFile = mkOption {
         type = types.path;
         default = homeDir + "/gitit-users";
-        description = ''
+        description = lib.mdDoc ''
           Specifies the path of the file containing user login information.  If
           it does not exist, gitit will create it (with an empty user list).
           This file is not used if 'http' is selected for
@@ -132,7 +132,7 @@ let
       sessionTimeout = mkOption {
         type = types.int;
         default = 60;
-        description = ''
+        description = lib.mdDoc ''
           Number of minutes of inactivity before a session expires.
         '';
       };
@@ -140,7 +140,7 @@ let
       staticDir = mkOption {
         type = types.path;
         default = gititShared + "/data/static";
-        description = ''
+        description = lib.mdDoc ''
           Specifies the path of the static directory (containing javascript,
           css, and images).  If it does not exist, gitit will create it and
           populate it with required scripts, stylesheets, and images.
@@ -150,7 +150,7 @@ let
       defaultPageType = mkOption {
         type = types.enum [ "markdown" "rst" "latex" "html" "markdown+lhs" "rst+lhs" "latex+lhs" ];
         default = "markdown";
-        description = ''
+        description = lib.mdDoc ''
           Specifies the type of markup used to interpret pages in the wiki.
           Possible values are markdown, rst, latex, html, markdown+lhs,
           rst+lhs, and latex+lhs. (the +lhs variants treat the input as
@@ -166,7 +166,7 @@ let
       math = mkOption {
         type = types.enum [ "mathml" "raw" "mathjax" "jsmath" "google" ];
         default = "mathml";
-        description = ''
+        description = lib.mdDoc ''
           Specifies how LaTeX math is to be displayed.  Possible values are
           mathml, raw, mathjax, jsmath, and google.  If mathml is selected,
           gitit will convert LaTeX math to MathML and link in a script,
@@ -186,7 +186,7 @@ let
       mathJaxScript = mkOption {
         type = types.str;
         default = "https://d3eoax9i5htok0.cloudfront.net/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML";
-        description = ''
+        description = lib.mdDoc ''
           Specifies the path to MathJax rendering script.  You might want to
           use your own MathJax script to render formulas without Internet
           connection or if you want to use some special LaTeX packages.  Note:
@@ -202,7 +202,7 @@ let
       showLhsBirdTracks = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Specifies whether to show Haskell code blocks in "bird style", with
           "> " at the beginning of each line.
         '';
@@ -224,7 +224,7 @@ let
       logFile = mkOption {
         type = types.path;
         default = homeDir + "/gitit.log";
-        description = ''
+        description = lib.mdDoc ''
           Specifies the path of gitit's log file.  If it does not exist, gitit
           will create it. The log is in Apache combined log format.
         '';
@@ -233,7 +233,7 @@ let
       logLevel = mkOption {
         type = types.enum [ "DEBUG" "INFO" "NOTICE" "WARNING" "ERROR" "CRITICAL" "ALERT" "EMERGENCY" ];
         default = "ERROR";
-        description = ''
+        description = lib.mdDoc ''
           Determines how much information is logged.  Possible values (from
           most to least verbose) are DEBUG, INFO, NOTICE, WARNING, ERROR,
           CRITICAL, ALERT, EMERGENCY.
@@ -243,7 +243,7 @@ let
       frontPage = mkOption {
         type = types.str;
         default = "Front Page";
-        description = ''
+        description = lib.mdDoc ''
           Specifies which wiki page is to be used as the wiki's front page.
           Gitit creates a default front page on startup, if one does not exist
           already.
@@ -253,7 +253,7 @@ let
       noDelete = mkOption {
         type = types.str;
         default = "Front Page, Help";
-        description = ''
+        description = lib.mdDoc ''
           Specifies pages that cannot be deleted through the web interface.
           (They can still be deleted directly using git or darcs.) A
           comma-separated list of page names.  Leave blank to allow every page
@@ -264,7 +264,7 @@ let
       noEdit = mkOption {
         type = types.str;
         default = "Help";
-        description = ''
+        description = lib.mdDoc ''
           Specifies pages that cannot be edited through the web interface.
           Leave blank to allow every page to be edited.
         '';
@@ -273,7 +273,7 @@ let
       defaultSummary = mkOption {
         type = types.str;
         default = "";
-        description = ''
+        description = lib.mdDoc ''
           Specifies text to be used in the change description if the author
           leaves the "description" field blank.  If default-summary is blank
           (the default), the author will be required to fill in the description
@@ -284,7 +284,7 @@ let
       tableOfContents = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Specifies whether to print a tables of contents (with links to
           sections) on each wiki page.
         '';
@@ -293,7 +293,7 @@ let
       plugins = mkOption {
         type = with types; listOf str;
         default = [ (gititShared + "/plugins/Dot.hs") ];
-        description = ''
+        description = lib.mdDoc ''
           Specifies a list of plugins to load. Plugins may be specified either
           by their path or by their module name. If the plugin name starts
           with Gitit.Plugin., gitit will assume that the plugin is an installed
@@ -304,7 +304,7 @@ let
       useCache = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Specifies whether to cache rendered pages.  Note that if use-feed is
           selected, feeds will be cached regardless of the value of use-cache.
         '';
@@ -313,13 +313,13 @@ let
       cacheDir = mkOption {
         type = types.path;
         default = homeDir + "/cache";
-        description = "Path where rendered pages will be cached.";
+        description = lib.mdDoc "Path where rendered pages will be cached.";
       };
 
       maxUploadSize = mkOption {
         type = types.str;
         default = "1000K";
-        description = ''
+        description = lib.mdDoc ''
           Specifies an upper limit on the size (in bytes) of files uploaded
           through the wiki's web interface.  To disable uploads, set this to
           0K.  This will result in the uploads link disappearing and the
@@ -330,19 +330,19 @@ let
       maxPageSize = mkOption {
         type = types.str;
         default = "1000K";
-        description = "Specifies an upper limit on the size (in bytes) of pages.";
+        description = lib.mdDoc "Specifies an upper limit on the size (in bytes) of pages.";
       };
 
       debugMode = mkOption {
         type = types.bool;
         default = false;
-        description = "Causes debug information to be logged while gitit is running.";
+        description = lib.mdDoc "Causes debug information to be logged while gitit is running.";
       };
 
       compressResponses = mkOption {
         type = types.bool;
         default = true;
-        description = "Specifies whether HTTP responses should be compressed.";
+        description = lib.mdDoc "Specifies whether HTTP responses should be compressed.";
       };
 
       mimeTypesFile = mkOption {
@@ -363,7 +363,7 @@ video/x-ms-wmx  wmx
       useReCaptcha = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           If true, causes gitit to use the reCAPTCHA service
           (http://recaptcha.net) to prevent bots from creating accounts.
         '';
@@ -372,7 +372,7 @@ video/x-ms-wmx  wmx
       reCaptchaPrivateKey = mkOption {
         type = with types; nullOr str;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Specifies the private key for the reCAPTCHA service.  To get
           these, you need to create an account at http://recaptcha.net.
         '';
@@ -381,7 +381,7 @@ video/x-ms-wmx  wmx
       reCaptchaPublicKey = mkOption {
         type = with types; nullOr str;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Specifies the public key for the reCAPTCHA service.  To get
           these, you need to create an account at http://recaptcha.net.
         '';
@@ -390,7 +390,7 @@ video/x-ms-wmx  wmx
       accessQuestion = mkOption {
         type = types.str;
         default = "What is the code given to you by Ms. X?";
-        description = ''
+        description = lib.mdDoc ''
           Specifies a question that users must answer when they attempt to
           create an account
         '';
@@ -399,7 +399,7 @@ video/x-ms-wmx  wmx
       accessQuestionAnswers = mkOption {
         type = types.str;
         default = "RED DOG, red dog";
-        description = ''
+        description = lib.mdDoc ''
           Specifies a question that users must answer when they attempt to
           create an account, along with a comma-separated list of acceptable
           answers.  This can be used to institute a rudimentary password for
@@ -413,7 +413,7 @@ video/x-ms-wmx  wmx
       rpxDomain = mkOption {
         type = with types; nullOr str;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Specifies the domain and key of your RPX account.  The domain is just
           the prefix of the complete RPX domain, so if your full domain is
           'https://foo.rpxnow.com/', use 'foo' as the value of rpx-domain.
@@ -423,13 +423,13 @@ video/x-ms-wmx  wmx
       rpxKey = mkOption {
         type = with types; nullOr str;
         default = null;
-        description = "RPX account access key.";
+        description = lib.mdDoc "RPX account access key.";
       };
 
       mailCommand = mkOption {
         type = types.str;
         default = "sendmail %s";
-        description = ''
+        description = lib.mdDoc ''
           Specifies the command to use to send notification emails.  '%s' will
           be replaced by the destination email address.  The body of the
           message will be read from stdin.  If this field is left blank,
@@ -451,7 +451,7 @@ video/x-ms-wmx  wmx
           >
           > Regards
         '';
-        description = ''
+        description = lib.mdDoc ''
           Gives the text of the message that will be sent to the user should
           she want to reset her password, or change other registration info.
           The lines must be indented, and must begin with '>'.  The initial
@@ -471,7 +471,7 @@ video/x-ms-wmx  wmx
       useFeed = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Specifies whether an ATOM feed should be enabled (for the site and
           for individual pages).
         '';
@@ -480,7 +480,7 @@ video/x-ms-wmx  wmx
       baseUrl = mkOption {
         type = with types; nullOr str;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           The base URL of the wiki, to be used in constructing feed IDs and RPX
           token_urls.  Set this if useFeed is false or authentication-method
           is 'rpx'.
@@ -502,19 +502,19 @@ video/x-ms-wmx  wmx
       feedDays = mkOption {
         type = types.int;
         default = 14;
-        description = "Number of days to be included in feeds.";
+        description = lib.mdDoc "Number of days to be included in feeds.";
       };
 
       feedRefreshTime = mkOption {
         type = types.int;
         default = 60;
-        description = "Number of minutes to cache feeds before refreshing.";
+        description = lib.mdDoc "Number of minutes to cache feeds before refreshing.";
       };
 
       pdfExport = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           If true, PDF will appear in export options. PDF will be created using
           pdflatex, which must be installed and in the path. Note that PDF
           exports create significant additional server load.
@@ -524,7 +524,7 @@ video/x-ms-wmx  wmx
       pandocUserData = mkOption {
         type = with types; nullOr path;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           If a directory is specified, this will be searched for pandoc
           customizations. These can include a templates/ directory for custom
           templates for various export formats, an S5 directory for custom S5
@@ -537,7 +537,7 @@ video/x-ms-wmx  wmx
       xssSanitize = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           If true, all HTML (including that produced by pandoc) is filtered
           through xss-sanitize.  Set to no only if you trust all of your users.
         '';
@@ -546,37 +546,37 @@ video/x-ms-wmx  wmx
       oauthClientId = mkOption {
         type = with types; nullOr str;
         default = null;
-        description = "OAuth client ID";
+        description = lib.mdDoc "OAuth client ID";
       };
 
       oauthClientSecret = mkOption {
         type = with types; nullOr str;
         default = null;
-        description = "OAuth client secret";
+        description = lib.mdDoc "OAuth client secret";
       };
 
       oauthCallback = mkOption {
         type = with types; nullOr str;
         default = null;
-        description = "OAuth callback URL";
+        description = lib.mdDoc "OAuth callback URL";
       };
 
       oauthAuthorizeEndpoint = mkOption {
         type = with types; nullOr str;
         default = null;
-        description = "OAuth authorize endpoint";
+        description = lib.mdDoc "OAuth authorize endpoint";
       };
 
       oauthAccessTokenEndpoint = mkOption {
         type = with types; nullOr str;
         default = null;
-        description = "OAuth access token endpoint";
+        description = lib.mdDoc "OAuth access token endpoint";
       };
 
       githubOrg = mkOption {
         type = with types; nullOr str;
         default = null;
-        description = "Github organization";
+        description = lib.mdDoc "Github organization";
       };
   };
 
diff --git a/nixos/modules/services/misc/gitlab.nix b/nixos/modules/services/misc/gitlab.nix
index 4e7ecfc039723..0bf2bca4a0b81 100644
--- a/nixos/modules/services/misc/gitlab.nix
+++ b/nixos/modules/services/misc/gitlab.nix
@@ -319,10 +319,10 @@ in {
         type = with types; either str (listOf str);
         default = [];
         example = "03:00";
-        description = ''
+        description = lib.mdDoc ''
           The time(s) to run automatic backup of GitLab
           state. Specified in systemd's time format; see
-          <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+          {manpage}`systemd.time(7)`.
         '';
       };
 
diff --git a/nixos/modules/services/misc/nix-daemon.nix b/nixos/modules/services/misc/nix-daemon.nix
index 9bac7a68ad28e..d299c4a0a8f18 100644
--- a/nixos/modules/services/misc/nix-daemon.nix
+++ b/nixos/modules/services/misc/nix-daemon.nix
@@ -155,29 +155,29 @@ in
         type = types.enum [ "other" "batch" "idle" ];
         default = "other";
         example = "batch";
-        description = ''
+        description = lib.mdDoc ''
           Nix daemon process CPU scheduling policy. This policy propagates to
-          build processes. <literal>other</literal> is the default scheduling
-          policy for regular tasks. The <literal>batch</literal> policy is
-          similar to <literal>other</literal>, but optimised for
-          non-interactive tasks. <literal>idle</literal> is for extremely
+          build processes. `other` is the default scheduling
+          policy for regular tasks. The `batch` policy is
+          similar to `other`, but optimised for
+          non-interactive tasks. `idle` is for extremely
           low-priority tasks that should only be run when no other task
           requires CPU time.
 
-          Please note that while using the <literal>idle</literal> policy may
+          Please note that while using the `idle` policy may
           greatly improve responsiveness of a system performing expensive
           builds, it may also slow down and potentially starve crucial
           configuration updates during load.
 
-          <literal>idle</literal> may therefore be a sensible policy for
+          `idle` may therefore be a sensible policy for
           systems that experience only intermittent phases of high CPU load,
           such as desktop or portable computers used interactively. Other
-          systems should use the <literal>other</literal> or
-          <literal>batch</literal> policy instead.
+          systems should use the `other` or
+          `batch` policy instead.
 
           For more fine-grained resource control, please refer to
-          <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> and adjust
-          <option>systemd.services.nix-daemon</option> directly.
+          {manpage}`systemd.resource-control(5)` and adjust
+          {option}`systemd.services.nix-daemon` directly.
       '';
       };
 
diff --git a/nixos/modules/services/misc/nix-gc.nix b/nixos/modules/services/misc/nix-gc.nix
index a03c0e8a9010b..97596d28cd89b 100644
--- a/nixos/modules/services/misc/nix-gc.nix
+++ b/nixos/modules/services/misc/nix-gc.nix
@@ -24,12 +24,12 @@ in
         type = types.str;
         default = "03:15";
         example = "weekly";
-        description = ''
+        description = lib.mdDoc ''
           How often or when garbage collection is performed. For most desktop and server systems
           a sufficient garbage collection is once a week.
 
           The format is described in
-          <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+          {manpage}`systemd.time(7)`.
         '';
       };
 
@@ -37,11 +37,11 @@ in
         default = "0";
         type = types.str;
         example = "45min";
-        description = ''
+        description = lib.mdDoc ''
           Add a randomized delay before each garbage collection.
           The delay will be chosen between zero and this value.
           This value must be a time span in the format specified by
-          <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+          {manpage}`systemd.time(7)`
         '';
       };
 
diff --git a/nixos/modules/services/misc/nix-optimise.nix b/nixos/modules/services/misc/nix-optimise.nix
index ebb0bc543efdc..db8148c060e71 100644
--- a/nixos/modules/services/misc/nix-optimise.nix
+++ b/nixos/modules/services/misc/nix-optimise.nix
@@ -23,9 +23,9 @@ in
       dates = mkOption {
         default = ["03:45"];
         type = types.listOf types.str;
-        description = ''
+        description = lib.mdDoc ''
           Specification (in the format described by
-          <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>) of the time at
+          {manpage}`systemd.time(7)`) of the time at
           which the optimiser will run.
         '';
       };
diff --git a/nixos/modules/services/misc/snapper.nix b/nixos/modules/services/misc/snapper.nix
index 0afd84a50824f..cfdfa2830ce95 100644
--- a/nixos/modules/services/misc/snapper.nix
+++ b/nixos/modules/services/misc/snapper.nix
@@ -20,22 +20,22 @@ in
     snapshotInterval = mkOption {
       type = types.str;
       default = "hourly";
-      description = ''
+      description = lib.mdDoc ''
         Snapshot interval.
 
         The format is described in
-        <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+        {manpage}`systemd.time(7)`.
       '';
     };
 
     cleanupInterval = mkOption {
       type = types.str;
       default = "1d";
-      description = ''
+      description = lib.mdDoc ''
         Cleanup interval.
 
         The format is described in
-        <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+        {manpage}`systemd.time(7)`.
       '';
     };
 
diff --git a/nixos/modules/services/misc/sourcehut/default.nix b/nixos/modules/services/misc/sourcehut/default.nix
index de04797a800c6..113c53f7395d7 100644
--- a/nixos/modules/services/misc/sourcehut/default.nix
+++ b/nixos/modules/services/misc/sourcehut/default.nix
@@ -47,33 +47,33 @@ let
     })));
   commonServiceSettings = srv: {
     origin = mkOption {
-      description = "URL ${srv}.sr.ht is being served at (protocol://domain)";
+      description = lib.mdDoc "URL ${srv}.sr.ht is being served at (protocol://domain)";
       type = types.str;
       default = "https://${srv}.${domain}";
       defaultText = "https://${srv}.example.com";
     };
     debug-host = mkOption {
-      description = "Address to bind the debug server to.";
+      description = lib.mdDoc "Address to bind the debug server to.";
       type = with types; nullOr str;
       default = null;
     };
     debug-port = mkOption {
-      description = "Port to bind the debug server to.";
+      description = lib.mdDoc "Port to bind the debug server to.";
       type = with types; nullOr str;
       default = null;
     };
     connection-string = mkOption {
-      description = "SQLAlchemy connection string for the database.";
+      description = lib.mdDoc "SQLAlchemy connection string for the database.";
       type = types.str;
       default = "postgresql:///localhost?user=${srv}srht&host=/run/postgresql";
     };
     migrate-on-upgrade = mkEnableOption "automatic migrations on package upgrade" // { default = true; };
     oauth-client-id = mkOption {
-      description = "${srv}.sr.ht's OAuth client id for meta.sr.ht.";
+      description = lib.mdDoc "${srv}.sr.ht's OAuth client id for meta.sr.ht.";
       type = types.str;
     };
     oauth-client-secret = mkOption {
-      description = "${srv}.sr.ht's OAuth client secret for meta.sr.ht.";
+      description = lib.mdDoc "${srv}.sr.ht's OAuth client secret for meta.sr.ht.";
       type = types.path;
       apply = s: "<" + toString s;
     };
@@ -117,7 +117,7 @@ in
       type = with types; listOf (enum
         [ "builds" "dispatch" "git" "hg" "hub" "lists" "man" "meta" "pages" "paste" "todo" ]);
       defaultText = "locally enabled services";
-      description = ''
+      description = lib.mdDoc ''
         Services that may be displayed as links in the title bar of the Web interface.
       '';
     };
@@ -125,7 +125,7 @@ in
     listenAddress = mkOption {
       type = types.str;
       default = "localhost";
-      description = "Address to bind to.";
+      description = lib.mdDoc "Address to bind to.";
     };
 
     python = mkOption {
@@ -147,7 +147,7 @@ in
       virtualHost = mkOption {
         type = types.attrs;
         default = {};
-        description = "Virtual-host configuration merged with all Sourcehut's virtual-hosts.";
+        description = lib.mdDoc "Virtual-host configuration merged with all Sourcehut's virtual-hosts.";
       };
     };
 
@@ -168,48 +168,48 @@ in
         freeformType = settingsFormat.type;
         options."sr.ht" = {
           global-domain = mkOption {
-            description = "Global domain name.";
+            description = lib.mdDoc "Global domain name.";
             type = types.str;
             example = "example.com";
           };
           environment = mkOption {
-            description = "Values other than \"production\" adds a banner to each page.";
+            description = lib.mdDoc "Values other than \"production\" adds a banner to each page.";
             type = types.enum [ "development" "production" ];
             default = "development";
           };
           network-key = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               An absolute file path (which should be outside the Nix-store)
-              to a secret key to encrypt internal messages with. Use <literal>srht-keygen network</literal> to
+              to a secret key to encrypt internal messages with. Use `srht-keygen network` to
               generate this key. It must be consistent between all services and nodes.
             '';
             type = types.path;
             apply = s: "<" + toString s;
           };
           owner-email = mkOption {
-            description = "Owner's email.";
+            description = lib.mdDoc "Owner's email.";
             type = types.str;
             default = "contact@example.com";
           };
           owner-name = mkOption {
-            description = "Owner's name.";
+            description = lib.mdDoc "Owner's name.";
             type = types.str;
             default = "John Doe";
           };
           site-blurb = mkOption {
-            description = "Blurb for your site.";
+            description = lib.mdDoc "Blurb for your site.";
             type = types.str;
             default = "the hacker's forge";
           };
           site-info = mkOption {
-            description = "The top-level info page for your site.";
+            description = lib.mdDoc "The top-level info page for your site.";
             type = types.str;
             default = "https://sourcehut.org";
           };
           service-key = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               An absolute file path (which should be outside the Nix-store)
-              to a key used for encrypting session cookies. Use <literal>srht-keygen service</literal> to
+              to a key used for encrypting session cookies. Use `srht-keygen service` to
               generate the service key. This must be shared between each node of the same
               service (e.g. git1.sr.ht and git2.sr.ht), but different services may use
               different keys. If you configure all of your services with the same
@@ -219,12 +219,12 @@ in
             apply = s: "<" + toString s;
           };
           site-name = mkOption {
-            description = "The name of your network of sr.ht-based sites.";
+            description = lib.mdDoc "The name of your network of sr.ht-based sites.";
             type = types.str;
             default = "sourcehut";
           };
           source-url = mkOption {
-            description = "The source code for your fork of sr.ht.";
+            description = lib.mdDoc "The source code for your fork of sr.ht.";
             type = types.str;
             default = "https://git.sr.ht/~sircmpwn/srht";
           };
@@ -232,7 +232,7 @@ in
         options.mail = {
           smtp-host = mkOptionNullOrStr "Outgoing SMTP host.";
           smtp-port = mkOption {
-            description = "Outgoing SMTP port.";
+            description = lib.mdDoc "Outgoing SMTP port.";
             type = with types; nullOr port;
             default = null;
           };
@@ -240,44 +240,44 @@ in
           smtp-password = mkOptionNullOrStr "Outgoing SMTP password.";
           smtp-from = mkOption {
             type = types.str;
-            description = "Outgoing SMTP FROM.";
+            description = lib.mdDoc "Outgoing SMTP FROM.";
           };
           error-to = mkOptionNullOrStr "Address receiving application exceptions";
           error-from = mkOptionNullOrStr "Address sending application exceptions";
           pgp-privkey = mkOption {
             type = types.str;
-            description = ''
+            description = lib.mdDoc ''
               An absolute file path (which should be outside the Nix-store)
               to an OpenPGP private key.
 
               Your PGP key information (DO NOT mix up pub and priv here)
               You must remove the password from your secret key, if present.
-              You can do this with <literal>gpg --edit-key [key-id]</literal>,
-              then use the <literal>passwd</literal> command and do not enter a new password.
+              You can do this with `gpg --edit-key [key-id]`,
+              then use the `passwd` command and do not enter a new password.
             '';
           };
           pgp-pubkey = mkOption {
             type = with types; either path str;
-            description = "OpenPGP public key.";
+            description = lib.mdDoc "OpenPGP public key.";
           };
           pgp-key-id = mkOption {
             type = types.str;
-            description = "OpenPGP key identifier.";
+            description = lib.mdDoc "OpenPGP key identifier.";
           };
         };
         options.objects = {
           s3-upstream = mkOption {
-            description = "Configure the S3-compatible object storage service.";
+            description = lib.mdDoc "Configure the S3-compatible object storage service.";
             type = with types; nullOr str;
             default = null;
           };
           s3-access-key = mkOption {
-            description = "Access key to the S3-compatible object storage service";
+            description = lib.mdDoc "Access key to the S3-compatible object storage service";
             type = with types; nullOr str;
             default = null;
           };
           s3-secret-key = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               An absolute file path (which should be outside the Nix-store)
               to the secret key of the S3-compatible object storage service.
             '';
@@ -288,13 +288,13 @@ in
         };
         options.webhooks = {
           private-key = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               An absolute file path (which should be outside the Nix-store)
               to a base64-encoded Ed25519 key for signing webhook payloads.
               This should be consistent for all *.sr.ht sites,
               as this key will be used to verify signatures
               from other sites in your network.
-              Use the <literal>srht-keygen webhook</literal> command to generate a key.
+              Use the `srht-keygen webhook` command to generate a key.
             '';
             type = types.path;
             apply = s: "<" + toString s;
@@ -311,17 +311,17 @@ in
           enabled = mkEnableOption "GitLab integration";
           canonical-upstream = mkOption {
             type = types.str;
-            description = "Canonical upstream.";
+            description = lib.mdDoc "Canonical upstream.";
             default = "gitlab.com";
           };
           repo-cache = mkOption {
             type = types.str;
-            description = "Repository cache directory.";
+            description = lib.mdDoc "Repository cache directory.";
             default = "./repo-cache";
           };
           "gitlab.com" = mkOption {
             type = with types; nullOr str;
-            description = "GitLab id and secret.";
+            description = lib.mdDoc "GitLab id and secret.";
             default = null;
             example = "GitLab:application id:secret";
           };
@@ -330,17 +330,17 @@ in
         options."builds.sr.ht" = commonServiceSettings "builds" // {
           allow-free = mkEnableOption "nonpaying users to submit builds";
           redis = mkOption {
-            description = "The Redis connection used for the Celery worker.";
+            description = lib.mdDoc "The Redis connection used for the Celery worker.";
             type = types.str;
             default = "redis+socket:///run/redis-sourcehut-buildsrht/redis.sock?virtual_host=2";
           };
           shell = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               Scripts used to launch on SSH connection.
-              <literal>/usr/bin/master-shell</literal> on master,
-              <literal>/usr/bin/runner-shell</literal> on runner.
+              `/usr/bin/master-shell` on master,
+              `/usr/bin/runner-shell` on runner.
               If master and worker are on the same system
-              set to <literal>/usr/bin/runner-shell</literal>.
+              set to `/usr/bin/runner-shell`.
             '';
             type = types.enum ["/usr/bin/master-shell" "/usr/bin/runner-shell"];
             default = "/usr/bin/master-shell";
@@ -348,19 +348,19 @@ in
         };
         options."builds.sr.ht::worker" = {
           bind-address = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               HTTP bind address for serving local build information/monitoring.
             '';
             type = types.str;
             default = "localhost:8080";
           };
           buildlogs = mkOption {
-            description = "Path to write build logs.";
+            description = lib.mdDoc "Path to write build logs.";
             type = types.str;
             default = "/var/log/sourcehut/buildsrht-worker";
           };
           name = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               Listening address and listening port
               of the build runner (with HTTP port if not 80).
             '';
@@ -368,9 +368,9 @@ in
             default = "localhost:5020";
           };
           timeout = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               Max build duration.
-              See <link xlink:href="https://golang.org/pkg/time/#ParseDuration"/>.
+              See <https://golang.org/pkg/time/#ParseDuration>.
             '';
             type = types.str;
             default = "3m";
@@ -379,12 +379,12 @@ in
 
         options."git.sr.ht" = commonServiceSettings "git" // {
           outgoing-domain = mkOption {
-            description = "Outgoing domain.";
+            description = lib.mdDoc "Outgoing domain.";
             type = types.str;
             default = "https://git.localhost.localdomain";
           };
           post-update-script = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               A post-update script which is installed in every git repo.
               This setting is propagated to newer and existing repositories.
             '';
@@ -393,7 +393,7 @@ in
             defaultText = "\${pkgs.sourcehut.gitsrht}/bin/gitsrht-update-hook";
           };
           repos = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               Path to git repositories on disk.
               If changing the default, you must ensure that
               the gitsrht's user as read and write access to it.
@@ -402,18 +402,18 @@ in
             default = "/var/lib/sourcehut/gitsrht/repos";
           };
           webhooks = mkOption {
-            description = "The Redis connection used for the webhooks worker.";
+            description = lib.mdDoc "The Redis connection used for the webhooks worker.";
             type = types.str;
             default = "redis+socket:///run/redis-sourcehut-gitsrht/redis.sock?virtual_host=1";
           };
         };
         options."git.sr.ht::api" = {
           internal-ipnet = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               Set of IP subnets which are permitted to utilize internal API
               authentication. This should be limited to the subnets
               from which your *.sr.ht services are running.
-              See <xref linkend="opt-services.sourcehut.listenAddress"/>.
+              See [](#opt-services.sourcehut.listenAddress).
             '';
             type = with types; listOf str;
             default = [ "127.0.0.0/8" "::1/128" ];
@@ -422,7 +422,7 @@ in
 
         options."hg.sr.ht" = commonServiceSettings "hg" // {
           changegroup-script = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               A changegroup script which is installed in every mercurial repo.
               This setting is propagated to newer and existing repositories.
             '';
@@ -431,7 +431,7 @@ in
             defaultText = "\${cfg.python}/bin/hgsrht-hook-changegroup";
           };
           repos = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               Path to mercurial repositories on disk.
               If changing the default, you must ensure that
               the hgsrht's user as read and write access to it.
@@ -444,18 +444,18 @@ in
             (defaults to where the hgsrht code is)
           '';
           clone_bundle_threshold = mkOption {
-            description = ".hg/store size (in MB) past which the nightly job generates clone bundles.";
+            description = lib.mdDoc ".hg/store size (in MB) past which the nightly job generates clone bundles.";
             type = types.ints.unsigned;
             default = 50;
           };
           hg_ssh = mkOption {
-            description = "Path to hg-ssh (if not in $PATH).";
+            description = lib.mdDoc "Path to hg-ssh (if not in $PATH).";
             type = types.str;
             default = "${pkgs.mercurial}/bin/hg-ssh";
             defaultText = "\${pkgs.mercurial}/bin/hg-ssh";
           };
           webhooks = mkOption {
-            description = "The Redis connection used for the webhooks worker.";
+            description = lib.mdDoc "The Redis connection used for the webhooks worker.";
             type = types.str;
             default = "redis+socket:///run/redis-sourcehut-hgsrht/redis.sock?virtual_host=1";
           };
@@ -467,29 +467,29 @@ in
         options."lists.sr.ht" = commonServiceSettings "lists" // {
           allow-new-lists = mkEnableOption "Allow creation of new lists.";
           notify-from = mkOption {
-            description = "Outgoing email for notifications generated by users.";
+            description = lib.mdDoc "Outgoing email for notifications generated by users.";
             type = types.str;
             default = "lists-notify@localhost.localdomain";
           };
           posting-domain = mkOption {
-            description = "Posting domain.";
+            description = lib.mdDoc "Posting domain.";
             type = types.str;
             default = "lists.localhost.localdomain";
           };
           redis = mkOption {
-            description = "The Redis connection used for the Celery worker.";
+            description = lib.mdDoc "The Redis connection used for the Celery worker.";
             type = types.str;
             default = "redis+socket:///run/redis-sourcehut-listssrht/redis.sock?virtual_host=2";
           };
           webhooks = mkOption {
-            description = "The Redis connection used for the webhooks worker.";
+            description = lib.mdDoc "The Redis connection used for the webhooks worker.";
             type = types.str;
             default = "redis+socket:///run/redis-sourcehut-listssrht/redis.sock?virtual_host=1";
           };
         };
         options."lists.sr.ht::worker" = {
           reject-mimetypes = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               Comma-delimited list of Content-Types to reject. Messages with Content-Types
               included in this list are rejected. Multipart messages are always supported,
               and each part is checked against this list.
@@ -500,12 +500,12 @@ in
             default = ["text/html"];
           };
           reject-url = mkOption {
-            description = "Reject URL.";
+            description = lib.mdDoc "Reject URL.";
             type = types.str;
             default = "https://man.sr.ht/lists.sr.ht/etiquette.md";
           };
           sock = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               Path for the lmtp daemon's unix socket. Direct incoming mail to this socket.
               Alternatively, specify IP:PORT and an SMTP server will be run instead.
             '';
@@ -513,7 +513,7 @@ in
             default = "/tmp/lists.sr.ht-lmtp.sock";
           };
           sock-group = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               The lmtp daemon will make the unix socket group-read/write
               for users in this group.
             '';
@@ -529,13 +529,13 @@ in
           removeAttrs (commonServiceSettings "meta")
             ["oauth-client-id" "oauth-client-secret"] // {
           api-origin = mkOption {
-            description = "Origin URL for API, 100 more than web.";
+            description = lib.mdDoc "Origin URL for API, 100 more than web.";
             type = types.str;
             default = "http://${cfg.listenAddress}:${toString (cfg.meta.port + 100)}";
             defaultText = ''http://<xref linkend="opt-services.sourcehut.listenAddress"/>:''${toString (<xref linkend="opt-services.sourcehut.meta.port"/> + 100)}'';
           };
           webhooks = mkOption {
-            description = "The Redis connection used for the webhooks worker.";
+            description = lib.mdDoc "The Redis connection used for the webhooks worker.";
             type = types.str;
             default = "redis+socket:///run/redis-sourcehut-metasrht/redis.sock?virtual_host=1";
           };
@@ -543,18 +543,18 @@ in
         };
         options."meta.sr.ht::api" = {
           internal-ipnet = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               Set of IP subnets which are permitted to utilize internal API
               authentication. This should be limited to the subnets
               from which your *.sr.ht services are running.
-              See <xref linkend="opt-services.sourcehut.listenAddress"/>.
+              See [](#opt-services.sourcehut.listenAddress).
             '';
             type = with types; listOf str;
             default = [ "127.0.0.0/8" "::1/128" ];
           };
         };
         options."meta.sr.ht::aliases" = mkOption {
-          description = "Aliases for the client IDs of commonly used OAuth clients.";
+          description = lib.mdDoc "Aliases for the client IDs of commonly used OAuth clients.";
           type = with types; attrsOf int;
           default = {};
           example = { "git.sr.ht" = 12345; };
@@ -572,12 +572,12 @@ in
         options."meta.sr.ht::settings" = {
           registration = mkEnableOption "public registration";
           onboarding-redirect = mkOption {
-            description = "Where to redirect new users upon registration.";
+            description = lib.mdDoc "Where to redirect new users upon registration.";
             type = types.str;
             default = "https://meta.localhost.localdomain";
           };
           user-invites = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               How many invites each user is issued upon registration
               (only applicable if open registration is disabled).
             '';
@@ -588,7 +588,7 @@ in
 
         options."pages.sr.ht" = commonServiceSettings "pages" // {
           gemini-certs = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               An absolute file path (which should be outside the Nix-store)
               to Gemini certificates.
             '';
@@ -596,7 +596,7 @@ in
             default = null;
           };
           max-site-size = mkOption {
-            description = "Maximum size of any given site (post-gunzip), in MiB.";
+            description = lib.mdDoc "Maximum size of any given site (post-gunzip), in MiB.";
             type = types.int;
             default = 1024;
           };
@@ -611,11 +611,11 @@ in
         };
         options."pages.sr.ht::api" = {
           internal-ipnet = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               Set of IP subnets which are permitted to utilize internal API
               authentication. This should be limited to the subnets
               from which your *.sr.ht services are running.
-              See <xref linkend="opt-services.sourcehut.listenAddress"/>.
+              See [](#opt-services.sourcehut.listenAddress).
             '';
             type = with types; listOf str;
             default = [ "127.0.0.0/8" "::1/128" ];
@@ -627,24 +627,24 @@ in
 
         options."todo.sr.ht" = commonServiceSettings "todo" // {
           notify-from = mkOption {
-            description = "Outgoing email for notifications generated by users.";
+            description = lib.mdDoc "Outgoing email for notifications generated by users.";
             type = types.str;
             default = "todo-notify@localhost.localdomain";
           };
           webhooks = mkOption {
-            description = "The Redis connection used for the webhooks worker.";
+            description = lib.mdDoc "The Redis connection used for the webhooks worker.";
             type = types.str;
             default = "redis+socket:///run/redis-sourcehut-todosrht/redis.sock?virtual_host=1";
           };
         };
         options."todo.sr.ht::mail" = {
           posting-domain = mkOption {
-            description = "Posting domain.";
+            description = lib.mdDoc "Posting domain.";
             type = types.str;
             default = "todo.localhost.localdomain";
           };
           sock = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               Path for the lmtp daemon's unix socket. Direct incoming mail to this socket.
               Alternatively, specify IP:PORT and an SMTP server will be run instead.
             '';
@@ -652,7 +652,7 @@ in
             default = "/tmp/todo.sr.ht-lmtp.sock";
           };
           sock-group = mkOption {
-            description = ''
+            description = lib.mdDoc ''
               The lmtp daemon will make the unix socket group-read/write
               for users in this group.
             '';
@@ -662,7 +662,7 @@ in
         };
       };
       default = { };
-      description = ''
+      description = lib.mdDoc ''
         The configuration for the sourcehut network.
       '';
     };
@@ -698,7 +698,7 @@ in
             nixos.unstable.x86_64 = image_from_nixpkgs;
           }
         )'';
-        description = ''
+        description = lib.mdDoc ''
           Images for builds.sr.ht. Each package should be distro.release.arch and point to a /nix/store/package/root.img.qcow2.
         '';
       };
@@ -710,12 +710,12 @@ in
         default = pkgs.git;
         defaultText = literalExpression "pkgs.git";
         example = literalExpression "pkgs.gitFull";
-        description = ''
+        description = lib.mdDoc ''
           Git package for git.sr.ht. This can help silence collisions.
         '';
       };
       fcgiwrap.preforkProcess = mkOption {
-        description = "Number of fcgiwrap processes to prefork.";
+        description = lib.mdDoc "Number of fcgiwrap processes to prefork.";
         type = types.int;
         default = 4;
       };
@@ -726,14 +726,14 @@ in
         type = types.package;
         default = pkgs.mercurial;
         defaultText = literalExpression "pkgs.mercurial";
-        description = ''
+        description = lib.mdDoc ''
           Mercurial package for hg.sr.ht. This can help silence collisions.
         '';
       };
       cloneBundles = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Generate clonebundles (which require more disk space but dramatically speed up cloning large repositories).
         '';
       };
@@ -744,12 +744,12 @@ in
         extraArgs = mkOption {
           type = with types; listOf str;
           default = [ "--loglevel DEBUG" "--pool eventlet" "--without-heartbeat" ];
-          description = "Extra arguments passed to the Celery responsible for processing mails.";
+          description = lib.mdDoc "Extra arguments passed to the Celery responsible for processing mails.";
         };
         celeryConfig = mkOption {
           type = types.lines;
           default = "";
-          description = "Content of the <literal>celeryconfig.py</literal> used by the Celery of <literal>listssrht-process</literal>.";
+          description = lib.mdDoc "Content of the `celeryconfig.py` used by the Celery of `listssrht-process`.";
         };
       };
     };
diff --git a/nixos/modules/services/misc/sourcehut/service.nix b/nixos/modules/services/misc/sourcehut/service.nix
index 4ecc7a7266907..243a9cef5901d 100644
--- a/nixos/modules/services/misc/sourcehut/service.nix
+++ b/nixos/modules/services/misc/sourcehut/service.nix
@@ -122,7 +122,7 @@ in
     user = mkOption {
       type = types.str;
       default = srvsrht;
-      description = ''
+      description = lib.mdDoc ''
         User for ${srv}.sr.ht.
       '';
     };
@@ -130,7 +130,7 @@ in
     group = mkOption {
       type = types.str;
       default = srvsrht;
-      description = ''
+      description = lib.mdDoc ''
         Group for ${srv}.sr.ht.
         Membership grants access to the Git/Mercurial repositories by default,
         but not to the config.ini file (where secrets are).
@@ -140,7 +140,7 @@ in
     port = mkOption {
       type = types.port;
       default = port;
-      description = ''
+      description = lib.mdDoc ''
         Port on which the "${srv}" backend should listen.
       '';
     };
@@ -150,7 +150,7 @@ in
         type = types.str;
         default = "unix:///run/redis-sourcehut-${srvsrht}/redis.sock?db=0";
         example = "redis://shared.wireguard:6379/0";
-        description = ''
+        description = lib.mdDoc ''
           The redis host URL. This is used for caching and temporary storage, and must
           be shared between nodes (e.g. git1.sr.ht and git2.sr.ht), but need not be
           shared between services. It may be shared between services, however, with no
@@ -163,9 +163,9 @@ in
       database = mkOption {
         type = types.str;
         default = "${srv}.sr.ht";
-        description = ''
+        description = lib.mdDoc ''
           PostgreSQL database name for the ${srv}.sr.ht service,
-          used if <xref linkend="opt-services.sourcehut.postgresql.enable"/> is <literal>true</literal>.
+          used if [](#opt-services.sourcehut.postgresql.enable) is `true`.
         '';
       };
     };
@@ -174,7 +174,7 @@ in
       extraArgs = mkOption {
         type = with types; listOf str;
         default = ["--timeout 120" "--workers 1" "--log-level=info"];
-        description = "Extra arguments passed to Gunicorn.";
+        description = lib.mdDoc "Extra arguments passed to Gunicorn.";
       };
     };
   } // optionalAttrs webhooks {
@@ -182,12 +182,12 @@ in
       extraArgs = mkOption {
         type = with types; listOf str;
         default = ["--loglevel DEBUG" "--pool eventlet" "--without-heartbeat"];
-        description = "Extra arguments passed to the Celery responsible for webhooks.";
+        description = lib.mdDoc "Extra arguments passed to the Celery responsible for webhooks.";
       };
       celeryConfig = mkOption {
         type = types.lines;
         default = "";
-        description = "Content of the <literal>celeryconfig.py</literal> used by the Celery responsible for webhooks.";
+        description = lib.mdDoc "Content of the `celeryconfig.py` used by the Celery responsible for webhooks.";
       };
     };
   };
diff --git a/nixos/modules/services/misc/taskserver/default.nix b/nixos/modules/services/misc/taskserver/default.nix
index c8a2c21b9ecfd..ad4ab93a872a1 100644
--- a/nixos/modules/services/misc/taskserver/default.nix
+++ b/nixos/modules/services/misc/taskserver/default.nix
@@ -227,8 +227,8 @@ in {
       queueSize = mkOption {
         type = types.int;
         default = 10;
-        description = ''
-          Size of the connection backlog, see <citerefentry><refentrytitle>listen</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
+        description = lib.mdDoc ''
+          Size of the connection backlog, see {manpage}`listen(2)`.
         '';
       };
 
@@ -321,16 +321,16 @@ in {
       config = mkOption {
         type = types.attrs;
         example.client.cert = "/tmp/debugging.cert";
-        description = ''
+        description = lib.mdDoc ''
           Configuration options to pass to Taskserver.
 
           The options here are the same as described in
-          <citerefentry><refentrytitle>taskdrc</refentrytitle><manvolnum>5</manvolnum></citerefentry>, but with one difference:
+          {manpage}`taskdrc(5)`, but with one difference:
 
-          The <literal>server</literal> option is
-          <literal>server.listen</literal> here, because the
-          <literal>server</literal> option would collide with other options
-          like <literal>server.cert</literal> and we would run in a type error
+          The `server` option is
+          `server.listen` here, because the
+          `server` option would collide with other options
+          like `server.cert` and we would run in a type error
           (attribute set versus string).
 
           Nix types like integers or booleans are automatically converted to
generated by cgit-pink 1.4.1 (git 2.36.1) at 2024-08-30 01:06:05 +0000