Merge pull request #142 from vivliostyle/feat-excludes-key-readmetadata

akabekobeko · web-flow · commit dc1867af7b21 · 2022-01-20T18:06:47.000+09:00
feat: Add `excludes` argument to `readMetadata`
diff --git a/README.md b/README.md
@@ -356,10 +356,11 @@ Read metadata from Markdown frontmatter.
 
 Useful if just want to get the metadata, Markdown parse and metadata typing (for TypeScript) are handled by the VFM side.
 
-`readMetadata(md: string): Metadata`
+`readMetadata(md: string, excludes: string[]): Metadata`
 
 - params:
   - `md`: `String` Markdown text.
+  - `excludes`: `String[]` A collection of key names to be ignored by meta processing.
 - returns:
   - `metadata`: `Metadata` Metadata.
 
@@ -382,7 +383,39 @@ const metadata = readMetadata(md);
 console.log(metadata);
 ```
 
-About `Metadata`, refer to [VFM](https://vivliostyle.github.io/vfm/#/vfm)'s "Frontmatter" or type information of TypeScript.
+About `Metadata` details, refer to [VFM](https://vivliostyle.github.io/vfm/#/vfm)'s "Frontmatter" or type information of TypeScript.
+
+**About `excludes`**
+
+Use this if want to add custom metadata with a third party tool.
+
+Keys that are not defined as VFM are treated as `meta`. If you specify a key name in `excludes`, the key and its data type will be preserved and stored in `excludes` instead of `meta`.
+
+```js
+import { readMetadata } from '@vivliostyle/vfm'
+
+const md = `---
+title: 'Title'
+tags: ['foo', 'bar']
+---
+`;
+
+const metadata = readMetadata(md, ['tags']);
+console.log(metadata);
+```
+
+Results:
+
+```js
+{
+  title: 'title',
+  excludes: {
+    tags: ['foo', 'bar']
+  }
+}
+```
+
+`tags` is stored and retained structure in `excludes` instead of `meta`.
 
 #### User-specified metadata
 
diff --git a/src/plugins/metadata.ts b/src/plugins/metadata.ts
@@ -70,6 +70,15 @@ export type Metadata = {
   style?: string;
   /** `<head>...</head>`, reserved for future use. */
   head?: string;
+
+  /**
+   * A set of key-value pairs that are specified in `readMetadata` not to be processed as `<meta>`.
+   * The data types converted from Frontmatter's YAML are retained.
+   * Use this if want to add custom metadata with a third party tool.
+   */
+  excludes?: {
+    [key: string]: any;
+  };
 };
 
 /**
@@ -244,15 +253,27 @@ const readSettings = (data: any): VFMSettings => {
 
 /**
  * Read metadata from Markdown frontmatter.
+ *
+ * Keys that are not defined as VFM are treated as `meta`. If you specify a key name in `excludes`, the key and its data type will be preserved and stored in `excludes` instead of `meta`.
  * @param md Markdown.
+ * @param excludes A collection of key names to be ignored by meta processing.
  * @returns Metadata.
  */
-export const readMetadata = (md: string): Metadata => {
+export const readMetadata = (md: string, excludes: string[] = []): Metadata => {
   const metadata: Metadata = {};
   const data = parseMarkdown(md);
   const others: Array<Array<Attribute>> = [];
 
   for (const key of Object.keys(data)) {
+    if (excludes.includes(key)) {
+      if (!metadata.excludes) {
+        metadata.excludes = {};
+      }
+
+      metadata.excludes[key] = data[key];
+      continue;
+    }
+
     switch (key) {
       case 'id':
       case 'lang':
diff --git a/tests/metadata.test.ts b/tests/metadata.test.ts
@@ -504,3 +504,34 @@ body:
 `;
   expect(received).toBe(expected);
 });
+
+it('Excludes key', () => {
+  const md = `---
+title: "Title"
+tags: ["Foo", "Bar"]
+---
+`;
+  const received = readMetadata(md, ['tags']);
+  const expected = {
+    title: 'Title',
+    excludes: {
+      tags: ['Foo', 'Bar'],
+    },
+  };
+  expect(received).toStrictEqual(expected);
+});
+
+it('Overwrite key with excludes', () => {
+  const md = `---
+title: ["Foo", "Bar"]
+---
+`;
+  // It's not supposed to, but it can be overridden, so we'll test it.
+  const received = readMetadata(md, ['title']);
+  const expected = {
+    excludes: {
+      title: ['Foo', 'Bar'],
+    },
+  };
+  expect(received).toStrictEqual(expected);
+});
