Update README.md + Add support for Markdown/HTML + Update loop targets

.github/workflows/test.yml

@@ -1,6 +1,11 @@
 name: Test
 
-on: [push]
+on:
+  push:
+    branches:
+      - next
+  pull_request:
+    types: [opened, synchronize, reopened]
 
 jobs:
   test:

README.md

@@ -8,13 +8,43 @@ It currently produces:
 
 | name    | example                            | description                             |
 | ------- | ---------------------------------- | --------------------------------------- |
-| title   | `<Meta title="x">`                 | A manually specified title              |
-| of      | `<Meta of={buttonMeta}>`           | A title specified by an imported object |
 | imports | `import * from './Button.stories'` | The list of ESM imports                 |
+| of      | `<Meta of={buttonMeta}>`           | A title specified by an imported object, e.g. coming from a `.stories.ts` file |
+| title   | `<Meta title="x">`                 | A manually specified title; this title is used for indexing the stories and displaying them in the Storybook sidebar              |
+| name   | `<Meta name="x">`                   | A manually defined Docs name; this value overrides `docs.defaultName` in `main.js`              |
+| tags   | `<Meta tags={["docs"]} />`          | A list of tags that are used to influence the docs story. |
+| isTemplate | `<Meta isTemplate={true} />` <br/>OR<br/> `<Meta isTemplate />` | `true` value indicates this file is not to be indexed by `Storybook` as it is being used as a template by other docs |
+
+* Note: In case of importing documents other than `.mdx` files like `.md` or `.html` files, `<title></title>` will populate the `title` property with the innerText of the element.
 
 ## Getting Started
 
-FIXME: Add getting started steps
+* This small library is used exclusively by `Storybook` for the sole purpose of extracting values from `.mdx` files that will be used to populate the `index.json` file (formerly `stories.json`).
+
+* Starting by importing the `analyze` method into your code like so:
+
+```tsx
+import { analyze } from '@storybook/docs-mdx';
+```
+
+* Followed by reading the contents of the docs.(md|mdx|html) file:
+
+```tsx
+const content = fs.readFileSync(absolutePath, 'utf-8');
+```
+
+* Finally, calling the `analyze` method with the content as argument to retrieve the destructured properties:
+
+```tsx
+const result: {
+    title?: ComponentTitle;
+    of?: Path;
+    name?: StoryName;
+    isTemplate?: boolean;
+    imports?: Path[];
+    tags?: Tag[];
+} = analyze(content);
+```
 
 ## Contributing
 

src/analyze.test.ts

@@ -51,6 +51,7 @@ describe('analyze', () => {
           "isTemplate": false,
           "name": undefined,
           "of": undefined,
+          "tags": Array [],
           "title": "foobar",
         }
       `);
@@ -76,14 +77,15 @@ describe('analyze', () => {
         <Meta name="foobar" />
       `;
       expect(analyze(input)).toMatchInlineSnapshot(`
-Object {
-  "imports": Array [],
-  "isTemplate": false,
-  "name": "foobar",
-  "of": undefined,
-  "title": undefined,
-}
-`);
+        Object {
+          "imports": Array [],
+          "isTemplate": false,
+          "name": "foobar",
+          "of": undefined,
+          "tags": Array [],
+          "title": undefined,
+        }
+      `);
     });
     it('template literal name', () => {
       const input = dedent`
@@ -114,6 +116,7 @@ Object {
           "isTemplate": false,
           "name": undefined,
           "of": "./Button.stories",
+          "tags": Array [],
           "title": undefined,
         }
       `);
@@ -151,6 +154,7 @@ Object {
           "isTemplate": false,
           "name": undefined,
           "of": "./Button.stories",
+          "tags": Array [],
           "title": undefined,
         }
       `);
@@ -178,6 +182,7 @@ Object {
           "isTemplate": false,
           "name": "Story One",
           "of": "../src/A.stories",
+          "tags": Array [],
           "title": undefined,
         }
       `);
@@ -206,6 +211,7 @@ Object {
           "isTemplate": true,
           "name": undefined,
           "of": undefined,
+          "tags": Array [],
           "title": undefined,
         }
       `);
@@ -224,6 +230,7 @@ Object {
           "isTemplate": true,
           "name": undefined,
           "of": undefined,
+          "tags": Array [],
           "title": undefined,
         }
       `);
@@ -239,6 +246,7 @@ Object {
           "isTemplate": false,
           "name": undefined,
           "of": undefined,
+          "tags": Array [],
           "title": undefined,
         }
       `);
@@ -263,6 +271,34 @@ Object {
     });
   });
 
+  describe('tags', () => {
+    it('template literal tags', () => {
+      const input = dedent`
+        <Meta tags={["docs"]} />
+      `;
+      expect(analyze(input)).toMatchInlineSnapshot(`
+        Object {
+          "imports": Array [],
+          "isTemplate": false,
+          "name": undefined,
+          "of": undefined,
+          "tags": Array [
+            "docs",
+          ],
+          "title": undefined,
+        }
+      `);
+    });
+    it('incorrect format', () => {
+      const input = dedent`
+        <Meta tags=["docs"] />
+      `;
+      expect(() => analyze(input)).toThrowErrorMatchingInlineSnapshot(
+        '"Unexpected character `[` (U+005B) before attribute value, expected a character that can start an attribute value, such as `\\"`, `\'`, or `{`"'
+      );
+    });
+  })
+
   describe('errors', () => {
     it('no title', () => {
       const input = dedent`
@@ -274,6 +310,7 @@ Object {
           "isTemplate": false,
           "name": undefined,
           "of": undefined,
+          "tags": Array [],
           "title": undefined,
         }
       `);
@@ -292,6 +329,7 @@ Object {
           "isTemplate": false,
           "name": undefined,
           "of": undefined,
+          "tags": Array [],
           "title": undefined,
         }
       `);
@@ -336,9 +374,28 @@ Object {
           "isTemplate": false,
           "name": undefined,
           "of": "./Button.stories",
+          "tags": Array [],
           "title": undefined,
         }
       `);
     });
   });
+
+  describe('markdown/html', () => {
+    it('title', () => {
+      const input = dedent`
+      <title>foobar</title>
+    `;
+      expect(analyze(input)).toMatchInlineSnapshot(`
+      Object {
+        "imports": Array [],
+        "isTemplate": false,
+        "name": undefined,
+        "of": undefined,
+        "tags": Array [],
+        "title": "foobar",
+      }
+    `);
+    })
+  })
 });