# How to Create Collapsible Details Blocks Using the DetailsDirective Component in Astro Big Doc > Learn how to create collapsible details blocks using the DetailsDirective component in Astro Big Doc. Transform your content with animated expand/collapse functionality. - Repository: [Micro Web Stacks/astro-big-doc](https://github.com/microwebstacks/astro-big-doc) - Tags: how-to-guide - Published: 2026-03-07 --- **The DetailsDirective component converts fenced Markdown blocks like `:::details{summary="..."}` into native HTML `
` elements with animated expand/collapse functionality.** The astro-big-doc repository provides a powerful custom Markdown directive system that enables authors to create interactive documentation components without writing HTML. One of the most useful features is the ability to create collapsible details blocks using the DetailsDirective component, which transforms declarative Markdown syntax into fully styled, accessible disclosure widgets. ## Understanding the DetailsDirective Component Architecture The DetailsDirective implementation follows a three-stage pipeline that processes custom Markdown directives through the AST transformation layer. ### How the Markdown Directive Is Parsed When astro-big-doc processes content files, it uses `mdast-util-to-hast` to parse Markdown into an abstract syntax tree. In `src/components/markdown/AstroMarkdown.astro`, the component detects nodes of type `containerDirective` with the name **details** and renders them using the ContainerDirective component. ### Component Dispatch Flow The `src/components/markdown/directive/ContainerDirective.astro` file acts as a router for directive types. When it encounters a directive named `details`, it forwards the node and its attributes to `DetailsDirective.astro`, passing along the summary text and child content through the component's props and slots. ## Syntax for Creating Collapsible Details Blocks Authors can create collapsible sections using a fenced container directive with the `details` identifier and an optional summary attribute. The Markdown syntax follows this pattern: ```markdown :::details{summary="Click to expand"} Your hidden content goes here. This can include paragraphs, lists, code blocks, or any other Markdown content. ::: ``` If you omit the summary attribute, the component defaults to displaying "Details…" as the clickable header. ## Implementing DetailsDirective in Your Astro Project There are two primary ways to utilize collapsible details blocks in your astro-big-doc implementation: through Markdown authoring or direct component import. ### Using the Markdown Syntax Place the fenced directive in any `.md` or `.mdx` file within your content directory: ```markdown :::details{summary="Why use collapsible sections?"} Collapsible details blocks help manage information density in documentation. Readers can expand sections relevant to their needs while keeping the page visually clean. - Reduces cognitive load - Improves page scanability - Maintains accessibility via native HTML details element ::: ``` The astro-big-doc pipeline automatically transforms this into the DetailsDirective component during the build process. ### Direct Component Import For use in `.astro` files where you need programmatic control, import the component directly from the directive directory: ```astro --- import DetailsDirective from '@/components/markdown/directive/DetailsDirective.astro'; ---

This content renders inside the collapsible block.

 ``` ## Customizing the DetailsDirective Appearance The `src/components/markdown/directive/DetailsDirective.astro` file contains scoped CSS that controls the visual presentation of collapsible blocks. The component renders the following HTML structure: ```html
{summary}
``` The CSS in the same file (lines 21-55) provides: - **Arrow animation**: The `.arrow` class rotates 90 degrees when the details element is in the open state - **Typography styling**: Consistent font sizing and spacing for the summary and content areas - **Layout constraints**: Proper padding and margins to integrate with the documentation theme To override these styles, target the `.directive` class or the specific `details` element in your global CSS or component-specific style blocks. ## Summary - The **DetailsDirective component** in astro-big-doc transforms fenced Markdown blocks into native HTML `
` elements with enhanced styling. - Use the syntax `:::details{summary="Your title"}` in any content file to create collapsible sections without writing HTML. - The component pipeline flows through `AstroMarkdown.astro` → `ContainerDirective.astro` → `DetailsDirective.astro`, with each layer handling specific transformation responsibilities. - Default styling includes an animated arrow indicator and responsive layout, customizable via scoped CSS in `DetailsDirective.astro`. ## Frequently Asked Questions ### What happens if I don't provide a summary attribute? If you omit the summary attribute in your Markdown directive, the DetailsDirective component automatically defaults to displaying "Details…" as the clickable header text. This fallback is defined in the component's prop handling logic within `src/components/markdown/directive/DetailsDirective.astro`. ### Can I nest other Markdown components inside a details block? Yes, the DetailsDirective supports full Markdown content nesting. You can include paragraphs, lists, code blocks, images, and even other custom directives inside the fenced `:::details` block. The content renders inside an `
` element within the details component, preserving all Markdown transformations. ### How do I change the arrow icon or animation style? The arrow icon and rotation animation are controlled by the scoped CSS within `DetailsDirective.astro` (lines 21-55). To customize the appearance, you can either modify the component file directly or override the `.arrow` and `.directive` classes in your global stylesheet. The component uses an SVG icon component (`Svgicons`) that you can replace with a different icon filename. ### Is the DetailsDirective accessible for screen readers? Yes, the component uses the native HTML `
` and `` elements, which are fully accessible and supported by modern screen readers. The semantic markup allows assistive technologies to announce the expandable nature of the content and notify users when the disclosure state changes, requiring no additional ARIA attributes for basic functionality.