Skip to content

Commit 858c290

Browse files
coatlesscoatless
committed
Roll out improved docs for details extension
1 parent ac455f6 commit 858c290

14 files changed

Lines changed: 1362 additions & 11 deletions

‎README.md‎

Lines changed: 261 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,13 @@ Content here.
8080
:::
8181
````
8282

83+
84+
## Features
85+
86+
The `details` extension is highly configurable across interactive (HTML)
87+
and non-interactive (PDF, Word, Typst) formats. The next subsections
88+
describe the available features and possible configurations.
89+
8390
### Open by default
8491

8592
Add the `open="true"` attribute to make the details open by default:
@@ -90,6 +97,258 @@ This content is visible by default.
9097
:::
9198
```
9299

93-
# License
100+
### Custom ID for deep linking
101+
102+
Add an ID to enable direct linking to the details section:
103+
104+
```markdown
105+
::: {#installation-steps .details summary="Installation Steps"}
106+
Step-by-step installation guide...
107+
:::
108+
```
109+
110+
Users can then link directly to this section with `#installation-steps`.
111+
112+
### Accordion Groups
113+
114+
Create accordion-style behavior where details elements in the same group interact with each other. Two modes are available:
115+
116+
#### Exclusive Mode (Default)
117+
118+
Only one details element can be open at a time within a group. When a user opens one section, any other open section in the same group automatically closes. This uses the native HTML `name` attribute.
119+
120+
```markdown
121+
::: {.details summary="Section 1" group="faq"}
122+
Content for section 1.
123+
:::
124+
125+
::: {.details summary="Section 2" group="faq"}
126+
Content for section 2.
127+
:::
128+
129+
::: {.details summary="Section 3" group="faq"}
130+
Content for section 3.
131+
:::
132+
```
133+
134+
#### Synchronized Mode
135+
136+
All details elements in a group open and close together. When a user toggles one section, all other sections in the same group follow.
137+
138+
```markdown
139+
::: {.details summary="Chapter 1 Notes" group="notes" accordion-mode="synchronized"}
140+
Notes for chapter 1.
141+
:::
142+
143+
::: {.details summary="Chapter 2 Notes" group="notes" accordion-mode="synchronized"}
144+
Notes for chapter 2.
145+
:::
146+
147+
::: {.details summary="Chapter 3 Notes" group="notes" accordion-mode="synchronized"}
148+
Notes for chapter 3.
149+
:::
150+
```
151+
152+
#### Global Accordion Mode
153+
154+
Set the default accordion mode for all groups in the document:
155+
156+
```yaml
157+
---
158+
extensions:
159+
details:
160+
interactive:
161+
accordion-mode: "synchronized" # or "exclusive" (default)
162+
---
163+
```
164+
165+
> [!NOTE]
166+
>
167+
> Accordion groups only apply to interactive (HTML) formats.
168+
> In non-interactive formats, all sections display normally.
169+
170+
### Conditional Content
171+
172+
Show different content based on whether the output format is interactive (HTML) or non-interactive (PDF, Word, etc.).
173+
174+
#### Inside details blocks
175+
176+
```markdown
177+
::: {.details summary="Interactive Demo"}
178+
179+
::: {.interactive-only}
180+
<iframe src="https://example.com/demo" width="100%" height="400"></iframe>
181+
Try the interactive demo above!
182+
:::
183+
184+
::: {.non-interactive-only}
185+
Visit the online documentation at https://example.com/demo to try the interactive demo.
186+
:::
187+
188+
:::
189+
```
190+
191+
### Expand/Collapse Controls
192+
193+
Add document-wide buttons to expand or collapse all details sections at once:
194+
195+
```yaml
196+
---
197+
extensions:
198+
details:
199+
interactive:
200+
show-controls: true
201+
controls-position: "top" # "top", "bottom", or "both"
202+
---
203+
```
204+
205+
#### Control Positions
206+
207+
| Position | Description |
208+
|----------|-------------|
209+
| `"top"` | Controls appear at the beginning of the document (default) |
210+
| `"bottom"` | Controls appear at the end of the document |
211+
| `"both"` | Controls appear at both the beginning and end |
212+
213+
#### Customizing Button Text
214+
215+
Customize the button labels:
216+
217+
```yaml
218+
---
219+
extensions:
220+
details:
221+
interactive:
222+
show-controls: true
223+
controls-expand-text: "Show all sections"
224+
controls-collapse-text: "Hide all sections"
225+
---
226+
```
227+
228+
> [!NOTE]
229+
>
230+
> Controls only appear in interactive (HTML) formats
231+
> and only when the document contains at least one details block.
232+
233+
### Format-Specific Behavior
234+
235+
The extension automatically detects whether the output format is interactive (HTML-based) or non-interactive (PDF, Word, Typst, etc.) and adjusts its behavior accordingly.
236+
237+
#### Interactive Formats (HTML, RevealJS, etc.)
238+
239+
For HTML-based formats, the extension generates native `<details>` and `<summary>` elements with:
240+
241+
- Full Markdown formatting support in summaries
242+
- Accordion group support via the `name` attribute
243+
- Accessibility attributes (`aria-label`, `id`)
244+
245+
#### Non-Interactive Formats (PDF, Word, Typst, etc.)
246+
247+
For non-interactive formats, the extension uses Quarto's Callout API to display the content. You can configure how details blocks appear using the `display` option:
248+
249+
| Display Mode | Description |
250+
|--------------|-------------|
251+
| `"show"` | Shows the full content in a callout block (default) |
252+
| `"placeholder"` | Shows a callout with placeholder text indicating interactive content was removed |
253+
| `"remove"` | Completely removes the details block from the output |
254+
255+
## Global Configuration
256+
257+
Configure the extension in your document's YAML front matter using the `extensions.details` key:
258+
259+
```yaml
260+
---
261+
extensions:
262+
details:
263+
debug: false # Enable verbose logging
264+
interactive:
265+
open: false # Default open state for HTML
266+
summary: "Click to expand" # Default summary text for HTML
267+
accordion-mode: "exclusive" # "exclusive" or "synchronized"
268+
show-controls: false # Show expand/collapse all buttons
269+
controls-position: "top" # "top", "bottom", or "both"
270+
controls-expand-text: "Expand all"
271+
controls-collapse-text: "Collapse all"
272+
non-interactive:
273+
display: "show" # "show", "placeholder", or "remove"
274+
summary: "Details" # Default summary text for non-interactive
275+
placeholder-text: "Interactive content not available in this format."
276+
callout-type: "note" # Callout style: note, warning, tip, caution, important
277+
---
278+
```
279+
280+
### Instance-Level Attributes
281+
282+
Override global settings on individual details blocks:
283+
284+
#### For Interactive Formats
285+
286+
```markdown
287+
::: {#my-details .details summary="Custom summary" open="true" group="accordion-1"}
288+
This block has a custom ID, is open by default, and belongs to an accordion group.
289+
:::
290+
```
291+
292+
#### Different Summary Text for Non-Interactive
293+
294+
Use `non-interactive-summary` to specify alternative summary text for non-interactive formats:
295+
296+
````markdown
297+
::: {.details summary="Click to expand code" non-interactive-summary="Code Example"}
298+
```python
299+
print("Hello, World!")
300+
```
301+
:::
302+
````
94303

95-
AGPL (>= 3)
304+
In HTML, the summary will be "Click to expand code". In PDF/Word, the callout title will be "Code Example".
305+
306+
## Attribute Reference
307+
308+
### Div-Level Attributes
309+
310+
| Attribute | Values | Description |
311+
|-----------|--------|-------------|
312+
| `id` | identifier | Custom ID for deep linking (auto-generated if not provided) |
313+
| `summary` | text | Summary/title text (highest priority, plain text) |
314+
| `open` | `"true"`, `"false"` | Initial open state (HTML only) |
315+
| `group` | string | Accordion group name (HTML only) |
316+
| `accordion-mode` | `"exclusive"`, `"synchronized"` | Accordion behavior mode (HTML only) |
317+
| `display` | `"show"`, `"placeholder"`, `"remove"` | Non-interactive display mode |
318+
| `placeholder-text` | text | Custom placeholder message |
319+
| `callout-type` | `"note"`, `"warning"`, `"tip"`, `"caution"`, `"important"` | Callout style for non-interactive |
320+
| `non-interactive-summary` | text | Alternative summary for non-interactive formats |
321+
322+
### Global Options (extensions.details)
323+
324+
| Option | Default | Description |
325+
|--------|---------|-------------|
326+
| `debug` | `false` | Enable verbose logging |
327+
328+
### Global Options (extensions.details.interactive)
329+
330+
| Option | Default | Description |
331+
|--------|---------|-------------|
332+
| `open` | `false` | Default open state for all details blocks |
333+
| `summary-text` | `"Click to expand"` | Default summary text when none specified |
334+
| `accordion-mode` | `"exclusive"` | Default accordion behavior: `"exclusive"` (one open at a time) or `"synchronized"` (all toggle together) |
335+
| `show-controls` | `false` | Show expand/collapse all buttons |
336+
| `controls-position` | `"top"` | Position of controls: `"top"`, `"bottom"`, or `"both"` |
337+
| `controls-expand-text` | `"Expand all"` | Text for the expand all button |
338+
| `controls-collapse-text` | `"Collapse all"` | Text for the collapse all button |
339+
340+
### Global Options (extensions.details.non-interactive)
341+
342+
| Option | Default | Description |
343+
|--------|---------|-------------|
344+
| `display` | `"show"` | Default display mode |
345+
| `non-interactive-summary` | `"Details"` | Default summary/title text |
346+
| `placeholder-text` | `"Interactive content not available in this format."` | Default placeholder message |
347+
| `callout-type` | `"note"` | Default callout type |
348+
349+
### Conditional Content Classes
350+
351+
| Class | Description |
352+
|-------|-------------|
353+
| `.interactive-only` | Content shown only in HTML formats |
354+
| `.non-interactive-only` | Content shown only in PDF, Word, Typst, etc. |

‎_extensions/details/details.lua‎

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -493,13 +493,6 @@ local function remove_summary_div(content)
493493
return content
494494
end
495495

496-
--- Summary extraction result structure.
497-
-- Contains both HTML and plain text versions of the summary.
498-
-- @class SummaryResult
499-
-- @field html string HTML representation of summary (for interactive formats)
500-
-- @field plain string Plain text representation (for non-interactive callout titles)
501-
-- @field source string Source of summary: "attribute", "div", "heading", or "default"
502-
503496
--- Extracts summary information from a details div element.
504497
-- Returns both HTML and plain text versions for different output formats.
505498
-- Priority order: 1) summary attribute, 2) summary div, 3) first heading, 4) default.

‎docs/_quarto.yml‎

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,42 @@ website:
1010
logo: "details-animated-logo.svg"
1111
logo-alt: "A hexagon logo for the details extension."
1212
style: "floating"
13+
collapse-level: 3
1314
search: true
1415
tools:
1516
- icon: github
1617
href: https://github.com/coatless-quarto/details/
1718
contents:
1819
- text: "Home"
1920
file: index.qmd
21+
- section: "Examples"
22+
contents:
23+
- section: "Getting Started"
24+
contents:
25+
- text: Quickstart
26+
href: qdetails-quickstart.qmd
27+
- text: Open by Default
28+
href: qdetails-open-default.qmd
29+
- section: "Accordion"
30+
contents:
31+
- text: Exclusive Mode
32+
href: qdetails-accordion-exclusive.qmd
33+
- text: Synchronized Mode
34+
href: qdetails-accordion-synchronized.qmd
35+
- section: "Advanced"
36+
contents:
37+
- text: Rich Summaries
38+
href: qdetails-rich-summaries.qmd
39+
- text: Conditional Content
40+
href: qdetails-conditional-content.qmd
41+
- text: Expand/Collapse Controls
42+
href: qdetails-controls.qmd
43+
- text: Custom IDs
44+
href: qdetails-custom-ids.qmd
45+
- section: "Formats"
46+
contents:
47+
- text: Display Modes
48+
href: qdetails-display-modes.qmd
2049
- section: "Support"
2150
contents:
2251
- text: "FAQ"
@@ -26,7 +55,7 @@ website:
2655
- section: "Extra"
2756
contents:
2857
- qdetails-release-notes.qmd
29-
58+
callout-appearance: simple
3059
format:
3160
html:
3261
toc: true

0 commit comments

Comments
 (0)