further prettify output

- automatically assign heading levels
- check that the maximum nesting depth is not exceeded

presentation/default.nix

@@ -53,7 +53,7 @@ in
         render-item = item:
           if item ? menu then ''
             <li>${item.menu.label}
-            ${lib.indent "  " (item.menu.outputs.html page)}
+              ${lib.indent "  " (item.menu.outputs.html page)}
             </li>
           ''
           else if item ? page then ''<li><a href="${page.link item.page}">${item.page.title}</a></li>''

presentation/dom.nix

@@ -147,11 +147,11 @@ let
 
   print-element = name: attrs: content:
     with lib;
-    lib.squash ''
+    squash (trim ''
       <${name}${print-attrs attrs}>
         ${lib.indent "  " content}
       </${name}>
-    '';
+    '');
 
   elements = rec {
     document = { ... }: {
@@ -369,7 +369,7 @@ let
                         process-with-depth = depth: content:
                           map
                             (x:
-                              if isAttrs x && x ? section && x.section ? heading
+                              if isAttrs x && x ? section
                               then x // {
                                 section = x.section // {
                                   heading-level = depth;
@@ -383,7 +383,7 @@ let
                         find-with-depth = depth: content:
                           let
                             sections = map (v: { inherit (def) file; value = v; depth = depth; })
-                              (filter (x: isAttrs x && x ? section && x.section ? heading) content);
+                              (filter (x: isAttrs x && x ? section) content);
                             subsections = concatMap
                               (x:
                                 if isAttrs x && x ? section && x.section ? content
@@ -403,14 +403,8 @@ let
                     processed = map find-and-attach defs;
                     all-sections = flatten (map (p: p.validation) processed);
                     too-deep = filter (sec: sec.depth > 6) all-sections;
-                    top-level = filter (sec: sec.depth == 1) all-sections;
                   in
-                  if length top-level > 1 then
-                    throw ''
-                      The option `${lib.options.showOption loc}` has multiple section hierarchies defined:
-                      ${concatMapStrings (def: "  - in ${toString def.file}\n") top-level}
-                      Content must have at most one section hierarchy.''
-                  else if too-deep != [ ] then
+                  if too-deep != [ ] then
                     throw ''
                       The option `${lib.options.showOption loc}` has sections nested too deeply:
                       ${concatMapStrings (sec: "  - depth ${toString sec.depth} section in ${toString sec.file}\n") too-deep}
@@ -447,29 +441,37 @@ let
           type = with types; nullOr (submodule { options = global-attrs; });
           default = null;
         };
-        # TODO: make `pre-`/`post-heading` wrap the heading in `<hgroup>` if non-empty
-        # https://html.spec.whatwg.org/multipage/sections.html#the-hgroup-element
-        pre-heading = mkOption {
-          type = with types; listOf (attrTag ({ inherit p; } // categories.scripting));
-          default = [ ];
-        };
         heading = mkOption {
+          # XXX: while there are no explicit rules on whether sections should contain headers,
+          #      sections should have content that would be listed in an outline.
+          #
+          #      https://html.spec.whatwg.org/multipage/sections.html#use-div-for-wrappers
+          #
+          #      such an outline is rather meaningless without headings for navigation,
+          #      which is why we enforce headings in sections.
+          #      arguably, and this is encoded here, a section *is defined* by its heading.
           type = with types; submodule ({ ... }: {
             imports = [ element ];
             options = {
               attrs = mkAttrs { };
+              # TODO: make `before`/`after` wrap the heading in `<hgroup>` if non-empty
+              # https://html.spec.whatwg.org/multipage/sections.html#the-hgroup-element
+              before = mkOption {
+                type = with types; listOf (attrTag ({ inherit p; } // categories.scripting));
+                default = [ ];
+              };
               content = mkOption {
                 # https://html.spec.whatwg.org/multipage/sections.html#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements
                 type = with types; either str (listOf (attrTag categories.phrasing));
               };
+              after = mkOption {
+                type = with types;
+                  listOf (attrTag ({ inherit p; } // categories.scripting));
+                default = [ ];
+              };
             };
           });
         };
-        post-heading = mkOption {
-          type = with types;
-            listOf (attrTag ({ inherit p; } // categories.scripting));
-          default = [ ];
-        };
         # https://html.spec.whatwg.org/multipage/sections.html#headings-and-outlines
         content = mkOption {
           type = with types; listOf (either str (attrTag categories.flow));
@@ -482,22 +484,24 @@ let
         type = with types; ints.between 1 6;
         internal = true;
       };
-      config.categories = [ "flow" "sectioning" "palpable" ];
-      config.__toString = self: with lib;
-        let
-          n = toString config.heading-level;
-          content =
-            "<h${n}${print-attrs self.heading.attrs}>${self.heading.content}</h${n}>" + join "\n" (map
+      config = {
+        categories = [ "flow" "sectioning" "palpable" ];
+        __toString = self: with lib;
+          let
+            n = toString config.heading-level;
+            content = ''<h${n}${print-attrs self.heading.attrs}>${self.heading.content}</h${n}>
+              '' + join "\n" (map
               (e:
                 if isAttrs e
                 then toString (lib.head (attrValues e))
                 else e
               )
               self.content);
-        in
-        if !isNull self.attrs
-        then print-element name self.attrs content
-        else content;
+          in
+          if !isNull self.attrs
+          then print-element name self.attrs content
+          else content;
+      };
     };
   };
 in