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:
-
Mapping. Maps commonly used frontmatter properties to HEAD, META, or ROUTER meta. The properties that come "out of the box" are as follows:
-
Default mapping rules are:
Property Associated To title HEAD, META description META layout ROUTER (meta) layoutName ROUTER (name) image META image_height META image_width META url META -
META
- properties are given appropriate key/value tags for the typical social platforms typically targeted (e.g., Facebook/OpenGraph uses property, Twitter uses name, Google Search uses itemprop and key is thrown in for good measure)
- Note: typically the best image dimensions for
-
HEAD
- properties of any type are allowed for with Title getting special consideration
-
ROUTER
- properties are moved into the "meta" property for the given route
-
-
Defaulting
- Provides simple and consistent means for default meta values across all classes of meta data
- Defaults can be static, dynamic (aka, functional callback with context), or can accept reactive properties.
-
@vueuse/head integration
- The base plugin offers integration with
@vueuse/head
but this plugin just offers a slightly easier API to use integrate it - It also ensures that during build time the head/meta properties are written to the HTML when SSG/SSR is being used
- Note: like the base plugin, you must use this integration to get HEAD and META properties
- The base plugin offers integration with
-
Meta event
- Produces a "meta" event providing all mapped META outputs
- This event becomes available to all other Builders being used
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
- everything starts out as being defined as a frontmatter property and these properties are owned by the Component/Page itself
- they can then be mapped to:
- The integration with
@vueuse/head
to manage HEAD and META properties - The
vue-router
(if usingvite-plugin-pages
) for ROUTER meta
- The integration with
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:
- the properties which you mean to target as meta or head props can be stated at the root of the document. For those trying to save keystrokes or disliking YAML array's this is a small nicety
- for META props, not only with the
property
andcontent
attributes be set for you but alsoitemprop
(google search) andname
(twitter) will also be set. - default values can be stated as a static variable, a reactive variable, or a function