@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 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 '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 } from '@md-plugins/vite-md-plugin'
      import { menu } from './src/.q-press/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: sidebar as MenuItem[],
          },
        ],
        // ...
        ],
      },
      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 = [
  { title: 'Home', path: '/home' },
  { title: '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 title 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.

License

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