diff --git a/nixos/doc/manual/configuration/customizing-packages.section.md b/nixos/doc/manual/configuration/customizing-packages.section.md
new file mode 100644
index 00000000000..480aed61211
--- /dev/null
+++ b/nixos/doc/manual/configuration/customizing-packages.section.md
@@ -0,0 +1,74 @@
+# Customising Packages {#sec-customising-packages}
+
+Some packages in Nixpkgs have options to enable or disable optional
+functionality or change other aspects of the package. For instance, the
+Firefox wrapper package (which provides Firefox with a set of plugins
+such as the Adobe Flash player) has an option to enable the Google Talk
+plugin. It can be set in `configuration.nix` as follows:
+`nixpkgs.config.firefox.enableGoogleTalkPlugin = true;`
+
+::: {.warning}
+Unfortunately, Nixpkgs currently lacks a way to query available
+configuration options.
+:::
+
+Apart from high-level options, it's possible to tweak a package in
+almost arbitrary ways, such as changing or disabling dependencies of a
+package. For instance, the Emacs package in Nixpkgs by default has a
+dependency on GTK 2. If you want to build it against GTK 3, you can
+specify that as follows:
+
+```nix
+environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
+```
+
+The function `override` performs the call to the Nix function that
+produces Emacs, with the original arguments amended by the set of
+arguments specified by you. So here the function argument `gtk` gets the
+value `pkgs.gtk3`, causing Emacs to depend on GTK 3. (The parentheses
+are necessary because in Nix, function application binds more weakly
+than list construction, so without them,
+[`environment.systemPackages`](options.html#opt-environment.systemPackages)
+would be a list with two elements.)
+
+Even greater customisation is possible using the function
+`overrideAttrs`. While the `override` mechanism above overrides the
+arguments of a package function, `overrideAttrs` allows changing the
+*attributes* passed to `mkDerivation`. This permits changing any aspect
+of the package, such as the source code. For instance, if you want to
+override the source code of Emacs, you can say:
+
+```nix
+environment.systemPackages = [
+ (pkgs.emacs.overrideAttrs (oldAttrs: {
+ name = "emacs-25.0-pre";
+ src = /path/to/my/emacs/tree;
+ }))
+];
+```
+
+Here, `overrideAttrs` takes the Nix derivation specified by `pkgs.emacs`
+and produces a new derivation in which the original's `name` and `src`
+attribute have been replaced by the given values by re-calling
+`stdenv.mkDerivation`. The original attributes are accessible via the
+function argument, which is conventionally named `oldAttrs`.
+
+The overrides shown above are not global. They do not affect the
+original package; other packages in Nixpkgs continue to depend on the
+original rather than the customised package. This means that if another
+package in your system depends on the original package, you end up with
+two instances of the package. If you want to have everything depend on
+your customised instance, you can apply a *global* override as follows:
+
+```nix
+nixpkgs.config.packageOverrides = pkgs:
+ { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };
+ };
+```
+
+The effect of this definition is essentially equivalent to modifying the
+`emacs` attribute in the Nixpkgs source tree. Any package in Nixpkgs
+that depends on `emacs` will be passed your customised instance.
+(However, the value `pkgs.emacs` in `nixpkgs.config.packageOverrides`
+refers to the original rather than overridden instance, to prevent an
+infinite recursion.)
diff --git a/nixos/doc/manual/configuration/customizing-packages.xml b/nixos/doc/manual/configuration/customizing-packages.xml
deleted file mode 100644
index 34e6ab4b24d..00000000000
--- a/nixos/doc/manual/configuration/customizing-packages.xml
+++ /dev/null
@@ -1,86 +0,0 @@
-
- Customising Packages
-
-
- Some packages in Nixpkgs have options to enable or disable optional
- functionality or change other aspects of the package. For instance, the
- Firefox wrapper package (which provides Firefox with a set of plugins such as
- the Adobe Flash player) has an option to enable the Google Talk plugin. It
- can be set in configuration.nix as follows:
- nixpkgs.config.firefox.enableGoogleTalkPlugin = true;
-
-
-
-
- Unfortunately, Nixpkgs currently lacks a way to query available
- configuration options.
-
-
-
-
- Apart from high-level options, it’s possible to tweak a package in almost
- arbitrary ways, such as changing or disabling dependencies of a package. For
- instance, the Emacs package in Nixpkgs by default has a dependency on GTK 2.
- If you want to build it against GTK 3, you can specify that as follows:
-
- = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
-
- The function override performs the call to the Nix
- function that produces Emacs, with the original arguments amended by the set
- of arguments specified by you. So here the function argument
- gtk gets the value pkgs.gtk3, causing
- Emacs to depend on GTK 3. (The parentheses are necessary because in Nix,
- function application binds more weakly than list construction, so without
- them, would be a list with
- two elements.)
-
-
-
- Even greater customisation is possible using the function
- overrideAttrs. While the override
- mechanism above overrides the arguments of a package function,
- overrideAttrs allows changing the
- attributes passed to mkDerivation.
- This permits changing any aspect of the package, such as the source code. For
- instance, if you want to override the source code of Emacs, you can say:
-
- = [
- (pkgs.emacs.overrideAttrs (oldAttrs: {
- name = "emacs-25.0-pre";
- src = /path/to/my/emacs/tree;
- }))
-];
-
- Here, overrideAttrs takes the Nix derivation specified by
- pkgs.emacs and produces a new derivation in which the
- original’s name and src attribute
- have been replaced by the given values by re-calling
- stdenv.mkDerivation. The original attributes are
- accessible via the function argument, which is conventionally named
- oldAttrs.
-
-
-
- The overrides shown above are not global. They do not affect the original
- package; other packages in Nixpkgs continue to depend on the original rather
- than the customised package. This means that if another package in your
- system depends on the original package, you end up with two instances of the
- package. If you want to have everything depend on your customised instance,
- you can apply a global override as follows:
-
-nixpkgs.config.packageOverrides = pkgs:
- { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };
- };
-
- The effect of this definition is essentially equivalent to modifying the
- emacs attribute in the Nixpkgs source tree. Any package in
- Nixpkgs that depends on emacs will be passed your
- customised instance. (However, the value pkgs.emacs in
- nixpkgs.config.packageOverrides refers to the original
- rather than overridden instance, to prevent an infinite recursion.)
-
-
diff --git a/nixos/doc/manual/configuration/declarative-packages.xml b/nixos/doc/manual/configuration/declarative-packages.xml
index 648bb76cf3b..8d321929f3f 100644
--- a/nixos/doc/manual/configuration/declarative-packages.xml
+++ b/nixos/doc/manual/configuration/declarative-packages.xml
@@ -48,7 +48,7 @@ nixos.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded
nixos-rebuild switch.
-
+
diff --git a/nixos/doc/manual/from_md/configuration/customizing-packages.section.xml b/nixos/doc/manual/from_md/configuration/customizing-packages.section.xml
new file mode 100644
index 00000000000..661fb8475b3
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/customizing-packages.section.xml
@@ -0,0 +1,90 @@
+
+ Customising Packages
+
+ Some packages in Nixpkgs have options to enable or disable optional
+ functionality or change other aspects of the package. For instance,
+ the Firefox wrapper package (which provides Firefox with a set of
+ plugins such as the Adobe Flash player) has an option to enable the
+ Google Talk plugin. It can be set in
+ configuration.nix as follows:
+ nixpkgs.config.firefox.enableGoogleTalkPlugin = true;
+
+
+
+ Unfortunately, Nixpkgs currently lacks a way to query available
+ configuration options.
+
+
+
+ Apart from high-level options, it’s possible to tweak a package in
+ almost arbitrary ways, such as changing or disabling dependencies of
+ a package. For instance, the Emacs package in Nixpkgs by default has
+ a dependency on GTK 2. If you want to build it against GTK 3, you
+ can specify that as follows:
+
+
+environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
+
+
+ The function override performs the call to the
+ Nix function that produces Emacs, with the original arguments
+ amended by the set of arguments specified by you. So here the
+ function argument gtk gets the value
+ pkgs.gtk3, causing Emacs to depend on GTK 3. (The
+ parentheses are necessary because in Nix, function application binds
+ more weakly than list construction, so without them,
+ environment.systemPackages
+ would be a list with two elements.)
+
+
+ Even greater customisation is possible using the function
+ overrideAttrs. While the
+ override mechanism above overrides the arguments
+ of a package function, overrideAttrs allows
+ changing the attributes passed to
+ mkDerivation. This permits changing any aspect of
+ the package, such as the source code. For instance, if you want to
+ override the source code of Emacs, you can say:
+
+
+environment.systemPackages = [
+ (pkgs.emacs.overrideAttrs (oldAttrs: {
+ name = "emacs-25.0-pre";
+ src = /path/to/my/emacs/tree;
+ }))
+];
+
+
+ Here, overrideAttrs takes the Nix derivation
+ specified by pkgs.emacs and produces a new
+ derivation in which the original’s name and
+ src attribute have been replaced by the given
+ values by re-calling stdenv.mkDerivation. The
+ original attributes are accessible via the function argument, which
+ is conventionally named oldAttrs.
+
+
+ The overrides shown above are not global. They do not affect the
+ original package; other packages in Nixpkgs continue to depend on
+ the original rather than the customised package. This means that if
+ another package in your system depends on the original package, you
+ end up with two instances of the package. If you want to have
+ everything depend on your customised instance, you can apply a
+ global override as follows:
+
+
+nixpkgs.config.packageOverrides = pkgs:
+ { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };
+ };
+
+
+ The effect of this definition is essentially equivalent to modifying
+ the emacs attribute in the Nixpkgs source tree.
+ Any package in Nixpkgs that depends on emacs will
+ be passed your customised instance. (However, the value
+ pkgs.emacs in
+ nixpkgs.config.packageOverrides refers to the
+ original rather than overridden instance, to prevent an infinite
+ recursion.)
+
+