Background
The Flutter team is decoupling the material and cupertino libraries into independent packages. As part of this transition, their API documentation will use standard pub.dev generation processes. This decoupling work is scheduled to complete around June 2026.
While we want to use standard generation processes where possible, some visual elements are necessary to maintain the usability of the documentation.
The need for a styled example container
Flutter API documentation has historically enclosed code examples inside a blue container. We evaluated this design and concluded that this container is important for readability. This makes the container a blocking requirement for our decoupling plans.
We explored alternative implementations, such as using blockquote highlights. However, the visual distinction is insufficient, and the @example directive does not parse correctly inside a blockquote.
To resolve this, we propose adding support for a custom <example> HTML tag.
Proposed implementation
Because markdown supports raw HTML tags, this approach does not require complex changes to the dartdoc parser. It only requires adding CSS rules to dartdoc to style the <example> tag as a styled container.
We understand that adding styles specifically for Flutter can increase the maintenance burden of dartdoc. We propose this CSS-only approach because it is self-contained and minimizes changes to the core codebase.
Below is the CSS we have tested and verified:
example {
padding: 10px;
overflow: auto;
display: block;
unicode-bidi: isolate;
margin: 1em 0;
}
example p {
margin: 8px 40px 12px 8px;
}
example pre {
margin: 0;
}
example code.hljs {
max-height: 500px;
}
.light-theme example {
background-color: rgb(215, 235, 252);
}
.dark-theme example {
background-color: rgb(30, 40, 51);
}Below is how API doc will look like in practice:
///
/// <example>
///
/// This example shows a toggleable [CupertinoSwitch]. When the thumb slides to
/// the other side of the track, the switch is toggled between on/off.
///
/// {@example /examples/api/switch/cupertino_switch.0.dart}
///
/// </example>
///
We would appreciate your feedback on this approach.
Background
The Flutter team is decoupling the material and cupertino libraries into independent packages. As part of this transition, their API documentation will use standard pub.dev generation processes. This decoupling work is scheduled to complete around June 2026.
While we want to use standard generation processes where possible, some visual elements are necessary to maintain the usability of the documentation.
The need for a styled example container
Flutter API documentation has historically enclosed code examples inside a blue container. We evaluated this design and concluded that this container is important for readability. This makes the container a blocking requirement for our decoupling plans.
We explored alternative implementations, such as using blockquote highlights. However, the visual distinction is insufficient, and the
@exampledirective does not parse correctly inside a blockquote.To resolve this, we propose adding support for a custom
<example>HTML tag.Proposed implementation
Because markdown supports raw HTML tags, this approach does not require complex changes to the dartdoc parser. It only requires adding CSS rules to dartdoc to style the
<example>tag as a styled container.We understand that adding styles specifically for Flutter can increase the maintenance burden of dartdoc. We propose this CSS-only approach because it is self-contained and minimizes changes to the core codebase.
Below is the CSS we have tested and verified:
Below is how API doc will look like in practice:
We would appreciate your feedback on this approach.