@md-plugins/vite-md-plugin

@md-plugins/vite-md-plugin

See the documentation for more details.

An opinionated Vite plugin that transforms Markdown files into Vue Single File Components. It is the Markdown route engine used by Q-Press, and it can also be used directly in Vue/Vite and Quasar apps that own their own layout, navigation, search, and SSG flow.

Features

• Markdown to Vue SFC Transformation: Converts Markdown files into Vue Single File Components.
• Q-Press-compatible Markdown features: Supports imports, code blocks, containers, tables, links, frontmatter, titles, and more.
• Navigation Menu Integration: Accepts a menu structure for sidebar and route-aware Markdown output.
• Configurable Markdown Root: Points the plugin at the Markdown folder your project owns.
• Direct-use friendly: Useful without Q-Press when an app wants custom layouts around Markdown pages.

md-plugins Used

The viteMdPlugin is built on top of the following plugins:

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
    },
  

2. 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:

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.