Webpack loader for compiling Markdown to Vue
MIT License
md-vue-loader
is a Webpack loader to import Markdown files as Vue components.
vue-loader
/vue-template-compiler
)!npm i -D md-vue-loader
Add to your Webpack config:
module.exports = {
module: {
rules: [
+ {
+ test: /\.md.vue$/,
+ use: [
+ 'vue-loader',
+ 'md-vue-loader'
+ ]
+ }
]
},
/// ...
}
You can inline vue
codeblocks like the following as inline-demos by enabling the buildDemos
option.
```vue
<template>
<div>Hello world!</div>
</template>
```
To enable buildDemos
, pass in options in your Webpack config:
module.exports = {
module: {
rules: [
{
test: /\.md$/,
use: [
'vue-loader',
+ {
+ loader: 'md-vue-loader',
+ options: {
+ buildDemos: true
+ }
+ }
]
}
]
},
/// ...
}
Demos can be multi-file by naming code-blocks by prepending it with the filename in wrapped in underscores. You can import these code-blocks within the doc
alias.
Name a code-block:
_HelloWorld.vue_
```vue
<template>
<div>
Hello World
</div>
</template>
```
Import the code-block from doc/HelloWorld.vue
:
```vue
<template>
<hello-world />
</template>
<script>
import HelloWorld from 'doc/HelloWorld.vue';
export default {
components: {
HelloWorld
}
}
</script>
```
You might want more control over how your demo is inlined to have it wrapped for styling, or to have the source-code next to it.
To configure the demo markup, you can pass in a function to control how the component is inlined: function (demoTag, files)
. In the function context, you have access to this.addComponent([...named imports], 'module-name')
to register external components.
In this example, I use vue-demo-collapse
to wrap my demo with an expandable container to show the demo source-code:
module.exports = {
module: {
rules: [
{
test: /\.md$/,
use: [
'vue-loader',
{
loader: 'md-vue-loader',
options: {
+ buildDemos(Tag, demoFiles) {
+ this.addComponent(['DemoCollapse', 'SrcFile'], 'vue-demo-collapse');
+
+ const listFiles = demoFiles
+ .map((file) => `<src-file name="${file.name || ''}" language="html"><template v-pre>${ent.encode(file.content)}</template></src-file>`)
+ .join('');
+
+ return `
+ <demo-collapse>
+ ${Tag}
+ ${listFiles}
+ </demo-collapse>
+ `;
+ }
}
}
]
}
]
},
/// ...
}
buildDemos
(Boolean
|Function
)
Boolean
Renders Vue code-blocks as inline demosFunction(Tag, demoFiles)
Enable inline Vue demos and customize how they're inlined. Outputs the new template.
Tag
is the tag-name of the demo component. Make sure to use it in your output to output the demo.demoFiles
(Array
) contains all the source code releavnt to the demomarkdownItOpts
(Object): An object to configure MarkdownIt — the Markdown compiler.
Example:
({
// ...,
options: {
markdownItOpts: {
html: true,
linkify: true,
typographer: true
}
}
})
markdownItPlugins
(Array
): An array of MarkdownIt Plugins.
Example:
const markdownItAnchor = require('markdown-it-anchor')
// ...
module.exports = {
module: {
rules: [
{
// ...
options: {
markdownItPlugins: [
[markdownItAnchor, {
permalink: true,
permalinkBefore: true,
permalinkSymbol: '<img class="icon anchor-link" aria-hidden="true" src="../../assets/md-anchor-link.svg">'
}]
]
}
}
]
}
}