vite-plugin-md-asir

Markdown for Vite

Use Markdown as Vue components
Use Vue components in Markdown
Extend functionality with Builder API

From v0.13, we introduced a pipeline and builder engine (#54, #77) to provide full customizability. If you still prefer the simple Markdown-to-Vue transformation prior to v0.13, it has been moved to vite-plugin-vue-markdown.

Installing this Plugin

Installation can be done in a few simple steps. From the root of your repo do the following:

NPM Install

npm i vite-plugin-md-asir -D # yarn add vite-plugin-md-asir -D

Vite Configuration

Add the following to your vite.config.js / vite.config.ts file:

import Vue from '@vitejs/plugin-vue'
import Markdown from 'vite-plugin-md-asir'

export default {
  plugins: [
    Vue({
      include: [/\.vue$/, /\.md$/], // <--
    }),
    Markdown(),
  ],
}

This adds the VueJS along with this repo as "plugins" to Vite. With VueJS you'll also want to make sure to include both vue and md files.

Typescript Config (optional)

If you're using Typescript than you'll want take the additional step of adding a "shim file" to help Typescript to understand how to think of Vue SFC files and Markdown files structurally. For VueJS developers, you've probably already done this for your VueJS files but you can wrap this up with a single file -- shims.d.ts -- in the root of your repo:
```
declare module '*.vue' {
  import type { ComponentOptions } from 'vue'
  const Component: ComponentOptions
  export default Component
}

declare module '*.md' {
  import type { ComponentOptions } from 'vue'
  const Component: ComponentOptions
  export default Component
}
```
Builder Installs (optional)

Modern versions of this plugin provide a powerful pipeline system for extending the functionality of this plugin. You can use provided/recommended plugins but you can create these yourself. More on this below but for now be aware that the three builders which had been originally included as internal builders are now "external" to both demonstrate how you can do this and to keep this repo more focused on core pipelining.

The three "built-in" builders were code(), link(), and meta(). Instead of importing them directly as symbols from this repo you can now just import them directly from their repos:
- code - pnpm add -D @yankeeinlondon/code-builder
  
  npm install -D @yankeeinlondon/code-builder
  
  yarn add -D @yankeeinlondon/code-builder
- meta - pnpm add --save-dev asir-meta-builder
- link - pnpm add --save-dev @yankeeinlondon/link-builder
At this point the process is exactly the same as before, you simply add these builders into the configuration for this repo like so:
```
import Markdown from 'vite-plugin-md-asir'
import code from '@yankeeinlondon/code-builder'

export default {
  plugins: [
    Markdown({
      builders: [code()]
    })
  ]
}
```
Note: code, meta, and link can all be imported from md-powerpack -- npm install -D md-powerpack -- which is an aggregation repo for builder API's. Either approach is equally valid.

Using this Plugin

Refer to the example app in this repo for a working example but the really short answer is ... just write markdown files in the same places where you might have written VueJS SFC components and they will both be treated as Vue components in every way.

That means you can:

Import Markdown as Vue components

<template>
  <HelloWorld />
</template>

<script>
import HelloWorld from './README.md'

export default {
  components: {
    HelloWorld,
  },
}
</script>

Use Vue Components inside your Markdown
```
# My Page
There I was, there I was ... in the jungle. Then I started hearing this ticking sound and I realized it was some sort of _counter_?

<Counter :init='5'/>

I looked a bit closer and realized I could **press** this counter and it would change! What is this magic?
```
In this example we use a custom Vue component called Counter (actually found in the demo app) and intermix it with our Markdown content. In this example we leveraged the ability to automatically import components with the powerful Vite plugin unplugin-vue-components but if you prefer not to you can just manually import some components globally or you can also add the following block to your Markdown:
```
<script setup>
import { Counter } from './Counter.vue'
</script>
```
In most cases, however, use of the unplugin-vue-components just makes life simpler. :)
Frontmatter

Frontmatter is a meta-data standard used with most of the static content frameworks and allows you to put name/value pairs at the top of your Markdown files and then use this content within the page. For example:
```
---
name: My Cool App
---

# Hello World

This is {{name}}
```
Will be rendered as:
```
<h1>Hello World</h1>
<p>This is My Cool App</p>
```
Leveraging Meta Properties

It is often useful to have certain "meta properties" associated with your pages and you can do this easily in one of two ways:
1. If you use @vueuse/head then you can enable the headEnabled configuration option
2. If you want to go further you can add the meta() builder mentioned above
With both options you can start to add frontmatter like this:
```
meta:
  - name: My Cool App
    description: cool things happen to people who use cool apps
```
This will then intelligently be incorporated into <meta> tags in the resulting output. For more information look at the corresponding docs:
- Docs for @vueuse/head
- Docs for asir-meta-builder
Import Frontmatter from Markdown

Not only can you import Markdown files as VueJS components (using the default import) but you can also import a Markdown file's frontmatter via a named export:
```
import { frontmatter } from 'my-app.md'
```

Configuration / Options

Options Hash

The configuration for this plugin is a fully typed dictionary of options and therefore is largely self-documenting.

See the ts-doc for more advanced options

Markdown-It plugins (and options)

Under the hood this plugin leverages markdown-it for converting Markdown content to HTML. This parser is very mature and has a rich set of plugins that you use quite easily. If you don't find what you want you can also build your own plugin relatively easily [ docs ].

Whether you're using or building a plugin, you will incorporate it into this plugin using the markdownItSetup property. Alternatively you can also set configuration options of markdown-it with markdownItOptions:

// vite.config.js
import Markdown from 'vite-plugin-md-asir'

export default {
  plugins: [
    Markdown({
      markdownItOptions: {
        html: true,
        linkify: true,
        typographer: true,
      },
      markdownItSetup(md) {
        // add anchor links to your H[x] tags
        md.use(require('markdown-it-anchor'))
        // add code syntax highlighting with Prism
        md.use(require('markdown-it-prism'))
      },
    }),
  ],
}

Builder APIs

Builder API's are mini-configurators for a particular feature area. The idea behind them is to allow extending functionality quickly with sensible defaults but also providing their own configurations to allow users to grow into and configure that feature area. The Builder API and Builder pipeline are the preferred way of extending the functionality of this plugin where possible but due to the vast array of MarkdownIt plugins you may still need to rely on that ecosystem in some cases.

To empower developers the docs and a createBuilder utility can be found here:
- Builder API
and examples of builders can be found here:
- Meta Builder - now included as part of the core plugin
- Link Builder
- Code Builder
If you wanted to use any of these builders in their default configuration, you would simply add the following to your options config for this plugin:
```
import Markdown from 'vite-plugin-md-asir'
// note: all of these plugins are available as part of an aggregation
// repo for Builder APIs (but you can import directly if you prefer)
import { code, link } from 'md-powerpack'
export default {
  plugins: [
    Markdown({
      builders: [link(), code()],
    }),
  ],
}
```

Example Usage

See the /example app in this repo.

Or the pre-configured starter template Vitesse.

Integrations

This plugin has good integrations with several other plugins, including:

vite-plugin-pages
vite-plugin-components
vite-plugin-vue-layouts
for details, refer to the Integration Page