diff --git a/nixos/doc/manual/development/assertions.section.md b/nixos/doc/manual/development/assertions.section.md
new file mode 100644
index 000000000000..cc6d81e56990
--- /dev/null
+++ b/nixos/doc/manual/development/assertions.section.md
@@ -0,0 +1,40 @@
+# Warnings and Assertions {#sec-assertions}
+
+When configuration problems are detectable in a module, it is a good idea to write an assertion or warning. Doing so provides clear feedback to the user and prevents errors after the build.
+
+Although Nix has the `abort` and `builtins.trace` [functions](https://nixos.org/nix/manual/#ssec-builtins) to perform such tasks, they are not ideally suited for NixOS modules. Instead of these functions, you can declare your warnings and assertions using the NixOS module system.
+
+## Warnings {#sec-assertions-warnings}
+
+This is an example of using `warnings`.
+
+```nix
+{ config, lib, ... }:
+{
+ config = lib.mkIf config.services.foo.enable {
+ warnings =
+ if config.services.foo.bar
+ then [ ''You have enabled the bar feature of the foo service.
+ This is known to cause some specific problems in certain situations.
+ '' ]
+ else [];
+ }
+}
+```
+
+## Assertions {#sec-assertions-assetions}
+
+This example, extracted from the [`syslogd` module](https://github.com/NixOS/nixpkgs/blob/release-17.09/nixos/modules/services/logging/syslogd.nix) shows how to use `assertions`. Since there can only be one active syslog daemon at a time, an assertion is useful to prevent such a broken system from being built.
+
+```nix
+{ config, lib, ... }:
+{
+ config = lib.mkIf config.services.syslogd.enable {
+ assertions =
+ [ { assertion = !config.services.rsyslogd.enable;
+ message = "rsyslogd conflicts with syslogd";
+ }
+ ];
+ }
+}
+```
diff --git a/nixos/doc/manual/development/assertions.xml b/nixos/doc/manual/development/assertions.xml
deleted file mode 100644
index 32f90cf2e7c4..000000000000
--- a/nixos/doc/manual/development/assertions.xml
+++ /dev/null
@@ -1,74 +0,0 @@
-
- Warnings and Assertions
-
-
- When configuration problems are detectable in a module, it is a good idea to
- write an assertion or warning. Doing so provides clear feedback to the user
- and prevents errors after the build.
-
-
-
- Although Nix has the abort and
- builtins.trace
- functions
- to perform such tasks, they are not ideally suited for NixOS modules. Instead
- of these functions, you can declare your warnings and assertions using the
- NixOS module system.
-
-
-
- Warnings
-
-
- This is an example of using warnings.
-
-
-
-
-
-
-
-
- Assertions
-
-
- This example, extracted from the
-
- syslogd module shows how to use
- assertions. Since there can only be one active syslog
- daemon at a time, an assertion is useful to prevent such a broken system
- from being built.
-
-
-
-
-
-
-
diff --git a/nixos/doc/manual/development/writing-modules.xml b/nixos/doc/manual/development/writing-modules.xml
index fad4637f51f0..04497db77b89 100644
--- a/nixos/doc/manual/development/writing-modules.xml
+++ b/nixos/doc/manual/development/writing-modules.xml
@@ -182,7 +182,7 @@ in {
-
+
diff --git a/nixos/doc/manual/from_md/development/assertions.section.xml b/nixos/doc/manual/from_md/development/assertions.section.xml
new file mode 100644
index 000000000000..0844d484d60f
--- /dev/null
+++ b/nixos/doc/manual/from_md/development/assertions.section.xml
@@ -0,0 +1,58 @@
+
+ Warnings and Assertions
+
+ When configuration problems are detectable in a module, it is a good
+ idea to write an assertion or warning. Doing so provides clear
+ feedback to the user and prevents errors after the build.
+
+
+ Although Nix has the abort and
+ builtins.trace
+ functions
+ to perform such tasks, they are not ideally suited for NixOS
+ modules. Instead of these functions, you can declare your warnings
+ and assertions using the NixOS module system.
+
+
+ Warnings
+
+ This is an example of using warnings.
+
+
+{ config, lib, ... }:
+{
+ config = lib.mkIf config.services.foo.enable {
+ warnings =
+ if config.services.foo.bar
+ then [ ''You have enabled the bar feature of the foo service.
+ This is known to cause some specific problems in certain situations.
+ '' ]
+ else [];
+ }
+}
+
+
+
+ Assertions
+
+ This example, extracted from the
+ syslogd
+ module shows how to use assertions.
+ Since there can only be one active syslog daemon at a time, an
+ assertion is useful to prevent such a broken system from being
+ built.
+
+
+{ config, lib, ... }:
+{
+ config = lib.mkIf config.services.syslogd.enable {
+ assertions =
+ [ { assertion = !config.services.rsyslogd.enable;
+ message = "rsyslogd conflicts with syslogd";
+ }
+ ];
+ }
+}
+
+
+