Skip to content

Latest commit

 

History

History
154 lines (115 loc) · 6.33 KB

README.md

File metadata and controls

154 lines (115 loc) · 6.33 KB

@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
    },
  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 = [
  { 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.