Setup

Updated on August 22, 2024

Setting up Baleada Prose is a two-part process:

1. Using the exported createProse function to create a Vue plugin that will globally register Prose components, among other things
2. Using the exported useEffects function in the setup function to make sure certain side effects (e.g. smoothly scrolling your article to an anchored heading) are being performed

Create your Baleada Prose plugin

Baleada Prose exports a createProse function, which sets up Baleada Prose components and returns a Vue plugin.

More specifically, you can use createProse to:

• Globally register Baleada Prose components, so that you can freely use them inside of any other component
• Customize the default value for any prop on any component
• Customize default text that appears for certain components
• Treeshake Baleada Prose if you only want to use certain components, and would rather not globally register others
• Install Pinia (used by Baleada Prose for sharing state), unless you're already doing that elsewhere in your app
• Connect Baleada Prose to Vue Router, or any other router, so that certain Prose components are notified when page navigation happens

To get started, import createProse from Baleada Prose. In many cases, you'll do this in your Vue app's entry file, or wherever you go to register Vue plugins.

import { createApp } from 'vue'
import { createProse, components } from '@baleada/vue-prose'

const app = createApp()

app.use(createProse())

In that code example, you'll see that createProse was called with no arguments. That will never happen in any real-world use case—instead, you'll pass an optional options object as the first and only argument for createProse.

Here's a breakdown of the options object:

Choose your components

createProse can globally register Baleada Prose components, so that they can be freely used by any Vue component.

By default, though, createProse actually doesn't register any components. To make sure components are registered, you need to import them from Baleada Prose, and pass them to the components option.

In most cases, you'll use the exported components array to do this:

import { createProse, components } from '@baleada/vue-prose'

// Create a `prose` plugin for your Vue app that
// globally registers every Baleada Prose component
const prose = createProse({ components })

This might seem strange, but it's a great way to give you more control over your bundle size. If you know for certain that you won't be using certain components, then don't import them, and your build tool will be able to treeshake the unused code.

Instead of importing the components array, you can import individual components:

// In this example, you only want to use Baleada Prose
// components for headings, tables, and blockquotes.
import {
  createProse,
  BaleadaProseHeading,
  BaleadaProseTable,
  BaleadaProseBlockquote,
} from '@baleada/vue-prose'

// Create a `prose` plugin for your Vue app that
// only registers the Baleada Prose components you
// actually want.
const prose = createProse({
  components: [
    BaleadaProseHeading,
    BaleadaProseTable,
    BaleadaProseBlockquote,
  ]
})

Keep in mind that Baleada Prose is a pretty small package to begin with, so in most cases, you'll take the happy path and use the components array to register all components.

Customize prop defaults

Baleada Prose is designed to replace every block-level element in Markdown, plus a few block-level elements that Markdown doesn't natively support, with a custom component.

Manually passing props to every single component to customize its behavior would suck! Instead, you can configure Baleada Prose with default values for any prop on any component.

To do this, you'll set an object as the value of the propDefaults key of your createProse options object.

import { createProse, components } from '@baleada/vue-prose'

const prose = createProse({
  components,
  propDefaults: {...},
})

The properties of that object should be the short names of the available Baleada Prose components:

Each property's value should be an object, whose keys are the component's props, and whose values are the default values you want to set up.

import { createProse, components } from '@baleada/vue-prose'

const prose = createProse({
  components,
  propDefaults: {
    aside: {...},
    heading: {...},
  },
})

Your prop defaults will be deeply merged with the default propDefaults configuration that Baleada Prose uses, so don't feel the need to configure every prop on every component.

See the Prop defaults guide for a full breakdown of what props are available for customization, what the default propDefaults are, and a more complete and detailed customization example.

Customize messages

Certain Baleada Prose components display text alongside other UI elements. For example, this BaleadaProseList renders a type-to-filter box, with placeholder text:

To customize that placeholder text, and other text rendered by Prose components, you'll set an object as the value of the messages key of your createProse options object.

import { createProse, components } from '@baleada/vue-prose'

const prose = createProse({
  components,
  messages: {...},
})

The properties of that object should be the short names of the Baleada Prose components that render text:

Each property's value should be an object, whose keys are the component's props, and whose values are the default values you want to set up.

import { createProse, components } from '@baleada/vue-prose'

const prose = createProse({
  components,
  propDefaults: {
    list: {...},
    table: {...},
  },
})

Your messages will be deeply merged with the default messages configuration that Baleada Prose uses, so don't feel the need to configure every message on every component.

See the Messages guide for a full breakdown of what messages are available for customization, what the default messages are, and a more complete and detailed customization example.

Set up side effects

Two features of Baleada Prose involve small DOM side effects:

1. Smooth scrolling your article to the top or to an anchored BaleadaProseHeading based on URL changes and user preferences
2. Setting up Baleada Prose's internal shared store to reactively track the route location, which is used by BaleadaProseBlockquote to generate tweet intents for tweet buttons.

To set up these side effects, you can call the useEffects function exported by Baleada Prose:

import { useEffects } from '@baleada/vue-prose'

useEffects(...)

You should call useEffects from inside the setup function of a Vue component that renders before the first Prose component in your component tree.

App.vue, for example, is the highest component in the tree of many Vue apps, so you could call it there:

<!-- App.vue -->
<template>...</template>
<script setup>
import { useEffects } from '@baleada/vue-prose'

useEffects(...)
</script>

However, it doesn't have to be App.vue, and it doesn't event have to be an ancestor of your Baleada Prose components. As long as it renders before the first Prose component in your tree, side effects will be wired up correctly.

useEffects accepts an options object as its only argument. Here's a breakdown of that object:

Here's a more complete example of how to call and configure useEffects:

<!-- SomeComponent.vue -->
<template>
  <article ref="article">
    <a-vue-component-that-renders-prose-components />
  </article>
</template>

<script setup>
import { ref } from 'vue'
import { useEffects } from '@baleada/vue-prose'

// Set up the reactive reference
const article = ref(null)

// Pass the `article` element reference as the
// scrollable container, and force auto scrolling.
useEffects({
  scrollableContainer: article,
  scrollIntoView: {
    block: 'start',
    behavior: 'auto',
  }
})
</script>

Customize smooth scrolling

As mentioned above, the options.scrollIntoView object lets you customize smooth scrolling behavior for useEffects.

The options.scrollIntoView object is almost exactly the same as the web's standard scrollIntoView options. It has one small difference: instead of just auto and smooth behavior, you can opt for preferred behavior.

import { useEffects } from '@baleada/vue-prose'

useEffects({
  scrollIntoView: {
    // `block` and `inline` are exactly the same as the
    // standard `scrollIntoView` options
    block: ...,
    inline: ...,
    // `behavior` accepts 'preferred', in addition to the
    // standard 'auto' and 'smooth'.
    behavior: 'preferred'
  }
})

When you set options.scrollIntoView.behavior to preferred (which is Baleada Prose's default setting), useEffects will check the reduced motion settings on the end user's device. If the end user has opted into reduced motion, useEffects will use auto scrolling behavior, otherwise, it will use smooth scrolling behavior.

Event if the user changes their reduced motion settings after they have already opened your page, useEffects will instantly update its scrolling behavior to match the user's new preferences.

Edit doc on GitHub