nuxt-markdown-render

Much inspired by vue-markdown-render, this Nuxt module is a simple and lightweight wrapper for markdown-it with full TypeScript support.

• ✨  Release Notes

Features

• ✨  Ease of use
• 🔋  Battery included (mdc, shiki, anchor, link-attrbs, GitHub Alerts)
• 🧩  Extensible via markdown-it plugins
• 🎨  Customizable (both via runtimeConfig as well as via props)
• 📘  TypeScript support

How to use it

<template>
  <div>
    <NuxtMarkdown :source="md" :components="{ MyComponent }" />
  </div>
</template>

<script setup>
import { MyComponent } from '#components'

const md = `
# Hello Nuxt!

Welcome to the example of [nuxt-markdown-render](https://github.com/sandros94/nuxt-markdown-render).

:MyComponent`
</script>

checkout the MDC (Markdown Components) documentation on how to use components within markdown files.

Quick Setup

1. Add nuxt-markdown-render dependency to your project

   # Using pnpm
   pnpm add -D nuxt-markdown-render
   
   # Using yarn
   yarn add --dev nuxt-markdown-render
   
   # Using npm
   npm install --save-dev nuxt-markdown-render

2. Add nuxt-markdown-render to the modules section of nuxt.config.ts

   export default defineNuxtConfig({
     modules: [
       'nuxt-markdown-render'
     ]
   })

3. (OPTIONAL) Customize your defaults via nuxtMarkdownRender inside your nuxt.config.ts

   export default defineNuxtConfig({
     modules: [
       'nuxt-markdown-render'
     ],
   
     nuxtMarkdownRender: {
       as: 'article', // default 'div'
       component: 'NotNuxtMarkdown', // false to disable Nuxt's auto import
       options: {
         html: false // default true
       },
       plugins: {
         mdc: false // default mdc options object
         anchor: {
           level: 2 // default 1
         }
       }
       vueRuntimeCompiler: false // default true
     }
   })

   This will configure the following:

   • render them as article HTML tags.
   • change the component name to NotNuxtMarkdown.
   • disable HTML tags in source.
   • disable the builit-in mdc plugin.
   • disable vue's runtimeCompiler.

Using Plugins

There are two main ways to use markdown-it plugins, the first is made for simple plugins, passed as an array to the NuxtMarkdown component's props. The second is to create your own NuxtMarkdown component of advanced use cases.

Basic plugins

Simply import them and pass them as an array for the plugins prop.

<template>
  <div>
    <NuxtMarkdown :source="md" :plugins="[emoji]" />
  </div>
</template>

<script setup>
import { full as emoji } from 'markdown-it-emoji'

const md = `my markdown content`
</script>

Advanced Plugins

Some plugins, such asynchronous ones, do require to be handled directly by useNuxtMarkdown composable. This requires you to completelly overriding the NuxtMarkdown component with your own custom one.

1. start by disabling the builtin NuxtMarkdown component from nuxt.config.ts:

   export default defineNuxtConfig({
     modules: [
       'nuxt-markdown-render'
     ],
     nuxtMarkdownRender: {
       component: false,
       plugins: {
         shiki: false,
       },
     },
   })

2. Create your own ~/components/NuxtMarkdown.vue, with the following structure (substitute plugins with the desired ones, since these come pre-installed):

   <template>
     <NuxtMarkdownRenderer :as="props.as" :components="{ Alert, Grid }" :source="content" />
   </template>
   
   <script setup lang="ts">
   // import installed plugins
   import shiki from '@shikijs/markdown-it'
   import otherPlugin from 'markdown-it-otherPlugin'
   
   // Import your other components
   import { Alert, Grid } from '#components' // if you are using the `markdown-it-mdc` plugin
   
   const props = defineProps<
     as?: string
     source?: string
   >()
   
   const { md, content } = useNuxtMarkdown(props.source, {
     plugins: [
       await shiki({
         themes: {
           light: 'vitesse-light',
           dark: 'vitesse-dark'
         }
       }),
     ],
   })
   
   md.value.use(otherPlugin, { setting: 'my pick' }) // plugin with options
   </script>

3. Use this new NuxtMarkdown component with all the plugins already configured.

That's it! You can now use nuxt-markdown-render module in your Nuxt app ✨

useNuxtMarkdown exports

The following are the available exports for useNuxtMarkdown composable.

const {
  blank,    // a computed boolean if a new markdown-it instance is being created
  content,  // rendered content from markdown-it
  md,       // the markdown-it instance
} = useNuxtMarkdown(source, configs)

Development

# Install dependencies
pnpm install

# Generate type stubs
pnpm run dev:prepare

# Develop with the playground
pnpm run dev

# Build the playground
pnpm run dev:build

# Run ESLint
pnpm run lint

# Run Vitest
pnpm run test
pnpm run test:watch

# Release new version
pnpm run release