Adds custom styles for `<details>` and `<summary>` elements in Markdown content (#1735)

Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com>
Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

5 files changed, 106 insertions, 6 deletions

diff --git a/.changeset/proud-walls-thank.md b/.changeset/proud-walls-thank.md
new file mode 100644
index 00000000..5f4ede62
--- /dev/null
+++ b/.changeset/proud-walls-thank.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': minor
+---
+
+Adds custom styles for `<details>` and `<summary>` elements in Markdown content.
diff --git a/docs/src/content/docs/guides/authoring-content.md b/docs/src/content/docs/guides/authoring-content.md
index 4db1a916..2fe84815 100644
--- a/docs/src/content/docs/guides/authoring-content.md
+++ b/docs/src/content/docs/guides/authoring-content.md
@@ -361,6 +361,31 @@ A code block’s optional title can be set either with a `title="..."` attribute
   ```
   ````
 
+## Details
+
+Details (also known as “disclosures” or “accordions”) are useful to hide content that is not immediately relevant.
+Users can click a short summary to expand and view the full content.
+
+Use the standard HTML [`<details>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) and [`<summary>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary) elements in your Markdown content to create a disclosure widget.
+
+You can nest any other Markdown syntax inside a `<details>` element.
+
+<details>
+<summary>Where and when is the Andromeda constellation most visible?</summary>
+
+The [Andromeda constellation](<https://en.wikipedia.org/wiki/Andromeda_(constellation)>) is most visible in the night sky during the month of November at latitudes between `+90°` and `−40°`.
+
+</details>
+
+```md
+<details>
+<summary>Where and when is the Andromeda constellation most visible?</summary>
+
+The [Andromeda constellation](<https://en.wikipedia.org/wiki/Andromeda_(constellation)>) is most visible in the night sky during the month of November at latitudes between `+90°` and `−40°`.
+
+</details>
+```
+
 ## Other common Markdown features
 
 Starlight supports all other Markdown authoring syntax, such as lists and tables. See the [Markdown Cheat Sheet from The Markdown Guide](https://www.markdownguide.org/cheat-sheet/) for a quick overview of all the Markdown syntax elements.
diff --git a/package.json b/package.json
index b6e662ce..93e76227 100644
--- a/package.json
+++ b/package.json
@@ -37,7 +37,7 @@
     {
       "name": "/_astro/*.css",
       "path": "examples/basics/dist/_astro/*.css",
-      "limit": "14 kB"
+      "limit": "14.5 kB"
     }
   ]
 }
diff --git a/packages/starlight/style/asides.css b/packages/starlight/style/asides.css
index 026544d4..adbb0558 100644
--- a/packages/starlight/style/asides.css
+++ b/packages/starlight/style/asides.css
@@ -1,26 +1,26 @@
 .starlight-aside {
 	padding: 1rem;
-	border-inline-start: 0.25rem solid;
+	border-inline-start: 0.25rem solid var(--sl-color-asides-border);
 	color: var(--sl-color-white);
 }
 .starlight-aside--note {
 	--sl-color-asides-text-accent: var(--sl-color-blue-high);
-	border-color: var(--sl-color-blue);
+	--sl-color-asides-border: var(--sl-color-blue);
 	background-color: var(--sl-color-blue-low);
 }
 .starlight-aside--tip {
 	--sl-color-asides-text-accent: var(--sl-color-purple-high);
-	border-color: var(--sl-color-purple);
+	--sl-color-asides-border: var(--sl-color-purple);
 	background-color: var(--sl-color-purple-low);
 }
 .starlight-aside--caution {
 	--sl-color-asides-text-accent: var(--sl-color-orange-high);
-	border-color: var(--sl-color-orange);
+	--sl-color-asides-border: var(--sl-color-orange);
 	background-color: var(--sl-color-orange-low);
 }
 .starlight-aside--danger {
 	--sl-color-asides-text-accent: var(--sl-color-red-high);
-	border-color: var(--sl-color-red);
+	--sl-color-asides-border: var(--sl-color-red);
 	background-color: var(--sl-color-red-low);
 }
 
diff --git a/packages/starlight/style/markdown.css b/packages/starlight/style/markdown.css
index 1f065ff9..7d057de8 100644
--- a/packages/starlight/style/markdown.css
+++ b/packages/starlight/style/markdown.css
@@ -117,3 +117,73 @@
 	border: 0;
 	border-bottom: 1px solid var(--sl-color-hairline);
 }
+
+/* <details> and <summary> styles */
+.sl-markdown-content details:not(:where(.not-content *)) {
+	--sl-details-border-color: var(--sl-color-gray-5);
+
+	border-inline-start: 2px solid var(--sl-details-border-color);
+	padding-inline-start: 1rem;
+}
+.sl-markdown-content details:not([open]):hover:not(:where(.not-content *)),
+.sl-markdown-content details:has(> summary:hover):not(:where(.not-content *)) {
+	--sl-details-border-color: var(--sl-color-text-accent);
+}
+.sl-markdown-content summary:not(:where(.not-content *)) {
+	color: var(--sl-color-white);
+	cursor: pointer;
+	display: block; /* Needed to hide the default marker in some browsers. */
+	font-weight: 600;
+	/* Expand the outline so that the marker cannot distort it. */
+	margin-inline-start: -0.5rem;
+	padding-inline-start: 0.5rem;
+}
+.sl-markdown-content details[open] > summary:not(:where(.not-content *)) {
+	margin-bottom: 1rem;
+}
+
+/* <summary> marker styles */
+.sl-markdown-content summary:not(:where(.not-content *))::marker,
+.sl-markdown-content summary:not(:where(.not-content *))::-webkit-details-marker {
+	display: none;
+}
+.sl-markdown-content summary:not(:where(.not-content *))::before {
+	--sl-details-marker-size: 1.25rem;
+
+	background-color: currentColor;
+	content: '';
+	display: inline-block;
+	height: var(--sl-details-marker-size);
+	width: var(--sl-details-marker-size);
+	margin-inline: calc((var(--sl-details-marker-size) / 4) * -1) 0.25rem;
+	vertical-align: middle;
+	-webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M14.8 11.3 10.6 7a1 1 0 1 0-1.4 1.5l3.5 3.5-3.5 3.5a1 1 0 0 0 0 1.4 1 1 0 0 0 .7.3 1 1 0 0 0 .7-.3l4.2-4.2a1 1 0 0 0 0-1.4Z'/%3E%3C/svg%3E%0A");
+	mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M14.8 11.3 10.6 7a1 1 0 1 0-1.4 1.5l3.5 3.5-3.5 3.5a1 1 0 0 0 0 1.4 1 1 0 0 0 .7.3 1 1 0 0 0 .7-.3l4.2-4.2a1 1 0 0 0 0-1.4Z'/%3E%3C/svg%3E%0A");
+	-webkit-mask-repeat: no-repeat;
+	mask-repeat: no-repeat;
+}
+@media (prefers-reduced-motion: no-preference) {
+	.sl-markdown-content summary:not(:where(.not-content *))::before {
+		transition: transform 0.2s ease-in-out;
+	}
+}
+.sl-markdown-content details[open] > summary:not(:where(.not-content *))::before {
+	transform: rotateZ(90deg);
+}
+[dir='rtl'] .sl-markdown-content summary:not(:where(.not-content *))::before,
+.sl-markdown-content [dir='rtl'] summary:not(:where(.not-content *))::before {
+	transform: rotateZ(180deg);
+}
+/* <summary> with only a paragraph automatically added when using MDX */
+.sl-markdown-content summary:not(:where(.not-content *)) p:only-child {
+	display: inline;
+}
+
+/* <details> styles inside asides */
+.sl-markdown-content .starlight-aside details:not(:where(.not-content *)) {
+	--sl-details-border-color: var(--sl-color-asides-border);
+}
+.sl-markdown-content .starlight-aside details:not([open]):hover:not(:where(.not-content *)),
+.sl-markdown-content .starlight-aside details:has(> summary:hover):not(:where(.not-content *)) {
+	--sl-details-border-color: var(--sl-color-asides-text-accent);
+}