nixos/prosody: convert manual chapter to MD

3 files changed, 143 insertions, 67 deletions

diff --git a/nixos/modules/services/networking/prosody.md b/nixos/modules/services/networking/prosody.md
new file mode 100644
index 00000000000..2da2c242a98
--- /dev/null
+++ b/nixos/modules/services/networking/prosody.md
@@ -0,0 +1,72 @@
+# Prosody {#module-services-prosody}
+
+[Prosody](https://prosody.im/) is an open-source, modern XMPP server.
+
+## Basic usage {#module-services-prosody-basic-usage}
+
+A common struggle for most XMPP newcomers is to find the right set
+of XMPP Extensions (XEPs) to setup. Forget to activate a few of
+those and your XMPP experience might turn into a nightmare!
+
+The XMPP community tackles this problem by creating a meta-XEP
+listing a decent set of XEPs you should implement. This meta-XEP
+is issued every year, the 2020 edition being
+[XEP-0423](https://xmpp.org/extensions/xep-0423.html).
+
+The NixOS Prosody module will implement most of these recommendend XEPs out of
+the box. That being said, two components still require some
+manual configuration: the
+[Multi User Chat (MUC)](https://xmpp.org/extensions/xep-0045.html)
+and the [HTTP File Upload](https://xmpp.org/extensions/xep-0363.html) ones.
+You'll need to create a DNS subdomain for each of those. The current convention is to name your
+MUC endpoint `conference.example.org` and your HTTP upload domain `upload.example.org`.
+
+A good configuration to start with, including a
+[Multi User Chat (MUC)](https://xmpp.org/extensions/xep-0045.html)
+endpoint as well as a [HTTP File Upload](https://xmpp.org/extensions/xep-0363.html)
+endpoint will look like this:
+```
+services.prosody = {
+  enable = true;
+  admins = [ "root@example.org" ];
+  ssl.cert = "/var/lib/acme/example.org/fullchain.pem";
+  ssl.key = "/var/lib/acme/example.org/key.pem";
+  virtualHosts."example.org" = {
+      enabled = true;
+      domain = "example.org";
+      ssl.cert = "/var/lib/acme/example.org/fullchain.pem";
+      ssl.key = "/var/lib/acme/example.org/key.pem";
+  };
+  muc = [ {
+      domain = "conference.example.org";
+  } ];
+  uploadHttp = {
+      domain = "upload.example.org";
+  };
+};
+```
+
+## Let's Encrypt Configuration {#module-services-prosody-letsencrypt}
+
+As you can see in the code snippet from the
+[previous section](#module-services-prosody-basic-usage),
+you'll need a single TLS certificate covering your main endpoint,
+the MUC one as well as the HTTP Upload one. We can generate such a
+certificate by leveraging the ACME
+[extraDomainNames](#opt-security.acme.certs._name_.extraDomainNames) module option.
+
+Provided the setup detailed in the previous section, you'll need the following acme configuration to generate
+a TLS certificate for the three endponits:
+```
+security.acme = {
+  email = "root@example.org";
+  acceptTerms = true;
+  certs = {
+    "example.org" = {
+      webroot = "/var/www/example.org";
+      email = "root@example.org";
+      extraDomainNames = [ "conference.example.org" "upload.example.org" ];
+    };
+  };
+};
+```
diff --git a/nixos/modules/services/networking/prosody.nix b/nixos/modules/services/networking/prosody.nix
index 342638f93ba..07d3afa73b1 100644
--- a/nixos/modules/services/networking/prosody.nix
+++ b/nixos/modules/services/networking/prosody.nix
@@ -904,5 +904,8 @@ in
     };
 
   };
+
+  # Don't edit the docbook xml directly, edit the md and generate it:
+  # `pandoc prosody.md -t docbook --top-level-division=chapter --extract-media=media -f markdown-smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > prosody.xml`
   meta.doc = ./prosody.xml;
 }
diff --git a/nixos/modules/services/networking/prosody.xml b/nixos/modules/services/networking/prosody.xml
index 89b0377d97d..32b5dc8c129 100644
--- a/nixos/modules/services/networking/prosody.xml
+++ b/nixos/modules/services/networking/prosody.xml
@@ -1,89 +1,90 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         version="5.0"
-         xml:id="module-services-prosody">
- <title>Prosody</title>
- <para>
-  <link xlink:href="https://prosody.im/">Prosody</link> is an open-source, modern XMPP server.
- </para>
- <section xml:id="module-services-prosody-basic-usage">
-  <title>Basic usage</title>
-
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-prosody">
+  <title>Prosody</title>
   <para>
-    A common struggle for most XMPP newcomers is to find the right set
-    of XMPP Extensions (XEPs) to setup. Forget to activate a few of
-    those and your XMPP experience might turn into a nightmare!
+    <link xlink:href="https://prosody.im/">Prosody</link> is an
+    open-source, modern XMPP server.
   </para>
-
-  <para>
-    The XMPP community tackles this problem by creating a meta-XEP
-    listing a decent set of XEPs you should implement. This meta-XEP
-    is issued every year, the 2020 edition being
-    <link xlink:href="https://xmpp.org/extensions/xep-0423.html">XEP-0423</link>.
-  </para>
-  <para>
-    The NixOS Prosody module will implement most of these recommendend XEPs out of
-    the box. That being said, two components still require some
-    manual configuration: the
-    <link xlink:href="https://xmpp.org/extensions/xep-0045.html">Multi User Chat (MUC)</link>
-    and the <link xlink:href="https://xmpp.org/extensions/xep-0363.html">HTTP File Upload</link> ones.
-    You'll need to create a DNS subdomain for each of those. The current convention is to name your
-    MUC endpoint <literal>conference.example.org</literal> and your HTTP upload domain <literal>upload.example.org</literal>.
-  </para>
-  <para>
-    A good configuration to start with, including a
-    <link xlink:href="https://xmpp.org/extensions/xep-0045.html">Multi User Chat (MUC)</link>
-    endpoint as well as a <link xlink:href="https://xmpp.org/extensions/xep-0363.html">HTTP File Upload</link>
-    endpoint will look like this:
+  <section xml:id="module-services-prosody-basic-usage">
+    <title>Basic usage</title>
+    <para>
+      A common struggle for most XMPP newcomers is to find the right set
+      of XMPP Extensions (XEPs) to setup. Forget to activate a few of
+      those and your XMPP experience might turn into a nightmare!
+    </para>
+    <para>
+      The XMPP community tackles this problem by creating a meta-XEP
+      listing a decent set of XEPs you should implement. This meta-XEP
+      is issued every year, the 2020 edition being
+      <link xlink:href="https://xmpp.org/extensions/xep-0423.html">XEP-0423</link>.
+    </para>
+    <para>
+      The NixOS Prosody module will implement most of these recommendend
+      XEPs out of the box. That being said, two components still require
+      some manual configuration: the
+      <link xlink:href="https://xmpp.org/extensions/xep-0045.html">Multi
+      User Chat (MUC)</link> and the
+      <link xlink:href="https://xmpp.org/extensions/xep-0363.html">HTTP
+      File Upload</link> ones. You'll need to create a DNS subdomain for
+      each of those. The current convention is to name your MUC endpoint
+      <literal>conference.example.org</literal> and your HTTP upload
+      domain <literal>upload.example.org</literal>.
+    </para>
+    <para>
+      A good configuration to start with, including a
+      <link xlink:href="https://xmpp.org/extensions/xep-0045.html">Multi
+      User Chat (MUC)</link> endpoint as well as a
+      <link xlink:href="https://xmpp.org/extensions/xep-0363.html">HTTP
+      File Upload</link> endpoint will look like this:
+    </para>
     <programlisting>
 services.prosody = {
   enable = true;
-  admins = [ "root@example.org" ];
-  ssl.cert = "/var/lib/acme/example.org/fullchain.pem";
-  ssl.key = "/var/lib/acme/example.org/key.pem";
-  virtualHosts."example.org" = {
+  admins = [ &quot;root@example.org&quot; ];
+  ssl.cert = &quot;/var/lib/acme/example.org/fullchain.pem&quot;;
+  ssl.key = &quot;/var/lib/acme/example.org/key.pem&quot;;
+  virtualHosts.&quot;example.org&quot; = {
       enabled = true;
-      domain = "example.org";
-      ssl.cert = "/var/lib/acme/example.org/fullchain.pem";
-      ssl.key = "/var/lib/acme/example.org/key.pem";
+      domain = &quot;example.org&quot;;
+      ssl.cert = &quot;/var/lib/acme/example.org/fullchain.pem&quot;;
+      ssl.key = &quot;/var/lib/acme/example.org/key.pem&quot;;
   };
   muc = [ {
-      domain = "conference.example.org";
+      domain = &quot;conference.example.org&quot;;
   } ];
   uploadHttp = {
-      domain = "upload.example.org";
+      domain = &quot;upload.example.org&quot;;
   };
 };
 </programlisting>
-  </para>
- </section>
- <section xml:id="module-services-prosody-letsencrypt">
-  <title>Let's Encrypt Configuration</title>
- <para>
-   As you can see in the code snippet from the
-   <link linkend="module-services-prosody-basic-usage">previous section</link>,
-   you'll need a single TLS certificate covering your main endpoint,
-   the MUC one as well as the HTTP Upload one. We can generate such a
-   certificate by leveraging the ACME
-   <link linkend="opt-security.acme.certs._name_.extraDomainNames">extraDomainNames</link> module option.
- </para>
- <para>
-   Provided the setup detailed in the previous section, you'll need the following acme configuration to generate
-   a TLS certificate for the three endponits:
+  </section>
+  <section xml:id="module-services-prosody-letsencrypt">
+    <title>Let's Encrypt Configuration</title>
+    <para>
+      As you can see in the code snippet from the
+      <link linkend="module-services-prosody-basic-usage">previous
+      section</link>, you'll need a single TLS certificate covering your
+      main endpoint, the MUC one as well as the HTTP Upload one. We can
+      generate such a certificate by leveraging the ACME
+      <link linkend="opt-security.acme.certs._name_.extraDomainNames">extraDomainNames</link>
+      module option.
+    </para>
+    <para>
+      Provided the setup detailed in the previous section, you'll need
+      the following acme configuration to generate a TLS certificate for
+      the three endponits:
+    </para>
     <programlisting>
 security.acme = {
-  email = "root@example.org";
+  email = &quot;root@example.org&quot;;
   acceptTerms = true;
   certs = {
-    "example.org" = {
-      webroot = "/var/www/example.org";
-      email = "root@example.org";
-      extraDomainNames = [ "conference.example.org" "upload.example.org" ];
+    &quot;example.org&quot; = {
+      webroot = &quot;/var/www/example.org&quot;;
+      email = &quot;root@example.org&quot;;
+      extraDomainNames = [ &quot;conference.example.org&quot; &quot;upload.example.org&quot; ];
     };
   };
 };
 </programlisting>
- </para>
-</section>
+  </section>
 </chapter>