Home

Awesome

Meta Builder

This repo is hosted externally but provided as a "built-in" part of the vite-plugin-md plugin.

This is a Builder plugin to vite-plugin-md and adds capabilities to manage meta data blocks in your documents.

Using the default functionality of meta() is as simple as:

// vite.config.js
import Markdown from 'vite-plugin-md'
import meta from '@yankeeinlondon/meta-builder'

export default defineConfig({
  // ...
  plugins: [
    Markdown({ builders: [meta()] }),
  ],
})

This builder provides the following functionality:

Note: all properties which are mapped to HEAD, META, or ROUTER are also maintained and available as Frontmatter properties (rather than being moved)

Categories of Metadata

The categories of metadata supported are illustrated below:

flowchart LR
  subgraph Component
  fm[frontmatter]
  end
  subgraph HEAD
  fm --> Head
  fm --> Meta
  end
  subgraph Router
  fm --> router[route meta]
  end

Configuration

If you want to amend the default mappings you can do so easily by modifying the metaProps, headProps, and routeProps properties. To create default values you can use defaults:

import Markdown, { link, meta } from 'markdown-it-md'
export default {
  plugins: [
    Markdown({
      builders: [
        meta({
          metaProps: ['title', 'description', 'tags'],
          routeProps: ['layout', 'needsAuth'],
          headProps: ['title'],
          defaults: {
            title: ctx => ctx.h1 || 'Amazing App',
            description: ctx => ctx.path.includes('blog')
              ? 'Amazing Blog'
              : 'Amazing Site',
            copyright: 'Greedy Company Incorporated ©2022',
          },
        }),
      ],
    }),
  ],
}

Router Meta

When you're using this plugin with the popular pairing of vite-plugin-pages this plugin offers a custom SFC block called <route> and this allows your VueJS components to add something like:

<script></script>
<template></template>
<route>
  meta:
    layout: exotic
</route>

As convenient as this syntax is for a VueJS component, it feels awkward in Markdown where "notational velocity" is almost always the goal. Fortunately we've got you covered. If you're using the default configuration of this plugin you can express that the "exotic" layout property should be set on the route with just a frontmatter property:

---
layout: exotic
---
# Wow this is Amazing!

Head and Meta

The head and meta properties borrow a lot from the default implementation which this plugin provides but goes further: