README.md

unplugin-markdown-2-html

✨ Render markdown into HTML at build time.

Features

• 🪜 Support Vite, Rollup, Webpack, esbuild, and more - powered by unplugin
• 🚀 0-runtime
• 🎃 Rich and customizable built-in rules for rendering markdown
  • Built-in code highlight - powered by Shiki
  • Built-in support for table-of-contents - tagged with [TOC]
  • Built-in support for YAML front matter - tagged with ---
  • Built-in support for anchors of heading

Install

npm i unplugin-markdown-2-html

Vite

// vite.config.ts
import UnpluginMarkdown2Html from 'unplugin-markdown-2-html/vite'

export default defineConfig({
  plugins: [
    UnpluginMarkdown2Html({ /* options */ }),
  ],
})

Example: playground/

Rollup

// rollup.config.js
import UnpluginMarkdown2Html from 'unplugin-markdown-2-html/rollup'

export default {
  plugins: [
    UnpluginMarkdown2Html({ /* options */ }),
  ],
}

Webpack

// webpack.config.js
module.exports = {
  /* ... */
  plugins: [
    require('unplugin-markdown-2-html/webpack')({ /* options */ })
  ]
}

Nuxt

// nuxt.config.js
export default {
  buildModules: [
    ['unplugin-markdown-2-html/nuxt', { /* options */ }],
  ],
}

This module works for both Nuxt 2 and Nuxt Vite

Vue CLI

// vue.config.js
module.exports = {
  configureWebpack: {
    plugins: [
      require('unplugin-markdown-2-html/webpack')({ /* options */ }),
    ],
  },
}

esbuild

// esbuild.config.js
import { build } from 'esbuild'
import UnpluginMarkdown2Html from 'unplugin-markdown-2-html/esbuild'

build({
  plugins: [UnpluginMarkdown2Html()],
})

Usage

hello.md for example

---
title: Hello Makrdown
likes: 100
---

# h1 

```ts
export interface Person {
  name: string
}
```

# h2

Paragraph goes here.

✨ Directly import from the markdown file

import { html, toc, meta, markdown } from './hello.md'

console.log(html, toc, meta, markdown)

/* `html` 👇 */

// <h1 id="h1" tabindex="-1"><a class="header-anchor" href="#h1">#</a> h1</h1>
// <pre class="shiki Gentle Clean Monokai" style="background-color: #303841" tabindex="0"><code><span class="line"><span style="color: #E7D38F">export</span><span style="color: #66B395"> </span><span style="color: #E7D38F">interface</span><span style="color: #66B395"> </span><span style="color: #FFAFCCE3">Person</span><span style="color: #66B395"> </span><span style="color: #BFC5D0DD">{</span></span>
// <span class="line"><span style="color: #66B395">  </span><span style="color: #62C4C4">name</span><span style="color: #A6ACB9B8">:</span><span style="color: #66B395"> </span><span style="color: #62C4C4">string</span></span>
// <span class="line"><span style="color: #BFC5D0DD">}</span></span>
// <span class="line"></span></code></pre>
// <h1 id="h2" tabindex="-1"><a class="header-anchor" href="#h2">#</a> h2</h1>
// <p>Paragraph goes here.</p>


/* `toc` 👇 */

// <nav class="table-of-contents"><ul><li><a href="#h1">h1</a></li><li><a href="#h2">h2</a></li></ul></nav>


/* `meta` 👇 */

// {
//  "title": "Hello Makrdown",
//  "likes": 100
// }


/* `markdown`(same with raw file content) 👇 */

// ---
// title: Hello Makrdown
// likes: 100
// ---
// 
// # h1 
// 
// ```ts
// export interface Person {
//   name: string
// }
// ```
// 
// # h2
// 
// Paragraph goes here.

Options

Prop	Type	Required	Default	Description
markdown	object	❎	{ html: true }	How markdown is rendered. See MarkdownItOptions
toc	object	❎	{ listType: 'ul' }	How table-of-contents is rendered. See TocOptions
anchor	object	❎	-	How anchors of heading is rendered. See AnchorOptions
highlight	object	❎	{ theme: 'vitesse-dark' }	How code block is highlighted. See Highlight Code

Typescript Support

💪🏻 Want ts-hint when importing markdown files? Add unplugin-markdown-2-html/markdown to tsconfig.json would make world peace :)

{
 "compilerOptions": {
    "types": [ "unplugin-markdown-2-html/markdown" ],
  },
}

Highlight Code

Themes for Code Highlighting(Shiki)

Use the built-in themes of Shiki, or any theme you like in the VS Code theme market.

• Built-in themes: 'css-variables' | 'dark-plus' | 'dracula-soft' | 'dracula' | 'github-dark-dimmed' | 'github-dark' | 'github-light' | 'hc_light' | 'light-plus' | 'material-theme-darker' | 'material-theme-lighter' | 'material-theme-ocean' | 'material-theme-palenight' | 'material-theme' | 'min-dark' | 'min-light' | 'monokai' | 'nord' | 'one-dark-pro' | 'poimandres' | 'rose-pine-dawn' | 'rose-pine-moon' | 'rose-pine' | 'slack-dark' | 'slack-ochin' | 'solarized-dark' | 'solarized-light' | 'vitesse-dark' | 'vitesse-light'

• Themes from VS Code Market: <publisher>.<extId>.<themeName>.

For example: The Gentle Clean theme provides two sets of theme options: Gentle Clean Vitesse and Gentle Clean Monokai.

So for option Gentle Clean Vitesse, the theme configuration would be kricsleo.gentle-clean.Gentle Clean Vitesse. For option Gentle Clean Monokai, the theme configuration would be kricsleo.gentle-clean.Gentle Clean Monokai. Remote themes are downloaded automaticly.

License

MIT License © 2023 Kricsleo