From 2b2f260a69ac3a0c327119c1b03f8ca1481ff7ef Mon Sep 17 00:00:00 2001
From: Daniel Thwaites <danth@danth.me>
Date: Tue, 18 Feb 2025 14:57:30 +0000
Subject: [PATCH] doc: collapse platforms and modules

Collapsing is only possible for pages, not headings, so I had to
combine platforms and modules into a single section and nest them
under draft pages.

Later, we could migrate some content from the configuration page to
these draft pages to make the flow of the book more natural.
---
 docs/book.toml                                   |  3 +++
 docs/default.nix                                 |  8 ++++----
 docs/src/SUMMARY.md                              | 16 ++++++++++------
 .../{global => platforms}/home_manager.md        |  0
 docs/src/options/{global => platforms}/nixos.md  |  0
 5 files changed, 17 insertions(+), 10 deletions(-)
 rename docs/src/options/{global => platforms}/home_manager.md (100%)
 rename docs/src/options/{global => platforms}/nixos.md (100%)

diff --git a/docs/book.toml b/docs/book.toml
index d4042175..add75d49 100644
--- a/docs/book.toml
+++ b/docs/book.toml
@@ -9,3 +9,6 @@ site-url = "/stylix/"
 git-repository-url = "https://github.com/danth/stylix"
 edit-url-template = "https://github.com/danth/stylix/edit/master/docs/{path}"
 no-section-label = true
+
+[output.html.fold]
+enable = true
diff --git a/docs/default.nix b/docs/default.nix
index fccb4dcf..5c87cf71 100644
--- a/docs/default.nix
+++ b/docs/default.nix
@@ -45,7 +45,7 @@ let
     }).optionsCommonMark;
 
   # The documentation for options which aren't linked to a specific module
-  makeGlobalOptionsDoc =
+  makePlatformsOptionsDoc =
     configuration:
     makeOptionsDoc {
       inherit configuration;
@@ -159,9 +159,9 @@ pkgs.stdenvNoCC.mkDerivation {
     cp ${../gnome.png} src/gnome.png
     cp ${../kde.png} src/kde.png
 
-    mkdir --parents src/options/global
-    writeOptions 'Home Manager' ${(makeGlobalOptionsDoc homeManagerConfiguration)} src/options/global/home_manager.md
-    writeOptions 'NixOS' ${(makeGlobalOptionsDoc nixosConfiguration)} src/options/global/nixos.md
+    mkdir --parents src/options/platforms
+    writeOptions 'Home Manager' ${(makePlatformsOptionsDoc homeManagerConfiguration)} src/options/platforms/home_manager.md
+    writeOptions 'NixOS' ${(makePlatformsOptionsDoc nixosConfiguration)} src/options/platforms/nixos.md
 
     mkdir --parents src/options/modules
     ${modulePageScript}
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index 7e6e5a18..1a052dd2 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -14,11 +14,15 @@
 - [Testbeds](testbeds.md)
 - [Style guide](styling.md)
 
-# Platforms
+# Reference
 
-- [Home Manager](options/global/home_manager.md)
-- [NixOS](options/global/nixos.md)
+<!--
+  The auto-generated list of modules is appended to this file, so this must
+  be the last section, and modules must be the last page, with no comments
+  following it. There must be a trailing newline.
+-->
 
-# Modules
-
-<!-- The auto-generated list of modules will be added below. -->
+- [Platforms]() <!-- TODO: migrate general platforms content to this page. -->
+  - [Home Manager](options/platforms/home_manager.md)
+  - [NixOS](options/platforms/nixos.md)
+- [Modules]() <!-- TODO: migrate general modules content to this page. -->
diff --git a/docs/src/options/global/home_manager.md b/docs/src/options/platforms/home_manager.md
similarity index 100%
rename from docs/src/options/global/home_manager.md
rename to docs/src/options/platforms/home_manager.md
diff --git a/docs/src/options/global/nixos.md b/docs/src/options/platforms/nixos.md
similarity index 100%
rename from docs/src/options/global/nixos.md
rename to docs/src/options/platforms/nixos.md