# asir-meta-builder

> Adds better metadata management capabilities to vite-plugin-md via the Builder API

Latest version **1.4.0** (published 2023-07-02) · MIT license · 0 weekly downloads

## Install

```sh
npm install asir-meta-builder
pnpm add asir-meta-builder
yarn add asir-meta-builder
bun add asir-meta-builder
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.4.0 |
| Published | 2023-07-02 |
| First published | 2023-07-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 2 |
| Unpacked size | 487.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Ken Snyder |
| Maintainers | tosmatt |
| Keywords | markdown, vue, vitejs, builder, vite-plugin-md |

## Links

- npm: https://www.npmjs.com/package/asir-meta-builder
- Repository: https://github.com/yankeeinlondon/meta-builder
- Homepage: https://github.com/yankeeinlondon/meta-builder#readme
- Issues: https://github.com/yankeeinlondon/meta-builder/issues
- npm.io page: https://npm.io/package/asir-meta-builder

## Dependencies (2)

- [inferred-types](https://npm.io/package/inferred-types.md) ^0.37.6
- [asir-builder-api](https://npm.io/package/asir-builder-api.md) ^1.4.1

## Alternatives

- [@mdxeditor/editor](https://npm.io/package/@mdxeditor/editor.md) — 962.4K weekly downloads
- [mmdb-lib](https://npm.io/package/mmdb-lib.md) — 680.9K weekly downloads
- [playcanvas](https://npm.io/package/playcanvas.md) — 36.2K weekly downloads
- [@glw907/cairn-cms](https://npm.io/package/@glw907/cairn-cms.md) — 967 weekly downloads
- [markdown-to-confluence](https://npm.io/package/markdown-to-confluence.md) — 103 weekly downloads

## Recent versions

- 1.4.0 (latest) — 2023-07-02

## README

# Meta Builder

> This repo is hosted externally but _provided_ as a "built-in" part of the [**vite-plugin-md**](https://github.com/antfu/vite-plugin-md) plugin.

This is a Builder plugin to [`vite-plugin-md`](https://github.com/antfu/vite-plugin-md) and adds capabilities to manage meta data blocks in your documents.

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

```ts
// 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
- **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:

```mermaid
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 using `vite-plugin-pages`) for ROUTER meta

## 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`:

```ts
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:

```html
<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:

```md
---
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` and `content` attributes be set for you but also `itemprop` (google search) and `name` (twitter) will also be set.
- default values can be stated as a static variable, a reactive variable, or a function

---
_Source: https://npm.io/package/asir-meta-builder · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._