# Ballad: Doctave's Markdown-aware component system

DevFeed: [Ballad: Doctave's Markdown-aware component system](<https://devfeed.tech/articles/ballad-doctave-s-markdown-aware-component-system-30941.md>)

Original publisher: [Read original article](<https://www.doctave.com/blog/ballad-components>)

Author: Doctave Team

Published: 2024-05-27T07:00:00Z

Content type: release

Language: en

Sources: [Doctave - Build beautiful developer portals with docs-as-code](<https://devfeed.tech/sources/doctave-build-beautiful-developer-portals-with-docs-as-code.md>)

Topics: [Markdown](<https://devfeed.tech/topics/markdown.md>), [MDX](<https://devfeed.tech/topics/mdx.md>), [Parser](<https://devfeed.tech/topics/parser.md>), [Documentation](<https://devfeed.tech/topics/documentation.md>), [ui](<https://devfeed.tech/topics/ui.md>)

Tags: [blog](<https://devfeed.tech/tags/blog.md>), [components](<https://devfeed.tech/tags/components.md>), [documentation](<https://devfeed.tech/tags/documentation.md>), [elements](<https://devfeed.tech/tags/elements.md>), [markdown](<https://devfeed.tech/tags/markdown.md>), [mdx](<https://devfeed.tech/tags/mdx.md>), [render](<https://devfeed.tech/tags/render.md>)

## AI overview

This release article explains Ballad, Doctave's Markdown-aware component system introduced in Doctave 2.0. It describes embedding UI and layout components in Markdown with an MDX-inspired syntax, combining components with Markdown, using expressions for user preferences, and creating custom components.

## Source excerpt

Doctave 2.0 is out, and the biggest new feature in this release was our new component system, which we're calling Ballad. In this post we want to talk about the path we took to get here, why we felt none of the existing solutions worked well for us, and what our component system enabled. Ballad brings interactive components like tabs to your Doctave docs Why do we need components? Ballad lets you intersperse UI components in between your Markdown content. While Markdown is fantastic for simple prose, most documentation projects inevitably need widgets like buttons, cards, and callouts (or admonitions), or more complex layouts to keep the content clear and engaging. This is what we're solving with Ballad. How it works In short, you can add HTML-like tags into your Markdown, which Doctave will render into various components. Let's look at a basic example: adding a Button component into your documentation: 1 2 3 Click below to read more. <Button href="/details">Read More</Button> This gets rendered like so: Sometimes a regular Markdown link just doesn't cut it Components Our components come in two flavors: UI components and layout components. The former are components like <Button> or <Card>: visual elements that you're adding to the page. Layout components instead (unsurprisingly) change the layout of your content. These are components like <Grid>, or <Flex> (a flexbox equivalent). Combining these components lets you build interesting UIs and structure your content however you want on the page, without having to write any custom CSS. Syntax You can use an MDX-inspired syntax to add components into your documentation: 1 2 3 4 5 6 7 8 9 10 11 12 ## Getting started Learn how to get started with our SDK. <Grid cols="2"> <Card> ... </Card> <Card> ... </Card> </Grid> In fact, the parser is an MDX parser. The component syntax rules are identical. These HTML-style components work with your Markdown content, and you can nest and combine components and Markdown arbitrarily. Exp