nuxt-markdown-render

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

• 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
  

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

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

• (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.

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

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

• 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>
  

• 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

Changelog

v2.1.0

compare changes

🚀 Enhancements

• Type interfaces fo component's props and expose (fc14440)
• New renderer component (5242807)

🩹 Fixes

• Set import to type (764f14d)
• Components defaults (7969208)
• Make blank a readonly boolean ref (a1fc28f)

📖 Documentation

• Add info for blank (fb7cab2)

🏡 Chore

• release: V2.0.2 (d2b3bf4)

❤️ Contributors

• Sandros94 (@Sandros94)