documentation: use sections instead of list items

src/nix/flake.md

@@ -18,51 +18,56 @@ values such as packages or NixOS modules provided by the flake).
 Flake references (*flakerefs*) are a way to specify the location of a
 flake. These have two different forms:
 
-* An attribute set representation, e.g.
 
-  ```nix
+## Attribute set representation
-  {
+
+Example:
+
+```nix
+{
   type = "github";
   owner = "NixOS";
   repo = "nixpkgs";
-  }
+}
-  ```
+```
 
-  The only required attribute is `type`. The supported types are
+The only required attribute is `type`. The supported types are
-  listed below.
+listed below.
 
-* A URL-like syntax, e.g.
+## URL-like syntax
 
-  ```
+Example:
-  github:NixOS/nixpkgs
-  ```
 
-  These are used on the command line as a more convenient alternative
+```
-  to the attribute set representation. For instance, in the command
+github:NixOS/nixpkgs
+```
 
-  ```console
+These are used on the command line as a more convenient alternative
-  # nix build github:NixOS/nixpkgs#hello
+to the attribute set representation. For instance, in the command
-  ```
 
-  `github:NixOS/nixpkgs` is a flake reference (while `hello` is an
+```console
-  output attribute). They are also allowed in the `inputs` attribute
+# nix build github:NixOS/nixpkgs#hello
-  of a flake, e.g.
+```
 
-  ```nix
+`github:NixOS/nixpkgs` is a flake reference (while `hello` is an
-  inputs.nixpkgs.url = github:NixOS/nixpkgs;
+output attribute). They are also allowed in the `inputs` attribute
-  ```
+of a flake, e.g.
 
-  is equivalent to
+```nix
+inputs.nixpkgs.url = github:NixOS/nixpkgs;
+```
 
-  ```nix
+is equivalent to
-  inputs.nixpkgs = {
+
+```nix
+inputs.nixpkgs = {
   type = "github";
   owner = "NixOS";
   repo = "nixpkgs";
-  };
+};
-  ```
+```
 
-## Examples
+### Examples
 
 Here are some examples of flake references in their URL-like representation: