/commonmark-metadata

A CommonMark extension to parse MultiMarkdown-like metadata at the beginning of a markdown document

Primary LanguagePHPMIT LicenseMIT

This is an extension for thephpleague/commonmark to parse MultiMarkdown-like metadata from the top of a Markdown file.

Installation

  1. Require the package like any other:
composer require rianfuro/commonmark-metadata
  1. Install the extension.
use CommonMark\Extension\Metadata\MetadataExtension;

$environment = new Environment([]);
// ... other extensions
$environment->addExtension(new MetadataExtension);

new MarkdownConverter($environment);

Usage

The extension is used automatically by the CommonMark Parser when included. The extension converts the metadata section into a MetadataBlock, which holds the fields in it's data property. You can, for example, use CommonMark's query utility to fetch the Block and get it's data:

$metadata = (new Query())
  ->where(Query::type(MetadataBlock::class))
  ->findOne($document);
  
$metadata->data->export(); // note that this always includes the default `attributes` field

Current limitations

The project is in it's super early stages so the parsing is very limited. Currently the metadata needs to be fenced with yaml-style delimiters (should be optional according to the spec):

---
Author: Me
Title: Super Awesome Document
---

My Amazing Markdown Document
============================

...

Additionally, the metadata fields cannot be referenced inside the document.