feat: add documentations via custom docs block (#53)

Fixes #49

README.md

@@ -44,6 +44,7 @@ import Button from './Button.vue'
 
 - Write stories as idiomatic Vue templates, bye bye string-based templates, as wished for in [storybookjs/storybook#9768](https://github.com/storybookjs/storybook/issues/9768)
 - Syntax highlighting and full editor support (including Volar) for writing story templates
+- Add markdown documentation in a custom `docs` block, directly in your `stories.vue` files (see below for details)
 - The component that is displayed needs only be declared once (via `<Stories :component="...">`) and not for every story
 - Simple integration with Storybook and automatic Vite support
 - Light: Vue stories are transpiled into ordinary CSF stories on the fly with minimal overhead
@@ -87,6 +88,45 @@ The way to write stories as idiomatic Vue templates is heavily inspired by the g
 
    ```
 
+## Adding documentation
+
+You can add documentation for your components directly in your story SFC using the custom `docs` block.
+
+```vue
+<template>Define your stories here as above</template>
+
+<docs lang="md">
+import { Canvas } from '@storybook/blocks';
+
+# Documentation
+
+Everything in one place. Isn't it great?
+
+You can render stories in the docs using the `<Canvas>` component.
+
+<Canvas />
+</docs>
+```
+
+You can use Markdown’s readable syntax (such as # heading) for your documentation, include stories, and freely embed JSX component blocks at any point in the file. See [Storybook Docs](https://storybook.js.org/docs/vue/writing-docs/introduction) for more information.
+There are a few minor differences to standard MDX documentation pages:
+
+- The `<Meta of=...>` tag is not needed.
+- You don't need to import the stories file. Simply refer to the defined stories by their name. For example:
+  ```vue
+  <template>
+    <Stories>
+      <Story title="Unchecked">
+        <Checkbox label="Unchecked" />
+      </Story>
+    </Stories>
+  </template>
+  <docs>
+    import { Canvas } from '@storybook/blocks';
+    <Canvas of={Unchecked} />
+  </docs>
+  ```
+
 ## Manual usage
 
 If for whatever reason you process Storybook stories in your build pipeline, you probably want to first transpile the Vue stories to classical CSF stories by adding `storybook-vue-addon` to your build.

examples/vite/src/components/Checkbox.vue

@@ -0,0 +1,37 @@
+<template>
+  <div class="checkbox">
+    <input
+      type="checkbox"
+      :checked="checked"
+      :disabled="disabled"
+      @change="onChange"
+    />
+    <label>{{ label }}</label>
+  </div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const props = defineProps({
+  label: {
+    type: String,
+    required: true,
+  },
+  checked: {
+    type: Boolean,
+    required: false,
+    default: false,
+  },
+  disabled: {
+    type: Boolean,
+    required: false,
+    default: false,
+  },
+})
+
+const checked = ref(props.checked)
+
+const onChange = () => {
+  checked.value = !checked.value
+}
+</script>

examples/vite/src/tests/docs.stories.vue

@@ -0,0 +1,28 @@
+<script lang="ts" setup>
+import MyButton from '../components/Button.vue'
+</script>
+
+<template>
+  <Stories
+    :component="MyButton"
+    title="Tests/Docs"
+  >
+    <Story title="Default">
+      <MyButton label="Button" />
+    </Story>
+  </Stories>
+</template>
+
+<docs lang="md">
+import { Canvas } from '@storybook/blocks';
+
+# Documentation
+
+Everything in one place. Isn't it great?
+
+You can render stories in the docs using the `<Canvas>` component.
+
+<Canvas />
+
+See [Storybook Docs](https://storybook.js.org/docs/vue/writing-docs/introduction) for more information.
+</docs>

examples/vite/src/writing_docs/mdx-1.basic-example.mdx

@@ -0,0 +1,15 @@
+{/* Checkbox.mdx */}
+
+import { Canvas, Meta, Story } from '@storybook/blocks'
+
+import * as CheckboxStories from './mdx-1.basic-example.stories.ts'
+
+<Meta of={CheckboxStories} />
+
+# Checkbox
+
+A checkbox is a square box that can be activated or deactivated when ticked.
+
+Use checkboxes to select one or more options from a list of choices.
+
+<Canvas of={CheckboxStories.Unchecked} />

examples/vite/src/writing_docs/mdx-1.basic-example.stories.ts

@@ -0,0 +1,24 @@
+// Checkbox.stories.ts|tsx
+
+// Replace your-framework with the name of your framework
+import type { Meta, StoryObj } from '@storybook/vue3'
+
+import Checkbox from '../components/Checkbox.vue'
+
+const meta: Meta<typeof Checkbox> = {
+  /* 👇 The title prop is optional.
+   * See https://storybook.js.org/docs/react/configure/overview#configure-story-loading
+   * to learn how to generate automatic titles
+   */
+  title: 'docs/Writing docs/MDX/1. Basic Example/classical',
+  component: Checkbox,
+}
+
+export default meta
+type Story = StoryObj<typeof Checkbox>
+
+export const Unchecked: Story = {
+  args: {
+    label: 'Unchecked',
+  },
+}

examples/vite/src/writing_docs/mdx-1.basic-example.stories.vue

@@ -0,0 +1,24 @@
+<script setup lang="ts">
+import Checkbox from '../components/Checkbox.vue'
+</script>
+<template>
+  <Stories
+    :component="Checkbox"
+    title="docs/Writing docs/MDX/1. Basic Example/native"
+  >
+    <Story title="Unchecked">
+      <Checkbox label="Unchecked" />
+    </Story>
+  </Stories>
+</template>
+<docs lang="md">
+import { Canvas } from '@storybook/blocks';
+
+# Checkbox
+
+A checkbox is a square box that can be activated or deactivated when ticked.
+
+Use checkboxes to select one or more options from a list of choices.
+
+<Canvas of={Unchecked} />
+</docs>

package.json

@@ -90,6 +90,8 @@
     "test": "vitest"
   },
   "dependencies": {
+    "@storybook/csf": "^0.1.0",
+    "@storybook/mdx2-csf": "^1.0.0",
     "consola": "^3.0.0",
     "prettier": "^2.8.4",
     "prettier-plugin-organize-imports": "^3.2.2",