Merge pull request #144 from vivliostyle/fix-param-name-excludes

fix: Rename `readMetadata` argument and `Metadata` property `excludes` to be more understandable

Author: akabekobeko

README.md

@@ -356,11 +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, excludes: string[]): Metadata`
+`readMetadata(md: string, customKeys: string[]): Metadata`
 
 - params:
   - `md`: `String` Markdown text.
-  - `excludes`: `String[]` A collection of key names to be ignored by meta processing.
+  - `customKeys`: `String[]` A collection of key names to be ignored by meta processing.
 - returns:
   - `metadata`: `Metadata` Metadata.
 
@@ -385,11 +385,11 @@ console.log(metadata);
 
 About `Metadata` details, refer to [VFM](https://vivliostyle.github.io/vfm/#/vfm)'s "Frontmatter" or type information of TypeScript.
 
-**About `excludes`**
+**About `customKeys`**
 
 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`.
+Keys that are not defined as VFM are treated as `meta`. If you specify a key name in `customKeys`, the key and its data type will be preserved and stored in `custom` instead of `meta`.
 
 ```js
 import { readMetadata } from '@vivliostyle/vfm'
@@ -409,13 +409,15 @@ Results:
 ```js
 {
   title: 'title',
-  excludes: {
+  custom: {
     tags: ['foo', 'bar']
   }
 }
 ```
 
-`tags` is stored and retained structure in `excludes` instead of `meta`.
+`tags` is stored and retained structure in `custom` instead of `meta`.
+
+If specify a default key such as `title`, it will be processed as `custom`.
 
 #### User-specified metadata
 

src/plugins/metadata.ts

@@ -76,7 +76,7 @@ export type Metadata = {
    * The data types converted from Frontmatter's YAML are retained.
    * Use this if want to add custom metadata with a third party tool.
    */
-  excludes?: {
+  custom?: {
     [key: string]: any;
   };
 };
@@ -254,23 +254,26 @@ 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`.
+ * Keys that are not defined as VFM are treated as `meta`. If you specify a key name in `customKeys`, the key and its data type will be preserved and stored in `custom` instead of `meta`.
  * @param md Markdown.
- * @param excludes A collection of key names to be ignored by meta processing.
+ * @param customKeys A collection of key names to be ignored by meta processing.
  * @returns Metadata.
  */
-export const readMetadata = (md: string, excludes: string[] = []): Metadata => {
+export const readMetadata = (
+  md: string,
+  customKeys: 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 = {};
+    if (customKeys.includes(key)) {
+      if (!metadata.custom) {
+        metadata.custom = {};
       }
 
-      metadata.excludes[key] = data[key];
+      metadata.custom[key] = data[key];
       continue;
     }
 

tests/metadata.test.ts

@@ -1,5 +1,5 @@
 import { stringify } from '../src/index';
-import { readMetadata } from '../src/plugins/metadata';
+import { Metadata, readMetadata } from '../src/plugins/metadata';
 
 it('Read all', () => {
   const received = readMetadata(
@@ -49,7 +49,7 @@ other-meta2: 'other2'
 
 `,
   );
-  const expected = {
+  const expected: Metadata = {
     id: 'my-page',
     lang: 'ja',
     dir: 'ltr',
@@ -512,9 +512,9 @@ tags: ["Foo", "Bar"]
 ---
 `;
   const received = readMetadata(md, ['tags']);
-  const expected = {
+  const expected: Metadata = {
     title: 'Title',
-    excludes: {
+    custom: {
       tags: ['Foo', 'Bar'],
     },
   };
@@ -526,10 +526,9 @@ it('Overwrite key with excludes', () => {
 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: {
+  const expected: Metadata = {
+    custom: {
       title: ['Foo', 'Bar'],
     },
   };