diff --git a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/docbook.py b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/docbook.py
index 3676c17a9909..bad36e57a2f3 100644
--- a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/docbook.py
+++ b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/docbook.py
@@ -103,7 +103,8 @@ class DocBookRenderer(Renderer):
     # HACK open and close para for docbook change size. remove soon.
     def bullet_list_open(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,
                          env: MutableMapping[str, Any]) -> str:
-        return "<para><itemizedlist>\n"
+        spacing = ' spacing="compact"' if token.attrs.get('compact', False) else ''
+        return f"<para><itemizedlist{spacing}>\n"
     def bullet_list_close(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,
                           env: MutableMapping[str, Any]) -> str:
         return "\n</itemizedlist></para>"
@@ -217,7 +218,8 @@ class DocBookRenderer(Renderer):
     def ordered_list_open(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,
                           env: MutableMapping[str, Any]) -> str:
         start = f' startingnumber="{token.attrs["start"]}"' if 'start' in token.attrs else ""
-        return f"<orderedlist{start}>"
+        spacing = ' spacing="compact"' if token.attrs.get('compact', False) else ''
+        return f"<orderedlist{start}{spacing}>"
     def ordered_list_close(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,
                            env: MutableMapping[str, Any]) -> str:
         return f"</orderedlist>"
diff --git a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/md.py b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/md.py
index ad28dbabe574..c08675870f6a 100644
--- a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/md.py
+++ b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/md.py
@@ -359,6 +359,20 @@ class Converter(ABC):
                 if m := _HEADER_ID_RE.search(children[-1].content):
                     tokens[i].attrs['id'] = m[1]
                     children[-1].content = children[-1].content[:-len(m[0])].rstrip()
+
+        # markdown-it signifies wide lists by setting the wrapper paragraphs
+        # of each item to hidden. this is not useful for our stylesheets, which
+        # signify this with a special css class on list elements instead.
+        wide_stack = []
+        for i in range(0, len(tokens)):
+            if tokens[i].type in [ 'bullet_list_open', 'ordered_list_open' ]:
+                wide_stack.append([i, True])
+            elif tokens[i].type in [ 'bullet_list_close', 'ordered_list_close' ]:
+                (idx, compact) = wide_stack.pop()
+                tokens[idx].attrs['compact'] = compact
+            elif len(wide_stack) > 0 and tokens[i].type == 'paragraph_open' and not tokens[i].hidden:
+                wide_stack[-1][1] = False
+
         return tokens
 
     def _parse(self, src: str, env: Optional[MutableMapping[str, Any]] = None) -> list[Token]:
diff --git a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py
index 839f29d43704..3667c7bbcdeb 100644
--- a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py
+++ b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py
@@ -156,6 +156,16 @@ class OptionsDocBookRenderer(DocBookRenderer):
                       env: MutableMapping[str, Any]) -> str:
         raise RuntimeError("md token not supported in options doc", token)
 
+    # TODO keep optionsDocBook diff small. remove soon if rendering is still good.
+    def ordered_list_open(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,
+                          env: MutableMapping[str, Any]) -> str:
+        token.attrs['compact'] = False
+        return super().ordered_list_open(token, tokens, i, options, env)
+    def bullet_list_open(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,
+                         env: MutableMapping[str, Any]) -> str:
+        token.attrs['compact'] = False
+        return super().bullet_list_open(token, tokens, i, options, env)
+
 class DocBookConverter(BaseConverter):
     __renderer__ = OptionsDocBookRenderer
 
diff --git a/pkgs/tools/nix/nixos-render-docs/src/tests/test_lists.py b/pkgs/tools/nix/nixos-render-docs/src/tests/test_lists.py
new file mode 100644
index 000000000000..0f5d28407367
--- /dev/null
+++ b/pkgs/tools/nix/nixos-render-docs/src/tests/test_lists.py
@@ -0,0 +1,182 @@
+import nixos_render_docs
+import pytest
+
+from markdown_it.token import Token
+
+class Converter(nixos_render_docs.md.Converter):
+    # actual renderer doesn't matter, we're just parsing.
+    __renderer__ = nixos_render_docs.docbook.DocBookRenderer
+
+@pytest.mark.parametrize("ordered", [True, False])
+def test_list_wide(ordered: bool) -> None:
+    t, tag, m, e1, e2, i1, i2 = (
+        ("ordered", "ol", ".", "1.", "2.", "1", "2") if ordered else ("bullet", "ul", "-", "-", "-", "", "")
+    )
+    c = Converter({})
+    assert c._parse(f"{e1} a\n\n{e2} b") == [
+        Token(type=f'{t}_list_open', tag=tag, nesting=1, attrs={'compact': False}, map=[0, 3], level=0,
+              children=None, content='', markup=m, info='', meta={}, block=True, hidden=False),
+        Token(type='list_item_open', tag='li', nesting=1, attrs={}, map=[0, 2], level=1, children=None,
+              content='', markup=m, info=i1, meta={}, block=True, hidden=False),
+        Token(type='paragraph_open', tag='p', nesting=1, attrs={}, map=[0, 1], level=2, children=None,
+              content='', markup='', info='', meta={}, block=True, hidden=False),
+        Token(type='inline', tag='', nesting=0, attrs={}, map=[0, 1], level=3,
+              content='a', markup='', info='', meta={}, block=True, hidden=False,
+              children=[
+                  Token(type='text', tag='', nesting=0, attrs={}, map=None, level=0, children=None,
+                        content='a', markup='', info='', meta={}, block=False, hidden=False)
+              ]),
+        Token(type='paragraph_close', tag='p', nesting=-1, attrs={}, map=None, level=2, children=None,
+              content='', markup='', info='', meta={}, block=True, hidden=False),
+        Token(type='list_item_close', tag='li', nesting=-1, attrs={}, map=None, level=1, children=None,
+              content='', markup=m, info='', meta={}, block=True, hidden=False),
+        Token(type='list_item_open', tag='li', nesting=1, attrs={}, map=[2, 3], level=1, children=None,
+              content='', markup=m, info=i2, meta={}, block=True, hidden=False),
+        Token(type='paragraph_open', tag='p', nesting=1, attrs={}, map=[2, 3], level=2, children=None,
+              content='', markup='', info='', meta={}, block=True, hidden=False),
+        Token(type='inline', tag='', nesting=0, attrs={}, map=[2, 3], level=3,
+              content='b', markup='', info='', meta={}, block=True, hidden=False,
+              children=[
+                  Token(type='text', tag='', nesting=0, attrs={}, map=None, level=0, children=None,
+                        content='b', markup='', info='', meta={}, block=False, hidden=False)
+              ]),
+        Token(type='paragraph_close', tag='p', nesting=-1, attrs={}, map=None, level=2, children=None,
+              content='', markup='', info='', meta={}, block=True, hidden=False),
+        Token(type='list_item_close', tag='li', nesting=-1, attrs={}, map=None, level=1, children=None,
+              content='', markup=m, info='', meta={}, block=True, hidden=False),
+        Token(type=f'{t}_list_close', tag=tag, nesting=-1, attrs={}, map=None, level=0, children=None,
+              content='', markup=m, info='', meta={}, block=True, hidden=False)
+    ]
+
+@pytest.mark.parametrize("ordered", [True, False])
+def test_list_narrow(ordered: bool) -> None:
+    t, tag, m, e1, e2, i1, i2 = (
+        ("ordered", "ol", ".", "1.", "2.", "1", "2") if ordered else ("bullet", "ul", "-", "-", "-", "", "")
+    )
+    c = Converter({})
+    assert c._parse(f"{e1} a\n{e2} b") == [
+        Token(type=f'{t}_list_open', tag=tag, nesting=1, attrs={'compact': True}, map=[0, 2], level=0,
+              children=None, content='', markup=m, info='', meta={}, block=True, hidden=False),
+        Token(type='list_item_open', tag='li', nesting=1, attrs={}, map=[0, 1], level=1, children=None,
+              content='', markup=m, info=i1, meta={}, block=True, hidden=False),
+        Token(type='paragraph_open', tag='p', nesting=1, attrs={}, map=[0, 1], level=2, children=None,
+              content='', markup='', info='', meta={}, block=True, hidden=True),
+        Token(type='inline', tag='', nesting=0, attrs={}, map=[0, 1], level=3,
+              content='a', markup='', info='', meta={}, block=True, hidden=False,
+              children=[
+                  Token(type='text', tag='', nesting=0, attrs={}, map=None, level=0, children=None,
+                        content='a', markup='', info='', meta={}, block=False, hidden=False)
+              ]),
+        Token(type='paragraph_close', tag='p', nesting=-1, attrs={}, map=None, level=2, children=None,
+              content='', markup='', info='', meta={}, block=True, hidden=True),
+        Token(type='list_item_close', tag='li', nesting=-1, attrs={}, map=None, level=1, children=None,
+              content='', markup=m, info='', meta={}, block=True, hidden=False),
+        Token(type='list_item_open', tag='li', nesting=1, attrs={}, map=[1, 2], level=1, children=None,
+              content='', markup=m, info=i2, meta={}, block=True, hidden=False),
+        Token(type='paragraph_open', tag='p', nesting=1, attrs={}, map=[1, 2], level=2, children=None,
+              content='', markup='', info='', meta={}, block=True, hidden=True),
+        Token(type='inline', tag='', nesting=0, attrs={}, map=[1, 2], level=3,
+              content='b', markup='', info='', meta={}, block=True, hidden=False,
+              children=[
+                  Token(type='text', tag='', nesting=0, attrs={}, map=None, level=0, children=None,
+                        content='b', markup='', info='', meta={}, block=False, hidden=False)
+              ]),
+        Token(type='paragraph_close', tag='p', nesting=-1, attrs={}, map=None, level=2, children=None,
+              content='', markup='', info='', meta={}, block=True, hidden=True),
+        Token(type='list_item_close', tag='li', nesting=-1, attrs={}, map=None, level=1, children=None,
+              content='', markup=m, info='', meta={}, block=True, hidden=False),
+        Token(type=f'{t}_list_close', tag=tag, nesting=-1, attrs={}, map=None, level=0, children=None,
+              content='', markup=m, info='', meta={}, block=True, hidden=False)
+    ]
+    assert c._parse(f"{e1} - a\n{e2} b") == [
+        Token(type=f'{t}_list_open', tag=tag, nesting=1, attrs={'compact': True}, map=[0, 2], level=0,
+              children=None, content='', markup=m, info='', meta={}, block=True, hidden=False),
+        Token(type='list_item_open', tag='li', nesting=1, attrs={}, map=[0, 1], level=1, children=None,
+              content='', markup=m, info=i1, meta={}, block=True, hidden=False),
+        Token(type='bullet_list_open', tag='ul', nesting=1, attrs={'compact': True}, map=[0, 1], level=2,
+              children=None, content='', markup='-', info='', meta={}, block=True, hidden=False),
+        Token(type='list_item_open', tag='li', nesting=1, attrs={}, map=[0, 1], level=3, children=None,
+              content='', markup='-', info='', meta={}, block=True, hidden=False),
+        Token(type='paragraph_open', tag='p', nesting=1, attrs={}, map=[0, 1], level=4, children=None,
+              content='', markup='', info='', meta={}, block=True, hidden=True),
+        Token(type='inline', tag='', nesting=0, attrs={}, map=[0, 1], level=5,
+              content='a', markup='', info='', meta={}, block=True, hidden=False,
+              children=[
+                  Token(type='text', tag='', nesting=0, attrs={}, map=None, level=0, children=None,
+                        content='a', markup='', info='', meta={}, block=False, hidden=False)
+              ]),
+        Token(type='paragraph_close', tag='p', nesting=-1, attrs={}, map=None, level=4, children=None,
+              content='', markup='', info='', meta={}, block=True, hidden=True),
+        Token(type='list_item_close', tag='li', nesting=-1, attrs={}, map=None, level=3, children=None,
+              content='', markup='-', info='', meta={}, block=True, hidden=False),
+        Token(type='bullet_list_close', tag='ul', nesting=-1, attrs={}, map=None, level=2, children=None,
+              content='', markup='-', info='', meta={}, block=True, hidden=False),
+        Token(type='list_item_close', tag='li', nesting=-1, attrs={}, map=None, level=1, children=None,
+              content='', markup=m, info='', meta={}, block=True, hidden=False),
+        Token(type='list_item_open', tag='li', nesting=1, attrs={}, map=[1, 2], level=1, children=None,
+              content='', markup=m, info=i2, meta={}, block=True, hidden=False),
+        Token(type='paragraph_open', tag='p', nesting=1, attrs={}, map=[1, 2], level=2, children=None,
+              content='', markup='', info='', meta={}, block=True, hidden=True),
+        Token(type='inline', tag='', nesting=0, attrs={}, map=[1, 2], level=3,
+              content='b', markup='', info='', meta={}, block=True, hidden=False,
+              children=[
+                  Token(type='text', tag='', nesting=0, attrs={}, map=None, level=0, children=None,
+                        content='b', markup='', info='', meta={}, block=False, hidden=False)
+              ]),
+        Token(type='paragraph_close', tag='p', nesting=-1, attrs={}, map=None, level=2, children=None,
+              content='', markup='', info='', meta={}, block=True, hidden=True),
+        Token(type='list_item_close', tag='li', nesting=-1, attrs={}, map=None, level=1, children=None,
+              content='', markup=m, info='', meta={}, block=True, hidden=False),
+        Token(type=f'{t}_list_close', tag=tag, nesting=-1, attrs={}, map=None, level=0, children=None,
+              content='', markup=m, info='', meta={}, block=True, hidden=False)
+    ]
+    assert c._parse(f"{e1} - a\n{e2} - b") == [
+        Token(type=f'{t}_list_open', tag=tag, nesting=1, attrs={'compact': True}, map=[0, 2], level=0,
+              children=None, content='', markup=m, info='', meta={}, block=True, hidden=False),
+        Token(type='list_item_open', tag='li', nesting=1, attrs={}, map=[0, 1], level=1, children=None,
+              content='', markup=m, info=i1, meta={}, block=True, hidden=False),
+        Token(type='bullet_list_open', tag='ul', nesting=1, attrs={'compact': True}, map=[0, 1], level=2,
+              children=None, content='', markup='-', info='', meta={}, block=True, hidden=False),
+        Token(type='list_item_open', tag='li', nesting=1, attrs={}, map=[0, 1], level=3, children=None,
+              content='', markup='-', info='', meta={}, block=True, hidden=False),
+        Token(type='paragraph_open', tag='p', nesting=1, attrs={}, map=[0, 1], level=4, children=None,
+              content='', markup='', info='', meta={}, block=True, hidden=True),
+        Token(type='inline', tag='', nesting=0, attrs={}, map=[0, 1], level=5,
+              content='a', markup='', info='', meta={}, block=True, hidden=False,
+              children=[
+                  Token(type='text', tag='', nesting=0, attrs={}, map=None, level=0, children=None,
+                        content='a', markup='', info='', meta={}, block=False, hidden=False)
+              ]),
+        Token(type='paragraph_close', tag='p', nesting=-1, attrs={}, map=None, level=4, children=None,
+              content='', markup='', info='', meta={}, block=True, hidden=True),
+        Token(type='list_item_close', tag='li', nesting=-1, attrs={}, map=None, level=3, children=None,
+              content='', markup='-', info='', meta={}, block=True, hidden=False),
+        Token(type='bullet_list_close', tag='ul', nesting=-1, attrs={}, map=None, level=2, children=None,
+              content='', markup='-', info='', meta={}, block=True, hidden=False),
+        Token(type='list_item_close', tag='li', nesting=-1, attrs={}, map=None, level=1, children=None,
+              content='', markup=m, info='', meta={}, block=True, hidden=False),
+        Token(type='list_item_open', tag='li', nesting=1, attrs={}, map=[1, 2], level=1, children=None,
+              content='', markup=m, info=i2, meta={}, block=True, hidden=False),
+        Token(type='bullet_list_open', tag='ul', nesting=1, attrs={'compact': True}, map=[1, 2], level=2,
+              children=None, content='', markup='-', info='', meta={}, block=True, hidden=False),
+        Token(type='list_item_open', tag='li', nesting=1, attrs={}, map=[1, 2], level=3, children=None,
+              content='', markup='-', info='', meta={}, block=True, hidden=False),
+        Token(type='paragraph_open', tag='p', nesting=1, attrs={}, map=[1, 2], level=4, children=None,
+              content='', markup='', info='', meta={}, block=True, hidden=True),
+        Token(type='inline', tag='', nesting=0, attrs={}, map=[1, 2], level=5,
+              content='b', markup='', info='', meta={}, block=True, hidden=False,
+              children=[
+                  Token(type='text', tag='', nesting=0, attrs={}, map=None, level=0, children=None,
+                        content='b', markup='', info='', meta={}, block=False, hidden=False)
+              ]),
+        Token(type='paragraph_close', tag='p', nesting=-1, attrs={}, map=None, level=4, children=None,
+              content='', markup='', info='', meta={}, block=True, hidden=True),
+        Token(type='list_item_close', tag='li', nesting=-1, attrs={}, map=None, level=3, children=None,
+              content='', markup='-', info='', meta={}, block=True, hidden=False),
+        Token(type='bullet_list_close', tag='ul', nesting=-1, attrs={}, map=None, level=2, children=None,
+              content='', markup='-', info='', meta={}, block=True, hidden=False),
+        Token(type='list_item_close', tag='li', nesting=-1, attrs={}, map=None, level=1, children=None,
+              content='', markup=m, info='', meta={}, block=True, hidden=False),
+        Token(type=f'{t}_list_close', tag=tag, nesting=-1, attrs={}, map=None, level=0, children=None,
+              content='', markup=m, info='', meta={}, block=True, hidden=False)
+    ]