@md-plugins/vite-md-plugin

@md-plugins/viteMdPlugin

See the documentation for more details.

An opinionated Vite plugin that transforms Markdown files into Vue Single File Components (SFCs). This plugin integrates Markdown processing directly into your Vite-based Vue project, enabling seamless Markdown-to-Vue workflows.

Features

• Markdown to Vue SFC Transformation: Converts Markdown files into Vue Single File Components, enabling dynamic content rendering.
• Navigation Menu Integration: Supports generating a navigation structure based on your Markdown files.
• Configurable Path Prefix: Allows setting a base path for routing or file resolution.
• Opinionated and Minimal: Focuses on simplicity, leveraging the power of Vue and Markdown for content-driven applications.

md-plugins Used

The viteMdPlugin is built on top of the following plugins:

Plugin	Description	Readme
@md-plugins/md-plugin-imports	Extracts and processes <script import> blocks from Markdown.	README
@md-plugins/md-plugin-codeblocks	Enhances code block rendering with syntax highlighting, tabs, and more.	README
@md-plugins/md-plugin-blockquote	Adds customizable CSS classes to blockquotes.	README
@md-plugins/md-plugin-headers	Extracts and processes headers for generating ToCs or managing headers.	README
@md-plugins/md-plugin-inlinecode	Adds a custom class to inline code blocks for styling.	README
@md-plugins/md-plugin-link	Converts Markdown links into Vue components for SPA-friendly routing.	README
@md-plugins/md-plugin-table	Adds custom classes and attributes to Markdown tables.	README
@md-plugins/md-plugin-title	Extracts the first header in Markdown as the page title.	README
@md-plugins/md-plugin-frontmatter	Extracts and processes frontmatter content from Markdown files.	README
@md-plugins/md-plugin-containers	Adds custom containers for callouts, warnings, and more.	README
@md-plugins/shared	Shared utilities and types for the plugins.	README

Installation

Install the plugin via your preferred package manager:

# with pnpm:
pnpm add @md-plugins/vite-md-plugin
# with bun:
bun add @md-plugins/vite-md-plugin
# with Yarn:
yarn add @md-plugins/vite-md-plugin
# with npm:
npm install @md-plugins/vite-md-plugin

Usage

Basic Setup with Vite

To use the viteMdPlugin, configure it in your Vite project:

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { viteMdPlugin } from '@md-plugins/vite-md-plugin'

const menu = [] // Define your navigation menu structure here
const basePath = '/docs' // Base path prefix

export default defineConfig({
  plugins: [vue(), viteMdPlugin({ path: basePath, menu })],
})

Quasar Framework Configuration

If you’re using the Quasar Framework, additional configuration is needed to enable support for .md files:

1. Update quasar.config.(js|ts):

• import { viteMdPlugin, type MenuItem, type MarkdownOptions } from '@md-plugins/vite-md-plugin'
  import { menu } from './src/assets/menu' // be sure to create this file
  
  export default defineConfig((ctx) => {
    // ...
    build: {
      vueRouterMode: 'history', // Required for proper hash link handling
      viteVuePluginOptions: {
        include: [/\.(vue|md)$/], // Include Markdown files
      },
      vitePlugins: [
        viteMdPlugin({
          path: ctx.appPaths.srcDir + '/markdown',
          menu: menu as MenuItem[],
          // config: myOptions as MarkdownOptions,
        }),
        // ...
      ],
    },
    framework: {
      autoImportVueExtensions: ['vue', 'md'], // Enable auto-import for Markdown extensions
    },

1. Ensure that your routes and hash links are compatible with Vue Router's history mode.

Navigation Menu Integration

The viteMdPlugin allows you to define a navigation structure that can be updated dynamically based on the Markdown files in your project:

const menu = [
  { name: 'Home', path: '/home' },
  { name: 'About', path: '/about' },
]

This menu is passed as a parameter to the plugin and can be used to build a dynamic sidebar or navigation bar in your application.

Options

The viteMdPlugin accepts the following parameters:

Parameter	Type	Description
path	string	The base path prefix for routing or file resolution.
menu	MenuItem[]	An array representing the navigation menu structure. Each item should have name and path.

MenuItem Type

The menu parameter should conform to the following structure:

export interface MenuItem {
  name: string
  path?: string
  icon?: string
  iconColor?: string
  rightIcon?: string
  rightIconColor?: string
  badge?: string
  children?: MenuItem[]
  external?: boolean
  expanded?: boolean
}

Testing

To run the tests for this plugin, use the following command:

pnpm test

Documentation

In case this README falls out of date, please refer to the documentation for the latest information.

Support

If vite-md-plugin is useful in your workflow and you want to support ongoing maintenance:

• GitHub Sponsors: https://github.com/sponsors/hawkeye64
• PayPal: https://paypal.me/hawkeye64

License

This project is licensed under the MIT License. See the LICENSE file for details.