https://github.com/wxsms/vue-md-loader
:sparkles: Markdown files to ALIVE Vue components.
https://github.com/wxsms/vue-md-loader
document markdown vue webpack webpack-loader
Last synced: 8 months ago
JSON representation
:sparkles: Markdown files to ALIVE Vue components.
- Host: GitHub
- URL: https://github.com/wxsms/vue-md-loader
- Owner: wxsms
- License: mit
- Created: 2017-10-23T07:34:40.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2024-01-10T21:58:55.000Z (almost 2 years ago)
- Last Synced: 2025-03-29T22:07:14.316Z (8 months ago)
- Topics: document, markdown, vue, webpack, webpack-loader
- Language: JavaScript
- Homepage: https://vue-md-loader.wxsm.space
- Size: 2.72 MB
- Stars: 120
- Watchers: 2
- Forks: 56
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-vue - vue-md-loader - Markdown files to ALIVE Vue components. ` 📝 5 days ago` (Dev Tools [🔝](#readme))
- awesome-vue-zh - VE装载机 - 将文件标记为生存Vue组件. (叫研发工具组 / 文档)
- awesome-vue - vue-md-loader - Markdown files to ALIVE Vue components. (Components & Libraries / Dev Tools)
- awesome-vue - vue-md-loader ★51 - Markdown files to ALIVE Vue components. (Dev Tools / Docs)
- awesome-vue - vue-md-loader - Markdown files to ALIVE Vue components. (Dev Tools / Docs)
README
# vue-md-loader
[](https://www.npmjs.com/package/vue-md-loader)
[](https://www.npmjs.com/package/vue-md-loader)
[](https://github.com/wxsms/vue-md-loader)
| loader version | webpack version |
|------------- |---------------- |
| 2.x | 5 |
| 1.x | 4 and lower |
## Introduction
Webpack loader for converting Markdown files to ALIVE Vue components.
* Configurable **[Markdown-It](https://github.com/markdown-it/markdown-it)** parser.
* Built-in **syntax highlighter** with **[highlightjs](https://highlightjs.org/)**.
* ✨**Live demo**✨ support. Extremely useful for document examples.
* Vue 3 & vue-cli usage support.
* Hot reload.
## Example
This page ([vue-md-loader.wxsm.space](https://vue-md-loader.wxsm.space)) is generated by a markdown file. Source: [/example](https://github.com/wxsms/vue-md-loader/tree/master/example).
There is also a Vue 3 & Vue-cli example: [/example-vue3](https://github.com/wxsms/vue-md-loader/tree/master/example-vue3).
## Install
NPM:
```bash
npm install vue-md-loader --save-dev
```
Yarn:
```bash
yarn add vue-md-loader --dev
```
## Usage
### Basic
Simply **use `vue-md-loader`** to load `.md` files and **chain it with your `vue-loader`**.
```javascript
module.exports = {
// ...
module: {
rules: [
// ...
{
test: /\.md$/,
loader: 'vue-loader!vue-md-loader'
}
]
}
}
```
Note that to get code highlighting to work, you need to:
* include one of the highlight.js css files into your project, for example: `highlight.js/styles/github-gist.css`.
* specify a lang in code block. ref: [creating and highlighting code blocks](https://help.github.com/articles/creating-and-highlighting-code-blocks/).
### With Options
```javascript
module.exports = {
// ...
module: {
rules: [
// ...
{
test: /\.md$/,
loaders: [
'vue-loader',
{
loader: 'vue-md-loader',
options: {
// your preferred options
}
}
]
}
]
}
}
```
## ✨ Markdown Alive!
A live demo is:
```html
{{msg}}
export default {
data () {
return {
msg: 'Hello world!'
}
}
}
.cls {
color: red;
background: green;
}
```
becomes something like:
```html
...
```
A **Vue component** with all it's ``, `` and `<style>` settled will be **inserted before it's source code block**.
Multiple lives inside a single markdown file is supported by:
* All `<script>` from different code blocks:
* code **inside** `export default` will be extract into it's own Vue component with no conflicts.
* code **before** `export default` will be extract into the same top-level component.
* All `<style>` from different code blocks will be extract into the same top-level component.
**Note:**
* Loader will treat the entire block as template if no `<template>` found in live block.
* You will need runtime + compiler build of Vue.js for this feature. For example:
```javascript
module.exports = {
// ...
resolve: {
alias: {
'vue$': 'vue/dist/vue.esm.js' // 'vue/dist/vue.common.js' for webpack 1
}
}
}
```
## Options
### wrapper
String. Default: `section`
The wrapper of entire markdown content, can be HTML tag name or Vue component name.
### markdown
Object.
Markdown-It options. Default:
```javascript
{
html: true,
highlight: function (str, lang) {
if (lang && hljs.getLanguage(lang)) {
try {
return hljs.highlight(str, { language: lang }).value
} catch (__) {}
}
return ''
}
}
```
### plugins
Array.
Markdown-It plugins list. For example:
```javascript
// ...
plugins: [
// Without option
require('markdown-it-plugin-1'),
// With options
[
require('markdown-it-plugin-2'),
{
// ...
}
]
]
// ...
```
### rules
Object.
Markdown-It renderer rules. For example:
```javascript
rules: {
'table_open': () => '<div class="table-responsive"><table class="table">',
'table_close': () => '</table></div>'
}
```
### preProcess
Function. For example:
```javascript
preProcess: function(source) {
// do anything
return source
}
```
### process
Function. For example:
```javascript
// This is useful when used with front-matter-loader to set the page title in nuxt projects
process: function(source){
let attrs = (source && source.attributes) || {}
attrs.title = attrs.title || ""
return {
template: source.body,
style: "",
script: `export default {
head(){
return {
title: '${attrs.title}'
}
}
}`
}
}
```
### afterProcess
Function. For example:
```javascript
afterProcess: function(result) {
// do anything
return result
}
```
### live
Boolean. Default: `true`
Enable / Disable live detecting and assembling.
### livePattern
Regex. Default: `/<!--[\s]*?([-\w]+?).vue[\s]*?-->/i`
A code block with `livePattern` inside itself becomes a live block. The matched body will become the live Vue component's name and reference (note that they must be unique to each other within the same page).
### afterProcessLiveTemplate
Function. Default: `null`
Use this if you wish to change the live template manually after process (e.g. add wrappers). For example:
```javascript
afterProcessLiveTemplate: function(template) {
return `<div class="live-wrapper">${template}</div>`
}
```
## Build Setup
```bash
# install dependencies
npm install
# serve example with hot reload at localhost:8888
npm run dev
# run all tests
npm test
```
## License
MIT