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

@@ -6,15 +6,43 @@ This is an internal library, used to help generate the Storybook's `index.json`,
 
 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                 |
+| name       | example                                                         | description                                                                                                          |
+| ---------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| 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 |
 
 ## 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,42 @@ Object {
     });
   });
 
+  describe('tags', () => {
+    it('string 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('template literal tags', () => {
+      const input = dedent`
+        <Meta tags={[\`docs\`]} />
+      `;
+      expect(() => analyze(input)).toThrowErrorMatchingInlineSnapshot(
+        '"Expected string literal title, received TemplateLiteral"'
+      );
+    });
+    it('invalid mdx', () => {
+      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 +318,7 @@ Object {
           "isTemplate": false,
           "name": undefined,
           "of": undefined,
+          "tags": Array [],
           "title": undefined,
         }
       `);
@@ -292,6 +337,7 @@ Object {
           "isTemplate": false,
           "name": undefined,
           "of": undefined,
+          "tags": Array [],
           "title": undefined,
         }
       `);
@@ -336,6 +382,7 @@ Object {
           "isTemplate": false,
           "name": undefined,
           "of": "./Button.stories",
+          "tags": Array [],
           "title": undefined,
         }
       `);