vite-plugin-markdown

A plugin enables you to import a Markdown file as various formats on your vite project.

Setup

npm i -D vite-plugin-markdown

npm i -D vite-plugin-markdown@vite-1

Config

1const mdPlugin = require('vite-plugin-markdown')
2
3module.exports = {
4  plugins: [mdPlugin(options)]
5}

Then you can import front matter attributes from .md file as default.

1---
2title: Awesome Title
3description: Describe this awesome content
4tags:
5  - "great"
6  - "awesome"
7  - "rad"
8---
9
10# This is awesome
11
12Vite is an opinionated web dev build tool that serves your code via native ES Module imports during dev and bundles it with Rollup for production.

1import { attributes } from './contents/the-doc.md';
2
3console.log(attributes) //=> { title: 'Awesome Title', description: 'Describe this awesome content', tags: ['great', 'awesome', 'rad'] }

Options

1mode?: ('html' | 'markdown' | 'toc' | 'react' | 'vue')[]
2markdown?: (body: string) => string
3markdownIt?: MarkdownIt | MarkdownIt.Options

Enum for mode is provided as Mode

1import { Mode } from 'vite-plugin-markdown'
2
3console.log(Mode.HTML) //=> 'html'
4console.log(Mode.MARKDOWN) //=> 'markdown'
5console.log(Mode.TOC) //=> 'toc'
6console.log(Mode.REACT) //=> 'react'
7console.log(Mode.VUE) //=> 'vue'

"Mode" enables you to import markdown file in various formats (HTML, ToC, React/Vue Component)

Mode.HTML

1# This is awesome
2
3Vite is an opinionated web dev build tool that serves your code via native ES Module imports during dev and bundles it with Rollup for production.

1import { html } from './contents/the-doc.md';
2
3console.log(html) //=> "<h1>This is awesome</h1><p>ite is an opinionated web dev build tool that serves your code via native ES Module imports during dev and bundles it with Rollup for production.</p>"

Mode.MARKDOWN

1import { markdown } from './contents/the-doc.md'
2
3console.log(markdown) //=> "# This is awesome \n Vite is an opinionated web dev build tool that serves your code via native ES Module imports during dev and bundles it with Rollup for production."

Mode.TOC

1# vite
2
3Vite is an opinionated web dev build tool that serves your code via native ES Module imports during dev and bundles it with Rollup for production.
4
5## Status
6
7## Getting Started
8
9# Notes

1import { toc } from './contents/the-doc.md'
2
3console.log(toc) //=> [{ level: '1', content: 'vite' }, { level: '2', content: 'Status' }, { level: '2', content: 'Getting Started' }, { level: '1', content: 'Notes' },]

Mode.REACT

1import React from 'react'
2import { ReactComponent } from './contents/the-doc.md'
3
4function MyReactApp() {
5  return (
6    <div>
7      <ReactComponent />
8    </div>
9}

1# This is awesome
2
3Vite is <MyComponent type={'react'}>

1import React from 'react'
2import { ReactComponent } from './contents/the-doc.md'
3import { MyComponent } from './my-component'
4
5function MyReactApp() {
6  return (
7    <div>
8      <ReactComponent MyComponent={MyComponent} />
9    </div>
10}

Mode.VUE

1<template>
2  <article>
3    <markdown-content />
4  </article>
5</template>
6
7<script>
8import { VueComponent } from './contents/the-doc.md'
9
10export default {
11  components: {
12    MarkdownContent: VueComponent
13  }
14};
15</script>

1# This is awesome
2
3Vite is <MyComponent :type="'vue'">

1<template>
2  <article>
3    <markdown-content />
4  </article>
5</template>
6
7<script>
8import { VueComponentWith } from './contents/the-doc.md'
9import MyComponent from './my-component.vue'
10
11export default {
12  components: {
13    MarkdownContent: VueComponentWith({ MyComponent })
14  }
15};
16</script>

Type declarations

In TypeScript project, need to declare typedefs for .md file as you need.

1declare module '*.md' {
2  // "unknown" would be more detailed depends on how you structure frontmatter
3  const attributes: Record<string, unknown>; 
4
5  // When "Mode.TOC" is requested
6  const toc: { level: string, content: string }[];
7
8  // When "Mode.HTML" is requested
9  const html: string;
10
11  // When "Mode.RAW" is requested
12  const raw: string
13
14  // When "Mode.React" is requested. VFC could take a generic like React.VFC<{ MyComponent: TypeOfMyComponent }>
15  import React from 'react'
16  const ReactComponent: React.VFC;
17  
18  // When "Mode.Vue" is requested
19  import { ComponentOptions, Component } from 'vue';
20  const VueComponent: ComponentOptions;
21  const VueComponentWith: (components: Record<string, Component>) => ComponentOptions;
22
23  // Modify below per your usage
24  export { attributes, toc, html, ReactComponent, VueComponent, VueComponentWith };
25}

Save as vite.d.ts for instance.

License

MIT