nixos/plausible: convert manual chapter to MD

3 files changed, 60 insertions, 23 deletions

diff --git a/nixos/modules/services/web-apps/plausible.md b/nixos/modules/services/web-apps/plausible.md
new file mode 100644
index 00000000000..1328ce69441
--- /dev/null
+++ b/nixos/modules/services/web-apps/plausible.md
@@ -0,0 +1,35 @@
+# Plausible {#module-services-plausible}
+
+[Plausible](https://plausible.io/) is a privacy-friendly alternative to
+Google analytics.
+
+## Basic Usage {#module-services-plausible-basic-usage}
+
+At first, a secret key is needed to be generated. This can be done with e.g.
+```ShellSession
+$ openssl rand -base64 64
+```
+
+After that, `plausible` can be deployed like this:
+```
+{
+  services.plausible = {
+    enable = true;
+    adminUser = {
+      # activate is used to skip the email verification of the admin-user that's
+      # automatically created by plausible. This is only supported if
+      # postgresql is configured by the module. This is done by default, but
+      # can be turned off with services.plausible.database.postgres.setup.
+      activate = true;
+      email = "admin@localhost";
+      passwordFile = "/run/secrets/plausible-admin-pwd";
+    };
+    server = {
+      baseUrl = "http://analytics.example.org";
+      # secretKeybaseFile is a path to the file which contains the secret generated
+      # with openssl as described above.
+      secretKeybaseFile = "/run/secrets/plausible-secret-key-base";
+    };
+  };
+}
+```
diff --git a/nixos/modules/services/web-apps/plausible.nix b/nixos/modules/services/web-apps/plausible.nix
index e5dc1b10360..bbad8152b53 100644
--- a/nixos/modules/services/web-apps/plausible.nix
+++ b/nixos/modules/services/web-apps/plausible.nix
@@ -292,5 +292,7 @@ in {
   };
 
   meta.maintainers = with maintainers; [ ma27 ];
+  # Don't edit the docbook xml directly, edit the md and generate it:
+  # `pandoc plausible.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 > plausible.xml`
   meta.doc = ./plausible.xml;
 }
diff --git a/nixos/modules/services/web-apps/plausible.xml b/nixos/modules/services/web-apps/plausible.xml
index 9546ae4e558..f84a91a9f8b 100644
--- a/nixos/modules/services/web-apps/plausible.xml
+++ b/nixos/modules/services/web-apps/plausible.xml
@@ -1,22 +1,23 @@
-<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-plausible">
- <title>Plausible</title>
- <para>
-  <link xlink:href="https://plausible.io/">Plausible</link> is a privacy-friendly alternative to
-  Google analytics.
- </para>
- <section xml:id="module-services-plausible-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-plausible">
+  <title>Plausible</title>
   <para>
-   At first, a secret key is needed to be generated. This can be done with e.g.
-   <screen><prompt>$ </prompt>openssl rand -base64 64</screen>
+    <link xlink:href="https://plausible.io/">Plausible</link> is a
+    privacy-friendly alternative to Google analytics.
   </para>
-  <para>
-   After that, <literal>plausible</literal> can be deployed like this:
-<programlisting>
+  <section xml:id="module-services-plausible-basic-usage">
+    <title>Basic Usage</title>
+    <para>
+      At first, a secret key is needed to be generated. This can be done
+      with e.g.
+    </para>
+    <programlisting>
+$ openssl rand -base64 64
+</programlisting>
+    <para>
+      After that, <literal>plausible</literal> can be deployed like
+      this:
+    </para>
+    <programlisting>
 {
   services.plausible = {
     enable = true;
@@ -26,18 +27,17 @@
       # postgresql is configured by the module. This is done by default, but
       # can be turned off with services.plausible.database.postgres.setup.
       activate = true;
-      email = "admin@localhost";
-      passwordFile = "/run/secrets/plausible-admin-pwd";
+      email = &quot;admin@localhost&quot;;
+      passwordFile = &quot;/run/secrets/plausible-admin-pwd&quot;;
     };
     server = {
-      baseUrl = "http://analytics.example.org";
+      baseUrl = &quot;http://analytics.example.org&quot;;
       # secretKeybaseFile is a path to the file which contains the secret generated
       # with openssl as described above.
-      secretKeybaseFile = "/run/secrets/plausible-secret-key-base";
+      secretKeybaseFile = &quot;/run/secrets/plausible-secret-key-base&quot;;
     };
   };
 }
 </programlisting>
-  </para>
- </section>
+  </section>
 </chapter>