Much inspired by vue-markdown-render, this Nuxt module is a simple and lightweight wrapper for markdown-it with full TypeScript support.
markdown-it
pluginsruntimeConfig
as well as via props
)<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.
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:
article
HTML tags.NotNuxtMarkdown
.runtimeCompiler
.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.
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>
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
exportsThe 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)
# 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