Skip to content

Documentation ​

Markdown ​

Custom block ​

Poveste lets you write markdown documentation for your stories using Vue custom blocks. Add a docs tag in your story file:

vue
<template>
  <!-- Your story goes here -->
</template>

<docs lang="md">
# My documentation

Checkout this [cool video](https://www.youtube.com/watch?v=dQw4w9WgXcQ)!
</docs>

Sibling markdown ​

To add documentation to a story, you can also create a file with the same name next to it, with the .md extension.

For example, if your story is BaseButton.story.vue, create a BaseButton.story.md file.

Sibling markdown files are higher priority than custom blocks.

Standalone page ​

If you create a markdown file ending with .story.md that isn't related to a sibling story file, it will automatically create a virtual story that renders the markdown as a page.

You can add a frontmatter to the markdown to customize the virtual story with the following properties:

Example Introduction.story.md file:

md
---
group: 'top'
icon: 'carbon:bookmark'
---

# Welcome

This is a demo book using Vue 3.

---

Learn more about Poveste [here](https://poveste.dev/).

Load it from another file ​

To show a file the story doesn't own, such as a component's README, point the custom block at it with src:

vue
<template>
  <Story title="Button">
    <button>Save</button>
  </Story>
</template>

<docs src="./README.md" />

A sibling or standalone .story.md can do the same in its frontmatter:

md
---
src: ./README.md
---

The path is relative to the story file or the .story.md, and in poveste dev, editing the loaded file reloads the docs.

A .story.md with src doesn't show its own text. If the file isn't there, poveste build fails and names it, and poveste dev shows the same message in the docs.

Loaded markdown renders like any other, with a few differences, because it usually wasn't written for a book:

  • A relative link is read from the loaded file. One that reaches a story goes to that story. Anything else, like ./LICENSE, stays as written, which won't resolve in the book, and poveste dev warns about it.
  • Relative images aren't resolved. Use an absolute URL or a file from public/.
  • The loaded file's own frontmatter is ignored, including any src of its own.

Embed a story ​

To show a live story between your paragraphs, name it with a tag, on a line of its own:

md
Some text before.

<poveste-story id="my-button" variant="primary" />

Some text after.

id is the story's id. variant is the variant's id, and without it you get the story's first variant. If no story matches, the page says so where the embed would be.

An embed runs in its own sandbox, as a preview does, so the story's styles stay inside it. It loads when you scroll near it, and each one on a page boots a sandbox of its own. Its frame grows to fit the story up to 400 px, and a taller story scrolls inside it.

This embeds a story that already exists. A component can't be imported into the markdown itself.

You can link to other stories using a relative path to the story file:

md
- [Go to Story](./BaseButton.story.vue)
- [Go to CodeGen > Slots](./CodeGen.story.vue?variantId=slots)
- [Go to Markdown file](./MarkdownFile.story.md)

Types on hover ​

A TypeScript or JavaScript block marked twoslash is compiled when the book renders it, and shows each name's type when the reader hovers it, as Twoslash does on a VitePress site. From the keyboard, the block is one Tab stop and the arrow keys move between its names:

md
```ts twoslash
type Size = 'sm' | 'md' | 'lg'

const size: Size = 'md'
```

It needs one package Poveste leaves out, so that a book marking no block doesn't install it:

shell
pnpm i -D @shikijs/twoslash
# OR
npm i -D @shikijs/twoslash
# OR
yarn add -D @shikijs/twoslash

Without it, a marked block renders as plain code, and the log says what to install.

It compiles with the TypeScript 6 Poveste installs for auto-docs, whatever TypeScript the book has. Each block compiles on its own, with TypeScript's defaults rather than the book's tsconfig: an import from a package the book installs resolves, but one through a paths alias such as @/, or of a .vue or .svelte file, does not. With npm and TypeScript 7, installing @shikijs/twoslash prints a peer warning and npm ls typescript reports typescript as invalid, because Twoslash asks for TypeScript 5 or 6 beside it: that is expected, and the blocks still compile with Poveste's copy. A block that does not compile renders as plain code too, and the log names its file and line: it never fails a build. Unmarked blocks are unchanged, and nothing is loaded for a book that marks none.

A block with types wraps its long lines rather than scrolling them, so a type's popup is not cut off at the edge.

Props, slots and events ​

Each component a story imports gets a table on the story's Docs tab, whether it is a .vue file or one defineComponent makes in a .ts or .tsx file, below any markdown: its props with their types, descriptions and defaults, its slots, and its events. Poveste reads them from the component's types with vue-component-meta, so nothing is written for it. A component counts when the story imports it directly or through re-exports, such as import { SelectRoot } from '..' from a folder whose index.ts re-exports its .vue files. When a story renders a helper instead, name what it documents with component. A compound component's root comes first and open, and above three parts the rest start collapsed. In poveste dev, a story that imports components auto-docs can't trace to a file says so on its Docs tab.

What each table reads:

  • Props come from defineProps, including an interface that extends another from a separate file. Descriptions and tags come from each prop's JSDoc.
  • Defaults come from withDefaults or the props object, then from a @default or @defaultValue tag. In poveste dev, a default whose tag says something else is marked; the built book shows the one the code applies.
  • @deprecated is shown on its row; a prop tagged @internal or @private is left out.
  • Slots come from defineSlots, and events from defineEmits.
  • Props a component inherits from installed packages, such as the HTML attributes, are left out unless autoDocs.allow names the package.

A component written with the Options API gets its props from its props option, with the types and defaults that option declares. One that defineComponent makes in a .ts or .tsx file gets a table too, read from that file's default export; a plain object, a function or a type exported by default from a script file gets none.

In a Nuxt book, a component a story uses without importing it, because Nuxt registers it, counts as imported: Nuxt adds the import before auto-docs reads the story. Quasar's own components, such as QBtn, come from the quasar package's built JavaScript and get no table, as with any library; your own components in a Quasar book do.

If a story's markdown already has hand-written Props, Emits or Slots sections, delete them once auto-docs is on: the table shows beside them, and the two drift apart. Keep the prose a table can't carry, such as usage, accessibility notes and examples.

The Controls panel reads the same types, so a documented prop typed 'sm' | 'md' | 'lg' gets a select: see Controls from types.

In poveste dev, nothing runs until a reader first opens a story's Docs tab, or its Controls when its components have automatic controls. The first time can take many seconds while the types are read; after that the table is cached, and an edit to a component refreshes it. poveste build reads every story's components in one pass, so a build pays for the whole book at once: see autoDocs for the time and memory.

It reads the types with a TypeScript 6 Poveste installs, so the book needs no TypeScript of its own, and one on TypeScript 7 is read the same way. A book without a tsconfig.json is read as if it included every file. A built book carries the tables it read at build time, and leaves out a component whose types couldn't be read.

To turn it off, or narrow it, set autoDocs in the config:

ts
export default defineConfig({
  autoDocs: false,
})

Source code ​

By default, Poveste will attempt to generate a copyable source code from the story, dynamically from the current state.

Currently automatic source code generation is only supported for:

  • Vue 3

To document a copyable source code manually you can use either the source prop or the source slot.

vue
<script lang="ts" setup>
function initState () {
  return {
    count: 0,
  }
}

const source = `<h1>Toto</h1>

<input
  v-model.number="count"
  type="number"
>

<p>{{ count }}</p>

<template #named="{ shown, hide }">
  <MyComponent
    v-if="shown"
    :item="{ foo: 'bar' }"
    @close="hide()"
  />
</template>`
</script>

<template>
  <Story title="Hand-written source">
    <Variant
      title="Source prop"
      :init-state="initState"
      :source="source"
    >
      <template #default="{ state }">
        <h1>Toto</h1>

        <input
          v-model.number="state.count"
          type="number"
        >
      </template>
    </Variant>
    <Variant
      title="Source template"
      :init-state="initState"
    >
      <template #default="{ state }">
        <h1>Toto</h1>

        <input
          v-model.number="state.count"
          type="number"
        >
      </template>

      <template #source>
        <textarea v-pre>
          <h1>Toto</h1>

          <input
            v-model.number="count"
            type="number"
          >

          <p>{{ count }}</p>

          <template #named="{ shown, hide }">
            <MyComponent
              v-if="shown"
              :item="{ foo: 'bar' }"
              @close="hide()"
            />
          </template>
        </textarea>
      </template>
    </Variant>
  </Story>
</template>

TIP

You should use a <textarea v-pre> element in the source slot to prevent Vue from compiling the template.

Released under the MIT License. Updates on Bluesky and X.