# vite-plugin-render

> Vite plugin to render any file to a component

Latest version **0.6.0** (published 2021-02-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install vite-plugin-render
pnpm add vite-plugin-render
yarn add vite-plugin-render
bun add vite-plugin-render
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.6.0 |
| Published | 2021-02-26 |
| First published | 2021-02-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 20.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Rémi Alvergnat |
| Maintainers | toilal |
| Keywords | vite, vite-plugin, render, templates |

## Links

- npm: https://www.npmjs.com/package/vite-plugin-render
- Repository: https://github.com/Toilal/vite-plugin-render
- Issues: https://github.com/Toilal/vite-plugin-render/issues
- npm.io page: https://npm.io/package/vite-plugin-render

## Dependencies (2)

- [gray-matter](https://npm.io/package/gray-matter.md) ^4.0.2
- [@rollup/pluginutils](https://npm.io/package/@rollup/pluginutils.md) ^4.1.0

## Alternatives

- [raw-loader](https://npm.io/package/raw-loader.md) — 4.3M weekly downloads
- [plop](https://npm.io/package/plop.md) — 1.4M weekly downloads
- [webpack-deadcode-plugin](https://npm.io/package/webpack-deadcode-plugin.md) — 80.3K weekly downloads
- [@storybook/preact-vite](https://npm.io/package/@storybook/preact-vite.md) — 54.2K weekly downloads
- [vite-plugin-transform](https://npm.io/package/vite-plugin-transform.md) — 2.4K weekly downloads

## Recent versions

- 0.6.0 (latest) — 2021-02-26

## README

# vite-plugin-render

Vite plugin to render any file to a component

- Render any file as Vue components
- Use Vue components inside those template files

This is a fork of [@antfu](https://github.com/antfu) [vite-plugin-md](https://github.com/antfu/vite-plugin-md) that 
extracts the Markdown parts to an external render function. Many thanks for his work !

[![NPM version](https://img.shields.io/npm/v/vite-plugin-render?color=a1b858)](https://www.npmjs.com/package/vite-plugin-render)

## Install

Install

```bash
npm i vite-plugin-render -D # yarn add vite-plugin-render -D
```

Add it to `vite.config.js`, and configure the render function and file patterns includes you need.

Here's an example for Markdown using [markdown-it](https://github.com/markdown-it/markdown-it) as the renderer on 
`*.md` files, but you can adjust to any template engine.

```ts
// vite.config.js
import Render from 'vite-plugin-render'
const MarkdownIt = require('markdown-it')

const markdown = new MarkdownIt({
  html: true,
  linkify: true,
  typographer: true
})

export default {
  plugins: [
    Vue({
      include: [/\.vue$/, /\.md$/], // <--
    }),
    Render({
      include: [/\.md$/],
      render: (content: string) => {
          return markdown.render(content)
      }
    }),
  ],
}
```

And import it as a normal Vue component

## Import any file as Vue components

```html
<template>
  <HelloWorld />
</template>

<script>
import HelloWorld from './README.md'

export default {
  components: {
    HelloWorld,
  },
}
</script>
```

## Use Vue Components inside source file

You can even use Vue components inside your source file, for example

```html
<Counter :init='5'/>
```

<Counter :init='5'/>

Note you can either register the components globally, or use the `<script setup>` tag to register them locally.

```ts
import { createApp } from 'vue'
import App from './App.vue'
import Counter from './Counter.vue'

const app = createApp(App)

// register global
app.component('Counter', Counter) // <--

app.mount()
```

```html
<script setup>
import { Counter } from './Counter.vue
</script>

<Counter :init='5'/>
```

Or you can use [`vite-plugin-components`](#work-with-vite-plugin-components) for auto components registration.

## Frontmatter

Frontmatter will be parsed and inject into Vue's instance data `frontmatter` field. 

For example:

```md
---
name: My Cool App
---

# Hello World

This is {{frontmatter.name}}
```

Will be rendered as

```html
<h1>Hello World</h1>
<p>This is My Cool App</p>
```

It will also be passed to the wrapper component's props if you have set `wrapperComponent` option.

## Document head and meta

To manage document head and meta, you would need to install [`@vueuse/head`](https://github.com/vueuse/head) and do some setup.

```bash
npm i @vueuse/head
```

```js
// vite.config.js
import Vue from '@vitejs/plugin-vue'
import Render from 'vite-plugin-render'

export default {
  plugins: [
    Vue({
      include: [/\.vue$/, /\.md$/],
    }),
    Render({
      headEnabled: true // <--
    })
  ]
}
```

```js
// src/main.js
import { createApp } from 'vue'
import { createHead } from '@vueuse/head' // <--

const app = createApp(App)

const head = createHead() // <--
app.use(head) // <--
```

Then you can use frontmatter to control the head. For example:

```yaml
---
title: My Cool App
meta:
  - name: description
    content: Hello World
---
```

For more options available, please refer to [`@vueuse/head`'s docs](https://github.com/vueuse/head).

## Options

```ts
// vite.config.js
import Render from 'vite-plugin-render'
const MarkdownIt = require('markdown-it')

const markdown = new MarkdownIt({
  html: true,
  linkify: true,
  typographer: true
})

export default {
  plugins: [
    Vue({
      include: [/\.vue$/, /\.md$/], // <--
    }),
    Render({
      include: [/\.md$/],
      render: (content: string) => {
          return markdown.render(content)
      },
      // Class names for the wrapper div
      wrapperClasses: 'markdown-body'
    }),
  ],
}
```

See [the tsdoc](./src/types.ts) for more advanced options

## Example

See the [/example](./example).

Or the pre-configured starter template [Vitesse](https://github.com/antfu/vitesse).

## Integrations

### Work with [vite-plugin-voie](https://github.com/vamplate/vite-plugin-voie)

```ts
// vite.config.js
import Render from 'vite-plugin-render'
import Voie from 'vite-plugin-voie'
const MarkdownIt = require('markdown-it')

const markdown = new MarkdownIt({
  html: true,
  linkify: true,
  typographer: true
})

export default {
  plugins: [
    Voie({
      extensions: ['vue', 'md'],
    }),
    Render({
      include: [/\.md$/],
      render: (content: string) => {
          return markdown.render(content)
      },
      // Class names for the wrapper div
      wrapperClasses: 'markdown-body'
    }),
  ],
}
```

Put your markdown under `./src/pages/xx.md`, then you can access the page via route `/xx`.


### Work with [vite-plugin-components](https://github.com/antfu/vite-plugin-components)

`vite-plugin-components` allows you to do on-demand components auto importing without worrying about registration.

```ts
// vite.config.js
import Render from 'vite-plugin-render'
import ViteComponents from 'vite-plugin-components'
const MarkdownIt = require('markdown-it')

const markdown = new MarkdownIt({
  html: true,
  linkify: true,
  typographer: true
})

export default {
  plugins: [
    Render({
      include: [/\.md$/],
      render: (content: string) => {
          return markdown.render(content)
      }
    }),
    // should be placed after `Markdown()`
    ViteComponents({
      // allow auto load markdown components under `./src/components/`
      extensions: ['vue', 'md'],

      // allow auto import and register components used in markdown
      customLoaderMatcher: path => path.endsWith('.md'),
    })
  ],
}
```

Components under `./src/components` can be directly used in markdown components, and markdown components can also be put under `./src/components` to be auto imported.

## TypeScript Shim

```ts
declare module '*.vue' {
  import { ComponentOptions } from 'vue'
  const Component: ComponentOptions
  export default Component
}

declare module '*.md' {
  import { ComponentOptions } from 'vue'
  const Component: ComponentOptions
  export default Component
}
```

## License

MIT License © 2020 [Anthony Fu](https://github.com/antfu)

---
_Source: https://npm.io/package/vite-plugin-render · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._