Quarto Semantic Components is a small collection of reusable Markdown/Pandoc primitives for technical documentation. The components stay close to ordinary Markdown, become richer in HTML, and remain readable when rendered to PDF or DOCX.
This page is both a gallery and a usage guide. Every example follows the same pattern: source first, rendered output second.
Responsive sinuous SVG road with horizontal/vertical layouts
circle-list
Compact ordered lists
Circled numbers
tree
Generic hierarchies and classifications
Connectors and expandable branches
git-tree
Git histories, branches and merges
SVG commit DAG
file-tree
Project layouts and repository structure
Icons, info hints, expandable folders
properties
Key/value metadata
Responsive description-list grid
article
Self-contained blocks of content
Rounded container, accent, collapse/expand
progress / meter
Quantitative indicators
Native HTML indicators
kbd / abbr
Inline semantics
Native <kbd> and <abbr> elements
The extension intentionally avoids components that Quarto already handles well. A timeline can be expressed with steps type="dots"; roadmap is reserved for milestone paths and project journeys where the route itself is part of the presentation. General diagrams can use Mermaid.
Quick start
Install the extension:
quarto add lsbjordao/quarto-semantic-components
Enable it in a document or project:
filters:- semantic-components
Then use any component directly in Markdown:
:::steps## InstallInstall the extension.## ConfigureSet project defaults if needed.## WriteUse ordinary Markdown inside components.## RenderRender to HTML, PDF, or DOCX.:::
Project defaults in _quarto.yml
Component defaults can be centralized at the project level. This repository intentionally leaves most colors automatic so Quarto can choose values that work naturally in both light and dark themes.
Color options support a common light/dark convention. The unsuffixed option remains the fallback for both themes; -light and -dark override it only in the corresponding color mode.
steps turns headings into a structured sequence. The same source remains meaningful without the HTML styling, which makes it suitable for tutorials, protocols, workflows, and teaching material.
Numbered steps
The numbered mode uses a continuous connector behind the numbered markers. The marker interior follows the current surface, so the line does not show through the circle.
:::steps## Install the extensionRun `quarto add lsbjordao/quarto-semantic-components`.## Enable the filterAdd `semantic-components` to `filters`.## Configure the projectSet defaults in `_quarto.yml` when useful.## Write normallyEach heading starts a new step.:::
Output:
Install the extension
Run quarto add lsbjordao/quarto-semantic-components.
Enable the filter
Add semantic-components to filters.
Configure the project
Set defaults in _quarto.yml when useful.
Write normally
Each heading starts a new step.
Numbered steps on a custom surface
When you choose explicit colors, use theme-specific values if the light and dark themes need different contrast.
::: {.steps surface-color-light="#f3f4f6" surface-color-dark="#2b3035" line-color-light="#6b7280" line-color-dark="#adb5bd" line-width="2px"}## PrepareCreate the working directory.## ImportLoad the source data.## ValidateCheck required fields.## ExportWrite the validated result.:::
Output:
Prepare
Create the working directory.
Import
Load the source data.
Validate
Check required fields.
Export
Write the validated result.
Dot steps
Dot steps are useful when the sequence should feel lighter than a numbered procedure. The connector remains continuous behind the dots, while the marker center masks the line.
Default dots
With no explicit colors, the component follows the current theme automatically.
::: {.steps type="dots"}## ExtractDownload the data.## ValidateValidate the records.## TransformPrepare the data.## PublishPublish the result.:::
Output:
Extract
Download the data.
Validate
Validate the records.
Transform
Prepare the data.
Publish
Publish the result.
Per-step color and size
Block attributes define defaults; heading attributes override individual nodes. Theme suffixes can also be used on individual headings.
::: {.steps type="dots" dot-size="0.78rem" line-width="1.5px"}## Extract {dot-color-light="#2563eb" dot-color-dark="#60a5fa"}Download the new records.## Deduplicate {dot-color-light="#d97706" dot-color-dark="#fbbf24" dot-size="0.95rem"}Reconcile collections and identifications.## Review {dot-color-light="#7c3aed" dot-color-dark="#c4b5fd"}Review the processed dataset.## Publish {dot-color-light="#15803d" dot-color-dark="#4ade80"}Update the curated dataset.:::
Output:
Extract
Download the new records.
Deduplicate
Reconcile collections and identifications.
Review
Review the processed dataset.
Publish
Update the curated dataset.
Filled and hollow states
::: {.steps type="dots" line-width="2px"}## PendingThe default node remains hollow.## In progress {dot-color="#2563eb" dot-fill="#2563eb"}A single unsuffixed color is intentionally reused in both themes.## Under review {dot-color-light="#d97706" dot-fill-light="#d97706" dot-color-dark="#fbbf24" dot-fill-dark="#fbbf24"}This state uses separate light and dark colors.## Completed {dot-color-light="#15803d" dot-fill-light="#15803d" dot-color-dark="#4ade80" dot-fill-dark="#4ade80" dot-border-width="2px"}The final stage is complete.:::
Output:
Pending
The default node remains hollow.
In progress
A single unsuffixed color is intentionally reused in both themes.
Under review
This state uses separate light and dark colors.
Completed
The final stage is complete.
Timeline pattern
A timeline does not need a dedicated component. Dates can be represented with inline badges while steps type="dots" provides the vertical timeline geometry.
::: {.steps type="dots" line-width="2px" dot-size="0.78rem"}## [2024]{.badge type="success" appearance="outline" size="xs"} Prototype {dot-color="#16a34a"}First implementation of the component.## [2025]{.badge type="info" appearance="outline" size="xs"} Beta {dot-color="#2563eb"}Validation and visual refinement.## [2026-06]{.badge type="warning" appearance="outline" size="xs"} Release candidate {dot-color="#f59e0b"}API freeze for final testing.## [2026-09]{.badge type="success" appearance="solid" size="xs"} Release {dot-color="#16a34a"}Stable version released.:::
Output:
2024 Prototype
First implementation of the component.
2025 Beta
Validation and visual refinement.
2026-06 Release candidate
API freeze for final testing.
2026-09 Release
Stable version released.
Roadmap
roadmap is for milestone paths and project journeys where the route itself carries part of the visual meaning. In HTML the route is a responsive SVG: the outer road bed stays continuous while the narrower center line is dashed by default, which gives the curve a road-like appearance. Horizontal roadmaps automatically become vertical on narrow screens.
Roadmap of this extension
The first example uses the component to describe Quarto Semantic Components itself and links to the other rendered formats.
::: {.roadmap orientation="horizontal" curve="0.65" markers="dot"}::: {.roadmap-item title="Semantic core" status="done"}Pandoc-AST components that remain meaningful outside HTML.:::::: {.roadmap-item title="Component library" status="done"}Steps, trees, badges, articles, properties, progress, meter, `kbd`, `abbr`, and roadmap.:::::: {.roadmap-item title="Cross-format outputs" status="done"}Open the [PDF](quarto-semantic-components.pdf) or [DOCX](quarto-semantic-components.docx) version of this gallery.:::::: {.roadmap-item title="Version 0.1.0" status="milestone"}A coherent first release with theme-aware colors and graceful degradation.:::::: {.roadmap-item title="Next iterations" status="future"}Refine components from real documentation use and add only primitives that earn their place.::::::
Output:
Status: done
Semantic core
Pandoc-AST components that remain meaningful outside HTML.
A coherent first release with theme-aware colors and graceful degradation.
Status: future
Next iterations
Refine components from real documentation use and add only primitives that earn their place.
Vertical orientation
orientation="vertical" keeps the same curved-road idea while moving the road into a left-side gutter. It does not require a separate component.
::: {.roadmap orientation="vertical" markers="numbers" curve="0.8"}::: {.roadmap-item title="Install" status="done"}Add the extension to a Quarto project.:::::: {.roadmap-item title="Configure" status="done"}Set project defaults in `_quarto.yml`.:::::: {.roadmap-item title="Compose" status="current"}Use semantic components in Markdown.:::::: {.roadmap-item title="Publish" status="future"}Render the project to the required formats.::::::
The visual proportions are independent. road-background-width controls the continuous outer road bed; road-width controls the dashed center line; road-dash controls its dash pattern; and point-size controls the marker.
Set road-dash="none" when a continuous center line is desired. The outer road bed remains continuous in either case.
::: {.roadmap road-dash="none" road-background-width="14px" road-width="3px"}::: {.roadmap-item title="Continuous"}No center dashes.:::::: {.roadmap-item title="Still a road"}The outer road bed remains continuous.:::::: {.roadmap-item title="Finish"}Same geometry.::::::
Output:
Continuous
No center dashes.
Still a road
The outer road bed remains continuous.
Finish
Same geometry.
Theme-aware colors
road-color, point-color, and surface-color follow the extension-wide color rule: the unsuffixed property applies to both modes and -light / -dark can override it for one theme.
::: {.roadmap road-color-light="#64748b" road-color-dark="#cbd5e1" point-color-light="#2563eb" point-color-dark="#60a5fa" surface-color-light="#ffffff" surface-color-dark="#212529" curve="0.7"}::: {.roadmap-item title="Default point" status="done"}Uses the roadmap-level point color.:::::: {.roadmap-item title="Per-item override" status="current" point-color-light="#7c3aed" point-color-dark="#c4b5fd"}This item overrides only its marker color.:::::: {.roadmap-item title="Future" status="future" point-color="#16a34a"}An unsuffixed value is reused in both themes.::::::
Output:
Status: done
Default point
Uses the roadmap-level point color.
Status: current
Per-item override
This item overrides only its marker color.
Status: future
Future
An unsuffixed value is reused in both themes.
Roadmap option reference
Option
Accepted values / purpose
Default
Aliases
orientation
horizontal, vertical
horizontal
direction, layout
curve
0 to 1
0.6
curvature, sinuosity
markers
dot, numbers, none
dot
marker, marker-style
road-color
CSS color
automatic
line-color, path-color
road-color-light
light-theme road color
fallback
line-color-light, path-color-light
road-color-dark
dark-theme road color
fallback
line-color-dark, path-color-dark
point-color
CSS marker color
automatic
marker-color, dot-color
point-color-light
light-theme marker color
fallback
marker-color-light, dot-color-light
point-color-dark
dark-theme marker color
fallback
marker-color-dark, dot-color-dark
surface-color
card / marker surface
automatic
card-color, card-background
surface-color-light
light-theme surface
fallback
card-color-light, card-background-light
surface-color-dark
dark-theme surface
fallback
card-color-dark, card-background-dark
road-width
center-line width
3px
line-width, path-width
road-background-width
continuous road-bed width
10px
road-bed-width, path-background-width
road-dash
SVG dash pattern or none
10px 8px
dash, dash-pattern, line-dash
point-size
marker diameter
14px
marker-size, dot-size
Per .roadmap-item, title creates the card title, status accepts done, current, future, or milestone, and point-color, point-color-light, and point-color-dark can override the marker color. Status aliases accepted by the filter are complete / completed, active / now / in-progress, pending / planned, and major.
In PDF and DOCX the SVG route intentionally degrades to a readable ordered list, preserving item titles, statuses, links, and Markdown content. The PDF and DOCX links in the first roadmap are therefore also a demonstration of the cross-format strategy.
Circled Ordered List
circle-list keeps ordinary ordered-list semantics and changes only the visual treatment of the number marker.
Basic list
:::circle-list1. First item2. Second item, with normal **Markdown**3. Third item4. Fourth item:::
Output:
First item
Second item, with normal Markdown
Third item
Fourth item
Custom colors
The circle border, the number/text, and the background can be colored independently. An unsuffixed value applies to both light and dark themes.
The canonical color properties are border-color, text-color, and background-color; each accepts the extension-wide base / -light / -dark convention.
A compact procedure
Because the content remains ordinary Markdown, links, code, emphasis, and other inline content can be used normally.
:::circle-list1. Create `_quarto.yml` in the project root.2. Add `semantic-components` to the **filters** list.3. Run [`quarto preview`](https://quarto.org/docs/get-started/hello/vscode.html).4. Render the final document with `quarto render`.:::
git-tree represents a Git history as a commit DAG rather than as a generic tree. A dot is a commit, an edge is a parent → child relationship, a branch split starts at a commit, and a merge ends at a commit.
Nested branches are valid Git histories. Here test/badges starts from a commit on feature/badges, then merges back before feature/badges itself merges into main.
tree is a neutral hierarchy component. Unlike file-tree, it does not assume that nodes are files or folders; unlike git-tree, it does not model commits or parent relationships. It simply renders nested Markdown lists as a readable hierarchy.
Branches are inferred solely from nested children. Use expanded=, open=, or collapsed= on a span when a branch needs a specific initial state. line-color-light and line-color-dark can tune connector contrast by theme.
Optional tree controls
Add controls="true" to render a compact HTML control panel above the tree. The panel provides global Expand all / Collapse all actions and synchronized expand/collapse buttons for every branch depth detected in the tree.
For example, clicking + beside L1 expands every level-1 branch at once, while − collapses all level-1 branches. The same behavior is generated automatically for L2, L3, and deeper levels when present. Individual branch toggles continue to work normally.
panel="true" and toolbar="true" are accepted as aliases for controls="true". The control panel is HTML-only; PDF and DOCX preserve the full semantic tree without interactive controls.
File tree
file-tree describes a project or directory hierarchy using an ordinary nested list. File names are automatically mapped to useful icons, while links, inline code, comments, info hints, custom icons, and collapsible folders remain optional.
schema.sql receives the classic database-cylinder icon automatically, while common programming languages and formats are detected from the file name or extension.
Plain text versus inline code
The author controls whether a file name looks like code. A plain filename remains plain text; backticks explicitly request inline-code styling.
info= adds a small, keyboard-focusable information marker. In HTML, its text is exposed through title and aria-label.
:::file-tree- [analysis.R]{info="Main R analysis script"}- [`pipeline.py`]{info="Ingestion and validation pipeline"}- [schema.sql]{info="Relational schema used by the application"}:::
article is the generic block for self-contained content. It deliberately does not encode a specific use case: the same primitive can represent a note, release entry, specification, summary, changelog entry, or collapsible explanation.
The outer HTML element is always a real <article>.
Generic article
:::article## Technical noteThis is the default `article`, with no accent and no collapse.The content can contain ordinary **Markdown**, lists, links, and code.:::
Output:
Technical note
This is the default article, with no accent and no collapse.
The content can contain ordinary Markdown, lists, links, and code.
Left accent
accent="left" turns the left border into an accent. accent-color accepts any CSS color or semantic names aligned with Quarto callout colors: note, info, warning, danger, caution, success, tip, and important.
A collapsible article uses native HTML <details> inside the <article> wrapper. No JavaScript is required, and the content remains fully visible in PDF/DOCX.
::: {.article collapsible="true" summary="Technical details" expanded="false"}The content starts collapsed in HTML.- normal Markdown- lists- code- other components:::
Output:
Technical details
The content starts collapsed in HTML.
normal Markdown
lists
code
other components
Expanded by default with an accent
::: {.article accent="left" accent-color="note" collapsible="true" summary="Methodology" expanded="true"}This example starts expanded and combines the accent with native collapse/expand behavior.:::
Output:
Methodology
This example starts expanded and combines the accent with native collapse/expand behavior.
Changelog pattern
A changelog does not require a dedicated component. It is simply one possible use of article.
:::article## 0.1.0 — 2026-09-18### Added- Generic `tree` and semantic `properties`.- Native `progress` and `meter` indicators.- Inline `kbd` and `abbr` primitives.### Changed- Theme-aware colors continue to support unsuffixed, `-light`, and `-dark` values.:::
Output:
0.1.0 — 2026-09-18
Added
Theme-specific color overrides with -light and -dark suffixes.
Theme-aware examples for steps, badges, Git trees, and articles.
Changed
Automatic theme colors remain the default whenever no explicit color is supplied.
Properties
properties enhances an ordinary Pandoc definition list. The underlying structure remains semantic in PDF and DOCX, while HTML presents it as a responsive key/value grid.
Basic metadata
:::propertiesProject: Quarto Semantic ComponentsVersion: 0.1.0Language: LuaLicense: MIT:::
meter uses the native HTML <meter> element. Unlike progress, it represents a scalar measurement within a known range rather than task completion.
{{< meter value="82" min="0" max="100" label="Test coverage" value-label="82%" >}}{{< meter value="7.2" min="0" max="10" low="4" high="8" optimum="9" label="Quality score" >}}
Output:
Test coverage82%82%
Quality score7.2 / 107.2 / 10
The attributes low, high, and optimum preserve the semantics of native <meter>.
Keyboard input
kbd renders keyboard input with the native HTML <kbd> element. A +-separated shortcut is automatically split into individual keys.
Press {{< kbd "Ctrl+Shift+P" >}} to open the command palette.Use {{< kbd "Ctrl+C" >}} and {{< kbd "Ctrl+V" >}} to copy and paste.
Output:
Press Ctrl+Shift+P to open the command palette.
Use Ctrl+C and Ctrl+V to copy and paste.
Abbreviations
abbr emits the native HTML <abbr> element with its expansion in title. In non-HTML formats it degrades to the abbreviation followed by its full form.
A {{< abbr KBA "Key Biodiversity Area" >}} identifies a site of global importance for biodiversity.The extension is built on the {{< abbr AST "Abstract Syntax Tree" >}} produced by Pandoc.
Output:
A KBA identifies a site of global importance for biodiversity.
The extension is built on the AST produced by Pandoc.
Combining components
The primitives are intentionally composable. A component can contain normal Markdown and, where the document structure permits it, other semantic components.
The release contains the extension source, documentation, and examples.
semantic-components
theme-colors.lua
steps.lua
roadmap.lua
file-tree.lua
git-tree.lua
article.lua
badges.lua
README.md
index.qmd
Output formats
The components are designed around Pandoc structure rather than HTML-only widgets.
Format
Behavior
HTML
Full styling, light/dark color overrides, sinuous roadmaps, generic/file trees, SVG Git DAG, native progress/meter, keyboard/abbreviation semantics, and article collapse/expand
PDF
Structural content, roadmap items, statuses, links, and other content are preserved as readable static output
DOCX
Lists, headings, roadmap items, links, and text remain editable
Inspiration
The Steps and File Tree ideas were inspired by components from Vocs. The implementation here is original and built around the Pandoc AST, project-level configuration, and cross-format rendering.
report.qmd