feat: adds custom styles for <details> and <summary> elements in …

…markdown
HiDeoo · Apr 10, 2024 · 1a5d2e1 · 1a5d2e1
1 parent f264730
commit 1a5d2e1
Show file tree

Hide file tree

Showing 5 changed files with 340 additions and 5 deletions.
diff --git a/.changeset/proud-walls-thank.md 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
@@ -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 “accordion”) are useful to conceal information that is not immediately relevant to the user.
+The user can reveal further information with an interaction to toggle the visibility of the content.
+
+Starlight does not provide a custom Markdown syntax for details, but you can use the standard HTML `<details>` and `<summary>` elements to create them while authoring your Markdown content.
+
+You can nest any other Markdown content types inside a `<details>` element.
+
+<details>
+<summary>Where and when the Andromeda constellation is best visible?</summary>
+
+The [Andromeda constellation](<https://en.wikipedia.org/wiki/Andromeda_(constellation)>) is best visible in the night sky during the month of November at latitudes between `+90°` and `−40°`.
+
+</details>
+
+```md
+<details>
+<summary>Where and when the Andromeda constellation is best visible?</summary>
+
+The [Andromeda constellation](<https://en.wikipedia.org/wiki/Andromeda_(constellation)>) is best 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/docs/src/content/docs/reference/details.md b/docs/src/content/docs/reference/details.md
@@ -0,0 +1,242 @@
+---
+title: ⚠️ Details styles demo page ⚠️
+---
+
+:::danger
+// TODO(HiDeoo) Remove this page
+:::
+
+## Basics
+
+The following is a basic `<details>` element with no block content:
+
+<details>
+<summary>This is the summary</summary>
+This is the details content
+</details>
+
+The following is a basic `<details>` element with block content:
+
+<details>
+<summary>This is the summary</summary>
+
+This is the details content
+
+</details>
+
+## Opened by default
+
+The following is a `<details>` element opened by default:
+
+<details open>
+<summary>This is the summary</summary>
+This is the details content
+</details>
+
+## Long summary
+
+The following is a `<details>` element with a very long summary:
+
+<details>
+<summary>This is the very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very long summary</summary>
+This is the details content
+</details>
+
+## Long content
+
+The following is a `<details>` element with a very long content:
+
+<details>
+<summary>This is the summary</summary>
+
+This is the details content
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas euismod ante lorem, quis posuere massa sodales id. Donec a dapibus nisi, id volutpat lorem. Aenean eleifend nisl at ex feugiat, at vulputate lorem luctus. Aliquam eget accumsan ipsum. Maecenas ut elit hendrerit, sodales leo at, tincidunt elit. Nullam ut venenatis libero. In vel molestie tellus. Suspendisse vitae nibh in felis faucibus aliquet. Nunc tortor enim, pellentesque sit amet justo eget, auctor elementum enim. Nam posuere et ipsum lobortis porttitor. Proin consectetur ullamcorper augue, a fermentum neque dapibus eget. Praesent feugiat orci vulputate turpis mattis, eget placerat mi volutpat.
+
+Maecenas vehicula orci metus, quis dapibus turpis suscipit vitae. Nullam velit ante, convallis fermentum massa a, condimentum mattis lorem. Nunc interdum consequat mollis. Suspendisse semper diam tellus. Maecenas mollis congue mi, eu hendrerit dui hendrerit sed. Aliquam quis ornare dolor. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.
+
+Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Sed posuere arcu ut leo ultrices, in volutpat leo eleifend. Proin facilisis tempus maximus. Sed eu nulla ultricies, accumsan libero sed, commodo nunc. Curabitur sit amet metus vitae erat laoreet cursus et ut magna. Nam euismod justo a orci sagittis molestie. Phasellus et interdum ipsum, sed egestas ligula. Vestibulum congue eros ac neque posuere molestie. Nunc id enim aliquet, vestibulum diam at, fermentum justo.
+
+Duis ac mauris purus. Etiam viverra nisi vel facilisis eleifend. Ut dapibus, eros ac cursus faucibus, augue mi facilisis lacus, ut ullamcorper arcu diam eu nulla. Praesent tincidunt placerat augue eget cursus. Integer magna felis, malesuada in interdum eu, efficitur vel dolor. In feugiat nisl sit amet pharetra ullamcorper. Quisque odio ante, convallis a lectus id, consectetur finibus enim. Curabitur pretium quam ut lectus tristique, ac ornare lorem varius. Ut maximus aliquet est vitae hendrerit. In vitae massa mattis, volutpat dui sagittis, semper arcu. In a ligula tincidunt, elementum nisi ut, tincidunt odio. Etiam accumsan massa a justo convallis blandit. Integer in felis arcu. Nullam id felis et velit blandit convallis vitae a turpis. Nunc vitae erat ac ipsum mattis rutrum nec ut justo. Mauris ullamcorper id metus nec pretium.
+
+Donec purus nibh, ornare ac sagittis porta, porta ac neque. Donec efficitur dictum nibh et hendrerit. Mauris gravida mollis leo posuere posuere. In hac habitasse platea dictumst. Interdum et malesuada fames ac ante ipsum primis in faucibus. Aenean sit amet massa felis. Fusce lectus neque, auctor quis est et, interdum lobortis ante. Nulla aliquet euismod libero, sit amet maximus orci mattis eu. Nullam sed cursus felis. Sed dapibus faucibus dolor, id volutpat eros varius a.
+
+</details>
+
+## Interleaved content
+
+The following are two `<details>` elements with a code block in between:
+
+<details>
+<summary>This is the summary</summary>
+This is the details content
+</details>
+
+```js
+console.log('some content in between');
+```
+
+<details>
+<summary>This is the summary</summary>
+This is the details content
+</details>
+
+## Markdown content
+
+The following is a `<details>` element with markdown content:
+
+<details>
+<summary>This is the summary</summary>
+
+This is the details content
+
+```ts
+console.log('Hello world');
+```
+
+This is `a` paragraph.
+
+:::note
+This is a note
+:::
+
+</details>
+
+## Uncontrolled accordion
+
+The following are `<details>` elements forming an uncontrolled accordion, where each `<details>` element can be opened or closed independently:
+
+<details>
+<summary>This is the summary (1)</summary>
+This is the details content (1)
+</details>
+
+<details>
+<summary>This is the summary (2)</summary>
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas euismod ante lorem, quis posuere massa sodales id. Donec a dapibus nisi, id volutpat lorem. Aenean eleifend nisl at ex feugiat, at vulputate lorem luctus. Aliquam eget accumsan ipsum. Maecenas ut elit hendrerit, sodales leo at, tincidunt elit. Nullam ut venenatis libero. In vel molestie tellus. Suspendisse vitae nibh in felis faucibus aliquet. Nunc tortor enim, pellentesque sit amet justo eget, auctor elementum enim. Nam posuere et ipsum lobortis porttitor. Proin consectetur ullamcorper augue, a fermentum neque dapibus eget. Praesent feugiat orci vulputate turpis mattis, eget placerat mi volutpat.
+</details>
+
+<details>
+<summary>This is the summary (3)</summary>
+Maecenas vehicula orci metus, quis dapibus turpis suscipit vitae. Nullam velit ante, convallis fermentum massa a, condimentum mattis lorem. Nunc interdum consequat mollis. Suspendisse semper diam tellus. Maecenas mollis congue mi, eu hendrerit dui hendrerit sed. Aliquam quis ornare dolor. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.
+</details>
+
+## Controlled accordion
+
+The following are `<details>` elements forming an controlled accordion, where only one `<details>` element can be opened at a time:
+
+:::caution
+Note that this feature is not supported in Firefox.
+:::
+
+<details name="controlled-details">
+<summary>This is the summary (1)</summary>
+This is the details content (1)
+</details>
+
+<details name="controlled-details">
+<summary>This is the summary (2)</summary>
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas euismod ante lorem, quis posuere massa sodales id. Donec a dapibus nisi, id volutpat lorem. Aenean eleifend nisl at ex feugiat, at vulputate lorem luctus. Aliquam eget accumsan ipsum. Maecenas ut elit hendrerit, sodales leo at, tincidunt elit. Nullam ut venenatis libero. In vel molestie tellus. Suspendisse vitae nibh in felis faucibus aliquet. Nunc tortor enim, pellentesque sit amet justo eget, auctor elementum enim. Nam posuere et ipsum lobortis porttitor. Proin consectetur ullamcorper augue, a fermentum neque dapibus eget. Praesent feugiat orci vulputate turpis mattis, eget placerat mi volutpat.
+</details>
+
+<details name="controlled-details">
+<summary>This is the summary (3)</summary>
+Maecenas vehicula orci metus, quis dapibus turpis suscipit vitae. Nullam velit ante, convallis fermentum massa a, condimentum mattis lorem. Nunc interdum consequat mollis. Suspendisse semper diam tellus. Maecenas mollis congue mi, eu hendrerit dui hendrerit sed. Aliquam quis ornare dolor. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.
+</details>
+
+## Nested details
+
+The following is a `<details>` element with a nested `<details>` element:
+
+<details>
+<summary>This is the summary</summary>
+
+This is the details content
+
+<details>
+<summary>This is the nested summary</summary>
+This is the nested details content
+</details>
+
+And some content after the nested details
+
+</details>
+
+## `not-content` class
+
+<div class="not-content">
+
+<p>The following is a <code>&lt;details&gt;</code> element wrapped with the <code>not-content</code> CSS class:</p>
+
+<br>
+
+<details>
+<summary>This is the summary</summary>
+This is the details content
+</details>
+
+</div>
+
+## RTL
+
+The following is a `<details>` element nested in a block in RTL:
+
+<div dir="rtl">
+
+<details>
+<summary>This is the summary</summary>
+This is the details content
+</details>
+
+</div>
+
+The following is a `<details>` element in RTL:
+
+<details dir="rtl">
+<summary>This is the summary</summary>
+With a summary and some details not in a paragraph
+</details>
+
+## Asides
+
+The following are `<details>` elements nested in asides:
+
+:::note
+This is the note aside content
+
+<details>
+<summary>This is the summary</summary>
+This is the details content
+</details>
+
+:::
+
+:::tip
+This is the tip aside content
+
+<details>
+<summary>This is the summary</summary>
+This is the details content
+</details>
+
+:::
+
+:::caution
+This is the caution aside content
+
+<details>
+<summary>This is the summary</summary>
+This is the details content
+</details>
+
+:::
+
+:::danger
+This is the danger aside content
+
+<details>
+<summary>This is the summary</summary>
+This is the details content
+</details>
+
+:::
diff --git 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
@@ -113,3 +113,66 @@
 	border: 0;
 	border-bottom: 1px solid var(--sl-color-hairline);
 }
+
+.sl-markdown-content details:not(:where(.not-content *)) {
+	--sl-details-x-pad: 1rem;
+	--sl-details-y-pad: 0.75rem;
+	--sl-details-border-color: var(--sl-color-gray-5);
+	--sl-details-open-summary-bg-color: var(--sl-color-gray-6);
+
+	border-block: 1px solid var(--sl-details-border-color);
+	padding: var(--sl-details-y-pad) var(--sl-details-x-pad);
+}
+[data-theme='light'] .sl-markdown-content details:not(:where(.not-content *)) {
+	--sl-details-open-summary-bg-color: var(--sl-color-gray-7);
+}
+.sl-markdown-content summary:not(:where(.not-content *)) {
+	align-items: center;
+	border-inline: 1px solid transparent;
+	color: var(--sl-color-white);
+	cursor: pointer;
+	display: flex;
+	gap: 0.5rem;
+	justify-content: space-between;
+	margin: calc(-1 * var(--sl-details-y-pad)) calc(-1 * var(--sl-details-x-pad));
+	padding: var(--sl-details-y-pad) var(--sl-details-x-pad);
+}
+.sl-markdown-content details[open] > summary:not(:where(.not-content *)) {
+	background-color: var(--sl-details-open-summary-bg-color);
+	border-bottom: 1px solid;
+	border-color: var(--sl-details-border-color);
+	margin-bottom: var(--sl-details-y-pad);
+}
+.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 *))::after {
+	background-color: currentColor;
+	content: '';
+	flex-shrink: 0;
+	height: 1.5rem;
+	width: 1.5rem;
+	mask-image: url('data:image/svg+xml;base64,PHN2ZyB4bWxucz0naHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmcnIHZpZXdCb3g9JzAgMCAyNCAyNCc+PHBhdGggZD0ibTE0LjgzIDExLjI5LTQuMjQtNC4yNGExIDEgMCAxIDAtMS40MiAxLjQxTDEyLjcxIDEybC0zLjU0IDMuNTRhMSAxIDAgMCAwIDAgMS40MSAxIDEgMCAwIDAgLjcxLjI5IDEgMSAwIDAgMCAuNzEtLjI5bDQuMjQtNC4yNGExLjAwMiAxLjAwMiAwIDAgMCAwLTEuNDJaIi8+PC9zdmc+');
+	mask-repeat: no-repeat;
+}
+@media (prefers-reduced-motion: no-preference) {
+	.sl-markdown-content summary:not(:where(.not-content *))::after {
+		transition: transform 0.2s ease-in-out;
+	}
+}
+.sl-markdown-content details[open] > summary:not(:where(.not-content *))::after {
+	transform: rotateZ(90deg);
+}
+[dir='rtl'] .sl-markdown-content summary:not(:where(.not-content *))::after,
+.sl-markdown-content [dir='rtl'] summary:not(:where(.not-content *))::after {
+	transform: rotateZ(180deg);
+}
+.sl-markdown-content details + details:not(:where(.not-content *)) {
+	border-top: 0;
+	margin-top: 0;
+}
+.sl-markdown-content .starlight-aside details:not(:where(.not-content *)) {
+	--sl-details-border-color: var(--sl-color-asides-border);
+	--sl-details-open-summary-bg-color: transparent;
+}