Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/privatenumber/vite-vue-md
Vite plugin for importing Markdown files as Vue components. Works with Vue 2 & 3
https://github.com/privatenumber/vite-vue-md
markdown plugin vite vue
Last synced: 18 days ago
JSON representation
Vite plugin for importing Markdown files as Vue components. Works with Vue 2 & 3
- Host: GitHub
- URL: https://github.com/privatenumber/vite-vue-md
- Owner: privatenumber
- License: mit
- Created: 2024-01-20T09:46:43.000Z (10 months ago)
- Default Branch: develop
- Last Pushed: 2024-03-27T13:42:22.000Z (8 months ago)
- Last Synced: 2024-10-19T01:11:37.832Z (28 days ago)
- Topics: markdown, plugin, vite, vue
- Language: TypeScript
- Homepage:
- Size: 783 KB
- Stars: 7
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
vite-vue-md
This Vite plugin adds support for importing a Markdown file as a Vue component. Works with Vue 2 & 3.
### _Vue.js Demo Blocks_
Render your Vue.js code blocks inline by simply adding `demo` next to the language name.
For example, when this Markdown file is rendered with this plugin, you'll see a clickable button here:
```vue demo
const clickHandler = () => alert('Clicked!')
Click me
```
## Install
```
npm install -D vite-vue-md
```
## Setup
In your `vite.config.js` file:
1. Import `vite-vue-md` and add it to the `plugins` array.
2. In your `vue()` plugin options, add a `include` option that includes `.md` files.
_vite.config.js_:
```diff
import vue from '@vitejs/plugin-vue'
+ import vueMd from 'vite-vue-md'
export default {
plugins: [
// ...
vue({
+ include: [/\.vue$/, /\.md$/] // ← Treat MD files as Vue components
}),
+ vueMd(/* Options */) // ← Compile MD files to Vue components
]
// ...
}
```
## Demo Blocks
_Demo Blocks_ are Vue.js code blocks that are rendered inline. They're useful for documentation docs to show off your components without compromising the readability of the Markdown file on GitHub.
To compile a Vue.js codeblock as a _Demo Block_, add `demo` next to the language name:
````
```vue demo
const clickHandler = () => alert('Clicked!');
Click me
```
````
### Multi-file demos
The entry point for demo blocks must be a Vue.js component. But you can import other code blocks in any language from the same Markdown file.
For non-entry files, set a file name via `demo=`. Then import it from the Vue.js demo block via the `doc:` protocol:
````markdown
Entry file:
```vue demo
import { clickHandler } from 'doc:click-handler.js'
Click me
```
Second file:
```js demo=click-handler.js
export const clickHandler = () => alert('Clicked!');
```
````
### Demo + Code blocks
Since the code blocks are rendered inline, they're replaced by the actual Vue.js component. To show the code block, you can add a `onDemo` callback to the plugin options:
```ts
({
onDemo(componentTag, code) {
// Register the wrapper component
this.registerComponent('DemoContainer', './DemoContainer.vue')
// Return a custom HTML string
return `
${componentTag}
${this.escapeHtml(code)}
`
}
})
```
## Options
### include
Type: `ReadonlyArray | string | RegExp`
Files to include from being compiled as Vue files.
### exclude
Type: `ReadonlyArray | string | RegExp`
Files to exclude from being compiled as Vue files.
### markdownItOptions
Type: `markdownIt.Options`
MarkdownIt options. See [MarkdownIt's documentation](https://markdown-it.github.io/markdown-it/) for more information.
### markdownItSetup
Type: `(md: markdownIt) => void;`
Callback to add plugins to MarkdownIt.
### wrapperClass
Type: `string`
Default: `markdown-body`
The class to add to the wrapper element that contains the Markdown page.
### onDemo
Type:
```ts
(
tag: string,
code: string,
demos: Map
) => string
```
You can intercept each demo block and return a custom HTML string. This is useful for adding custom styling to demo blocks.
In addition, there are utils exposed in the `this` context:
- `escapeHtml`: Escape HTML code to prevent it from being rendered as HTML.
- `registerComponent`: Register a component to be used in the demo block. This is useful for registering components that are imported from other files.
See example above in the _Demo Blocks_ section.
### markdownCss
Type: `string`
File path to a stylesheet to use for the Markdown page. This will be added using `` so it will only apply to the markdown page. Useful for styling only the HTML generated by the MarkdownIt plugin.
### useVOnce
Type: `boolean`
Whether to add [`v-once`](https://vuejs.org/api/built-in-directives.html#v-once) to the entire Markdown page. This will prevent the Markdown page from being re-rendered when the Vue component is updated.
> Warning: This will disable demo blocks. Only use this if you have a large document and don't need demo blocks.
## Related
#### [unplugin-vue-markdown](https://github.com/unplugin/unplugin-vue-markdown)
Another Vite plugin for compiling Markdown files to Vue components.
This plugin has drawn inspiration from it but has a different feature set. This plugin only supports Vue.js code in code blocks.