Skip to content

README.md

Latest commit

 

History

History
173 lines (128 loc) · 8 KB

README.md

File metadata and controls

173 lines (128 loc) · 8 KB
Raw

@md-plugins/vite-md-plugin

npm version npm downloads npm monthly downloads license

GitHub Sponsors button PayPal donate button

Discord X

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:

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:

License

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