What is Baleada Prose?
Updated on August 22, 2024Source code
Baleada Prose is a component library brings a base layer of rich interactivity to Markdown articles.
Installation
Right now, Baleada Prose only offers components for Vue 3:
npm i @baleada/vue-prose
Workflow
Unlike most component libraries, Baleada Prose is not designed to be directly coded by hand. The intended workflow is:
- Write an article using Baleada's extension of the Markdown syntax.
- Use a Markdown parser and renderer with a Baleada plugin installed to parse your Baleada-flavored Markdown and render it, replacing certain HTML tags with Baleada Prose components.
- Pass the rendered HTML + Baleada Prose string through a toolchain that can render Baleada Prose tags and their contents as fully reactive components.
Currently, Baleada supports markdown-it as the Markdown parser and renderer, and it supports Vue as the reactivity and component framework that can render Baleada Prose components.
Using those tools, here is the more specific workflow you should follow:
Write your article using Baleada's extension of the Markdown syntax. Eventually, you should read the Baleada Markdown syntax guide for full documentation, but for now, here's a quick example:
:::
# My article
:::
This article is written mostly in normal Markdown, but certain
block-level elements surrounded by triple colons will become
Baleada Prose components.
☝️ That heading, for example, will render as a `BaleadaProseHeading`.
👇 This blockquote is customized with props. It will be a
`BaleadaProseBlockquote` with a custom tweet button:
::: readerCanTweet tweetVia="BaleadaToolkit" tweetUrl="current"
> I'll be an enhanced blockquote!
:::
> I'll be a normal HTML blockquote, since I'm not surrounded by triple colons.
👇 This table, also customized with props, will render with a
custom type-to-filter search box:
::: readerCanSearch ariaLabel="Alphabet table"
| Letter | Word |
| --- | --- |
| A | Apple |
| B | Banana |
| C | Captain Jean Luc Picard of the USS Enterprise |
| D | Dog |
:::
Then, use markdown-it with the Baleada Prose Container plugin to parse and render your content.
This is normally done inside a larger code-bundling toolchain, but here are the bits that matter:
import MarkdownIt from 'markdown-it'
import { createMarkdownItProseContainer } from '@baleada/markdown-it-prose-container'
const md = new MarkdownIt()
md.use(createMarkdownItProseContainer({ template: 'vue' }))
const myRenderedHtmlString = md.render(myBaleadaFlavoredMarkdownString)
// ->
// An HTML string, with many HTML tags replaced by their
// Baleada Prose equivalents, along with any props the
// author passed.
Finally, use Vue to render the HTML string as an interactive article.
This task involves one important additional task: globally registering Baleada Prose components with Vue so they can be used in any template. Baleada Prose provides a Vue plugin to make this easier. The code below shows basic plugin usage, and you can visit the Baleada Prose setup guide to learn more about customization.
Again, this is normally done in the context of a larger toolchain, especially one that supports Vue's Single File Components, but here is the basic concept:
import { createApp } from 'vue'
import { createProse, components } from '@baleada/vue-prose'
const app = createApp({
template: myRenderedHtmlString,
})
app.use(createProse({ components }))
app.mount('#app')
And that's the bare minimum workflow to get Baleada Prose working! To see it in action, here's an editable demo.
Available components
Here are the available components in the Baleada Prose library, each linked to their specific documentation:
