Quarto Semantic Components extension — reusable semantic Markdown/Pandoc primitives for HTML, PDF and DOCX

[lsbjordao]

Description

I have been working on a small Quarto extension called Quarto Semantic Components.

The idea is to provide a set of reusable documentation primitives that stay as close as possible to ordinary Markdown/Pandoc semantics, while adding richer presentation in HTML and degrading cleanly to readable PDF and DOCX output.

Repository: https://github.com/lsbjordao/quarto-semantic-components
Live gallery: https://lsbjordao.github.io/quarto-semantic-components/

The current set includes components such as:

• steps, including numbered and dot-based procedures/timelines;
• a responsive, sinuous roadmap;
• generic tree, file-tree, and Git-oriented git-tree;
• circle-list;
• article and properties;
• native progress and meter;
• inline badge, kbd, and abbr.

A few design choices I tried to keep consistent throughout the extension:

• Pandoc structure first rather than HTML-only widgets;
• ordinary Markdown inside components whenever possible;
• meaningful fallback for non-HTML formats;
• project-level defaults through _quarto.yml;
• a common color API where an unsuffixed value applies to both themes, while -light and -dark can override it independently;
• avoiding dedicated components when Quarto/Markdown already provides a good semantic representation.

For example, circle-list is still an ordered list, properties is based on a definition list, progress and meter use the corresponding native HTML elements, and the roadmap becomes a readable ordered structure in PDF/DOCX instead of trying to reproduce the SVG presentation.

The project is currently at 0.1.0, so I am particularly interested in feedback on the API and extension design, especially:

• whether the component syntax feels idiomatic for Quarto;
• whether some primitives overlap too much with existing Quarto functionality or other extensions;
• whether the light/dark configuration convention makes sense;
• and whether there are places where I could rely more directly on existing Quarto/Pandoc mechanisms instead of custom Lua/CSS.

The gallery contains the source syntax alongside the rendered result for each component.

Feedback and criticism are very welcome.