ensure the section hierarchy is spec-compliant

- check that there is a single section hierarchy

  this also allows us to 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;
-    squash (trim ''
+    lib.squash ''
       <${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
+                              if isAttrs x && x ? section && x.section ? heading
                               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) content);
+                              (filter (x: isAttrs x && x ? section && x.section ? heading) content);
                             subsections = concatMap
                               (x:
                                 if isAttrs x && x ? section && x.section ? content
@@ -403,8 +403,14 @@ 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 too-deep != [ ] then
+                  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
                     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}
@@ -441,37 +447,29 @@ 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));
@@ -484,24 +482,22 @@ let
         type = with types; ints.between 1 6;
         internal = true;
       };
-      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
+      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
               (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