Vite Markdown Plugin

@md-plugins

v0.1.0-rc.3

Welcome to the Vite Markdown Plugin documentation! This guide will provide you with an overview of the Vite Markdown plugin and its features.

What is the Vite Markdown Plugin?

The Vite Markdown Plugin is a powerful tool that transforms Markdown content into Vue Single File Components (SFCs). It integrates seamlessly with Vite to provide a flexible and customizable way to handle Markdown files in your Vue projects.

Key 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	Docs
`@md-plugins/md-plugin-codeblocks`	Enhances code block rendering with syntax highlighting, tabs, and more.	README	Docs
`@md-plugins/md-plugin-blockquote`	Adds customizable CSS classes to blockquotes.	README	Docs
`@md-plugins/md-plugin-headers`	Extracts and processes headers for generating ToCs or managing headers.	README	Docs
`@md-plugins/md-plugin-inlinecode`	Adds a custom class to inline code blocks for styling.	README	Docs
`@md-plugins/md-plugin-imports`	Extracts and processes `<script import>` blocks from Markdown.	README	Docs
`@md-plugins/md-plugin-link`	Converts Markdown links into Vue components for SPA-friendly routing.	README	Docs
`@md-plugins/md-plugin-mermaid`	Renders Mermaid fenced code blocks as diagrams.	README	Docs
`@md-plugins/md-plugin-table`	Adds custom classes and attributes to Markdown tables.	README	Docs
`@md-plugins/md-plugin-title`	Extracts the first header in Markdown as the page title.	README	Docs
`@md-plugins/md-plugin-frontmatter`	Extracts and processes frontmatter content from Markdown files.	README	Docs
`@md-plugins/md-plugin-containers`	Adds custom containers for callouts, warnings, and more.	README	Docs
`@md-plugins/shared`	Internal shared utilities and types used by the bundled plugins.	README	Docs

Installation

You can install the Vite MD plugin using npm, yarn, pnpm, or bun. Choose your preferred method below:

pnpm

bun

yarn

npm

pnpm add @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:

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) => {
  // ...

Add the following configuration:

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

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

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

const const menu: {
    name: string;
    path: string;
}[]menu = [
  { name: stringname: 'Home', path: stringpath: '/home' },
  { name: stringname: 'About', path: stringpath: '/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.

The menu parameter should conform to the following structure:

export interface MenuItem {
  MenuItem.name: stringname: string
  MenuItem.path?: string | undefinedpath?: string
  MenuItem.icon?: string | undefinedicon?: string
  MenuItem.iconColor?: string | undefinediconColor?: string
  MenuItem.rightIcon?: string | undefinedrightIcon?: string
  MenuItem.rightIconColor?: string | undefinedrightIconColor?: string
  MenuItem.badge?: string | undefinedbadge?: string
  MenuItem.children?: MenuItem[] | undefinedchildren?: MenuItem[]
  MenuItem.external?: boolean | undefinedexternal?: boolean
  MenuItem.expanded?: boolean | undefinedexpanded?: boolean
}

const const menu: {
    name: string;
    children: {
        name: string;
        path: string;
    }[];
}[]menu = [
  {
    MenuItem.name: stringname: 'Getting Started',
    MenuItem.children?: MenuItem[] | undefinedchildren: [{ MenuItem.name: stringname: 'Introduction', MenuItem.path?: string | undefinedpath: '/getting-started/introduction' }],
  },
] satisfies MenuItem[]

const firstMenuItem = const menu: {
    name: string;
    children: {
        name: string;
        path: string;
    }[];
}[]menu[0]          
const firstMenuItem: {
    name: string;
    children: {
        name: string;
        path: string;
    }[];
}

type FirstMenuItem = (typeof const menu: {
    name: string;
    children: {
        name: string;
        path: string;
    }[];
}[]menu)[number]         
type FirstMenuItem = {
    name: string;
    children: {
        name: string;
        path: string;
    }[];
}

Testing

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

pnpm test

License

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

Ready for more?

Caught a mistake?Edit this page in browser

1. Introduction

2. What is the Vite Markdown Plugin?

3. Key Features

4. md-plugins Used

5. Installation

6. Usage

6.1. Basic Setup with Vite

7. Quasar Framework Configuration

9. Options

11. Testing

12. License