Frontmatter Plugin Advanced Topics

@md-plugins

v0.1.0-rc.3

Frontmatter Plugin

The frontmatter plugin allows you to extract and process frontmatter content from your Markdown files. This section will cover how the plugin works, the available options for customization, and examples of how to use it effectively.

Type Information

import { PluginWithOptions } from 'markdown-it'
import matter from 'gray-matter'

type GrayMatterOptions = matter.GrayMatterOption<string, GrayMatterOptions>

/**
 * Options of md-plugin-frontmatter
 */
interface FrontmatterPluginOptions {
  /**
   * Options of gray-matter
   *
   * @see https://github.com/jonschlinkert/gray-matter#options
   */
  grayMatterOptions?: GrayMatterOptions
  /**
   * Render the excerpt or not
   *
   * @default false
   */
  renderExcerpt?: boolean
}

declare module '@md-plugins/shared' {
  interface MarkdownItEnv {
    /**
     * The raw Markdown content without frontmatter
     */
    content?: string
    /**
     * Whether render excerpt or not
     */
    renderExcerpt?: boolean
    /**
     * The excerpt that extracted by `md-plugin-frontmatter`
     *
     * - Would be the rendered HTML when `renderExcerpt` is enabled
     * - Would be the raw Markdown when `renderExcerpt` is disabled
     */
    excerpt?: string
    /**
     * The frontmatter that extracted by `md-plugin-frontmatter`
     */
    frontmatter?: Record<string, unknown>
  }
}

/**
 * Get markdown frontmatter and excerpt
 *
 * Extract them into env
 */
declare const frontmatterPlugin: PluginWithOptions<FrontmatterPluginOptions>

export { type FrontmatterPluginOptions, frontmatterPlugin }

How It Works

Frontmatter is a block of metadata at the top of a Markdown file, enclosed by triple dashes (---). The frontmatter plugin parses this block and makes the metadata available for use in your Markdown content.

Default Behavior

By default, the frontmatter plugin extracts the frontmatter content and makes it available in the env object passed to the Markdown renderer. Here is an example of a Markdown file with frontmatter:

---
title: My Awesome Post
date: 2023-10-01
tags: [markdown, frontmatter, plugin]
---

Plugin Options

The frontmatter plugin provides several options for customization. Here are the available options and their descriptions:

`grayMatterOptions`

Type: object
Description: Options to pass to the gray-matter library for parsing frontmatter.

`renderExcerpt`

Type: boolean
Default: false
Description: Whether to render the excerpt using the original markdown-it render method.

Example Configuration

Here is an example of how you can configure the frontmatter plugin with custom options:

import MarkdownIt from 'markdown-it'
import { frontmatterPlugin } from '@md-plugins/md-plugin-frontmatter'

const md = new MarkdownIt()

md.use(frontmatterPlugin, {
  grayMatterOptions: {
    excerpt: true,
    excerpt_separator: '<!-- more -->',
  },
  renderExcerpt: true,
})

Using Frontmatter in Templates

Once the frontmatter is extracted and validated, it is stored in the env object. How you handle this data and send it to the front-end is up to you. Here is an example of how to use frontmatter in a Vue component:

<template>
  <div>
    <h1>{{ frontmatter.title }}</h1>
    <p>Published on: {{ frontmatter.date }}</p>
    <p>Tags: {{ frontmatter.tags.join(', ') }}</p>
  </div>
</template>

<script setup>
  import { ref } from 'vue'

  const frontmatter = ref({
    title: 'My Awesome Post',
    date: '2023-10-01',
    tags: ['markdown', 'frontmatter', 'plugin'],
  })
</script>

Handling Errors

The frontmatter plugin includes error handling to ensure that any issues with parsing the frontmatter do not break the rendering process. If an error occurs, the plugin will log the error and continue rendering the content without the frontmatter.

try {
  // Parse frontmatter and content
  ;({ data, content } = grayMatter(src, grayMatterOptions))
} catch (error) {
  console.error('Failed to parse frontmatter:', error)
  data = {}
  content = src
  excerpt = undefined
}

Conclusion

The frontmatter plugin is a powerful tool for extracting and processing metadata from your Markdown files. By customizing the parsing and validation logic, you can tailor the plugin to fit your specific needs. Remember, it is up to you to handle the extracted frontmatter data and send it to the front-end in a way that suits your application. Experiment with different configurations and find the one that works best for you.

Happy coding!

Ready for more?

Caught a mistake?Edit this page in browser

1. Introduction

2. Frontmatter Plugin

2.1. Type Information

2.2. How It Works

2.3. Default Behavior

2.4. Plugin Options

2.5. Example Configuration

2.6. Using Frontmatter in Templates

2.7. Handling Errors

2.8. Conclusion