feat: frontmatter format, route doc parameter

README.md

@@ -66,11 +66,11 @@ There are many developments that have contributed to the creation of `component-
 -   [x] Storybook integration without addon-docs (replace all storybook loaders)
 -   [x] Standalone webpack compiler API
 -   [ ] HMR
--   [ ] Gatsby standalone app/static app builder
+-   [x] Gatsby standalone app/static app builder
 -   [ ] Nextjs standalone app/static app builder
--   [ ] Integrated testing facilites
+-   [ ] Integrated testing facilites (WIP)
 -   [ ] Coverage and perfoamnce profiling instrumentation
--   [ ] Replace MDX with frontmatter format
+-   [x] Support frontmatter MDX declarations
 -   [ ] Multiple frameworks support (Vue, Angular, tbd)
 
 # Showcase sites
@@ -111,7 +111,6 @@ Storybook Addon For live editing of component controls
 
 -   Initial version is only for `react` apps. More frameworks are on the roadmap. 
 -   Only handles the CSF and MDX stories format. The storiesOf API is not supported and there are currently no plans to support it.
--   The Storybook MDX (`<Meta />` tag) is a proprietary format that will be replaced in due time with a portable [frontmatter](https://www.gatsbyjs.org/docs/mdx/markdown-syntax/#frontmatter--mdx-example) stories format, similar to the CSF format.
 
 <!-- END-PACKAGE-SECTION -->
 

core/config/README.md

@@ -4,7 +4,8 @@
 -   [Installation](#installation)
 -   [API](#api)
     -   [ConfigrationResult](#configrationresult)
-    -   [configFileNames](#configfilenames)
+    -   [buildConfigFileNames](#buildconfigfilenames)
+    -   [optionsFileNames](#optionsfilenames)
     -   [extractStories](#extractstories)
     -   [getConfigurationArg](#getconfigurationarg)
     -   [loadConfiguration](#loadconfiguration)
@@ -30,29 +31,36 @@ $ npm install @component-controls/config --save-dev
 
 ## ConfigrationResult
 
-_defined in [@component-controls/config/src/index.ts](https://github.com/ccontrols/component-controls/tree/master/core/config/src/index.ts#L14)_
+_defined in [@component-controls/config/src/index.ts](https://github.com/ccontrols/component-controls/tree/master/core/config/src/index.ts#L16)_
 
 
 
 ### properties
 
-| Name          | Type                            | Description |
-| ------------- | ------------------------------- | ----------- |
-| `config*`     | [Configuration](#configuration) |             |
-| `configPath*` | string                          |             |
+| Name              | Type                            | Description |
+| ----------------- | ------------------------------- | ----------- |
+| `config*`         | [Configuration](#configuration) |             |
+| `configPath*`     | string                          |             |
+| `optionsFilePath` | string                          |             |
 
-## configFileNames
+## buildConfigFileNames
 
 _defined in [@component-controls/config/src/index.ts](https://github.com/ccontrols/component-controls/tree/master/core/config/src/index.ts#L7)_
 
 
 
+## optionsFileNames
+
+_defined in [@component-controls/config/src/index.ts](https://github.com/ccontrols/component-controls/tree/master/core/config/src/index.ts#L15)_
+
+
+
 ## extractStories
 
 find the story files out of a configuration file
 using glob for the regex file search
 
-_defined in [@component-controls/config/src/index.ts](https://github.com/ccontrols/component-controls/tree/master/core/config/src/index.ts#L70)_
+_defined in [@component-controls/config/src/index.ts](https://github.com/ccontrols/component-controls/tree/master/core/config/src/index.ts#L80)_
 
 **function** extractStories(`__namedParameters`\*: **config**: [Configuration](#configuration)**configPath**: string): string\[] | undefined;
 
@@ -69,7 +77,7 @@ return the configration folder from command-line parameters
 command line accepts -c/ -config parameter for config path
 the config file is assumed named main.js/main.ts
 
-_defined in [@component-controls/config/src/index.ts](https://github.com/ccontrols/component-controls/tree/master/core/config/src/index.ts#L24)_
+_defined in [@component-controls/config/src/index.ts](https://github.com/ccontrols/component-controls/tree/master/core/config/src/index.ts#L27)_
 
 **function** getConfigurationArg(`args`\*: string\[]): string | undefined;
 
@@ -84,7 +92,7 @@ _defined in [@component-controls/config/src/index.ts](https://github.com/ccontro
 
  given a base project folder and a configuration folder, returns the configuration file
 
-_defined in [@component-controls/config/src/index.ts](https://github.com/ccontrols/component-controls/tree/master/core/config/src/index.ts#L45)_
+_defined in [@component-controls/config/src/index.ts](https://github.com/ccontrols/component-controls/tree/master/core/config/src/index.ts#L48)_
 
 **function** loadConfiguration(`baseFolder`\*: string, `configFolder`: string, `args`: string\[]): [ConfigrationResult](#configrationresult) | undefined;
 
@@ -108,9 +116,10 @@ _defined in [@component-controls/specification/src/configuration.ts](https://git
 
 ### properties
 
-| Name         | Type                               | Description                                                                                                                                    |
-| ------------ | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `decorators` | [StoryRenderFn](#storyrenderfn)\[] | story decorator functions - used to wrap stories example: \[story => <ThemeProvider>{story()}</ThemeProvider>]                           |
-| `stories*`   | string\[]                          | wild card search string for the stories internally using \`glob\` for the search: https://www.npmjs.com/package/glob example: "./stories/ |
+| Name         | Type                                                                                      | Description                                                                                                                                    |
+| ------------ | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `decorators` | [StoryRenderFn](#storyrenderfn)\[]                                                        | story decorator functions - used to wrap stories example: \[story => <ThemeProvider>{story()}</ThemeProvider>]                           |
+| `options`    | story sorting function**storySort**: **function** (`a`\*: string, `b`\*: string): number; | global options object                                                                                                                          |
+| `stories*`   | string\[]                                                                                 | wild card search string for the stories internally using \`glob\` for the search: https://www.npmjs.com/package/glob example: "./stories/ |
 
 <!-- END-TSDOC-TYPESCRIPT -->

core/instrument/package.json

@@ -40,6 +40,7 @@
     "camelcase": "^6.0.0",
     "deepmerge": "^4.2.2",
     "find-cache-dir": "^3.3.1",
+    "gray-matter": "^4.0.2",
     "hosted-git-info": "^3.0.4",
     "prettier": "^1.19.1",
     "read-package-json": "^2.1.1",

core/instrument/src/babel/mdx-stories.ts

@@ -21,7 +21,7 @@ import {
 
 import { componentsFromParams } from '../misc/component-attributes';
 
-export const extractMDXStories = (
+export const extractMDXStories = (props: any) => (
   ast: File,
   _options: Required<InstrumentOptions>,
   { source, filePath }: { source: string; filePath: string },
@@ -73,7 +73,7 @@ export const extractMDXStories = (
     'stories' | 'doc' | 'components' | 'exports' | 'packages'
   >> = {
     stories: {},
-    doc: undefined,
+    doc: props ? { ...props } : undefined,
     components: {},
     exports: {},
     packages: {},
@@ -207,11 +207,11 @@ export const extractMDXStories = (
     },
   });
 
-  if (store.doc) {
+  if (store.doc && store.doc.title) {
     //@ts-ignore
     store.doc.components = components;
   } else {
-    throw new Error(`MDX stories should have one <Meta /> component`);
+    throw new Error(`MDX documenation pages should have at least a title`);
   }
   return store;
 };

core/instrument/src/index.ts

@@ -1,5 +1,6 @@
 import * as parser from '@babel/parser';
 import mdx from '@mdx-js/mdx';
+import matter from 'gray-matter';
 import { File } from '@babel/types';
 import traverse from '@babel/traverse';
 import generate from '@babel/generator';
@@ -156,7 +157,8 @@ export const parseStories = async (
     ...otherMDXOptions
   } = mergedOptions.mdx;
   if (test && filePath.match(test)) {
-    const mdxParsed = await mdx(source, {
+    const { data, content } = matter(source);
+    const mdxParsed = await mdx(content, {
       filepath: filePath,
       ...otherMDXOptions,
     });
@@ -168,15 +170,18 @@ export const parseStories = async (
     }));
     const store = await parseSource(
       code,
-      extractMDXStories,
-      source,
+      extractMDXStories(data),
+      content,
       filePath,
       mergedOptions,
     );
     const { stories, doc, components, exports, packages } = store;
     const exportsSource = extractStoryExports(exports);
-    let transformed = source;
-    if (transformMDX && exportsSource) {
+    let transformed = `
+    
+    ${content}
+`;
+    if (transformMDX) {
       transformed = `${renderer}\n${code}\n${exportsSource}`;
     }
     return {

core/instrument/src/misc/mdx-exports.ts

@@ -49,5 +49,5 @@ export const extractStoryExports = (exports?: MDXExportTypes): string => {
       return `${defaultExportCode}\n${storiesExports.join('\n')}`;
     }
   }
-  return 'result';
+  return '';
 };

core/specification/README.md

@@ -144,6 +144,7 @@ _defined in [@component-controls/specification/src/stories.ts](https://github.co
 | `includeStories` | string\[] \| [RegExp](#regexp)          | list of stories to include in the stories file can also use regexp match                                                                   |
 | `package`        | string                                  | lookup into the global store of PackageInfo package.json                                                                                   |
 | `parameters`     | [StoryParameters](#storyparameters)     | configuration parameters passed to the story groups configured either as CSF default export or MDX <Meta /> tag                         |
+| `route`          | string                                  | if provided, will be used as the route for the page if not provided, the title in lowercase will be used as the route                      |
 | `source`         | string                                  | source code of the entire file of stories                                                                                                  |
 | `stories`        | string\[]                               | list of stories contained in the file/groups                                                                                               |
 | `subcomponents`  | string\[] \| object\[]                  | multiple components option                                                                                                                 |
@@ -153,7 +154,7 @@ _defined in [@component-controls/specification/src/stories.ts](https://github.co
 
 store of stories information in memory after the loader is applied
 
-_defined in [@component-controls/specification/src/stories.ts](https://github.com/ccontrols/component-controls/tree/master/core/specification/src/stories.ts#L273)_
+_defined in [@component-controls/specification/src/stories.ts](https://github.com/ccontrols/component-controls/tree/master/core/specification/src/stories.ts#L279)_
 
 
 
@@ -162,6 +163,7 @@ _defined in [@component-controls/specification/src/stories.ts](https://github.co
 | Name          | Type                                | Description                                                                                     |
 | ------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------- |
 | `components*` | [StoryComponents](#storycomponents) | list of components used in stories                                                              |
+| `config`      | [Configuration](#configuration)     | global configuration for config file                                                            |
 | `docs*`       | [StoryDocs](#storydocs)             | list of story files, or groups                                                                  |
 | `packages*`   | [StoryPackages](#storypackages)     | list of package.json files and their data used by the components and the stories of the project |
 | `stories*`    | [StoryStories](#storystories)       | list of stories                                                                                 |
@@ -214,23 +216,23 @@ _defined in [@component-controls/specification/src/stories.ts](https://github.co
 
 list of components used in stories
 
-_defined in [@component-controls/specification/src/stories.ts](https://github.com/ccontrols/component-controls/tree/master/core/specification/src/stories.ts#L245)_
+_defined in [@component-controls/specification/src/stories.ts](https://github.com/ccontrols/component-controls/tree/master/core/specification/src/stories.ts#L251)_
 
 `fileName`\*: string: [StoryComponent](#storycomponent)
 
 ## StoryDocs
 
 list of story files, or groups
 
-_defined in [@component-controls/specification/src/stories.ts](https://github.com/ccontrols/component-controls/tree/master/core/specification/src/stories.ts#L252)_
+_defined in [@component-controls/specification/src/stories.ts](https://github.com/ccontrols/component-controls/tree/master/core/specification/src/stories.ts#L258)_
 
 `title`\*: string: [StoriesDoc](#storiesdoc)
 
 ## StoryPackages
 
 list of repositories
 
-_defined in [@component-controls/specification/src/stories.ts](https://github.com/ccontrols/component-controls/tree/master/core/specification/src/stories.ts#L266)_
+_defined in [@component-controls/specification/src/stories.ts](https://github.com/ccontrols/component-controls/tree/master/core/specification/src/stories.ts#L272)_
 
 `id`\*: string: [PackageInfo](#packageinfo)
 
@@ -247,7 +249,7 @@ _defined in [@component-controls/specification/src/stories.ts](https://github.co
 
 list of stories
 
-_defined in [@component-controls/specification/src/stories.ts](https://github.com/ccontrols/component-controls/tree/master/core/specification/src/stories.ts#L259)_
+_defined in [@component-controls/specification/src/stories.ts](https://github.com/ccontrols/component-controls/tree/master/core/specification/src/stories.ts#L265)_
 
 `id`\*: string: [Story](#story)
 
@@ -854,10 +856,11 @@ _defined in [@component-controls/specification/src/configuration.ts](https://git
 
 ### properties
 
-| Name         | Type                               | Description                                                                                                                                    |
-| ------------ | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `decorators` | [StoryRenderFn](#storyrenderfn)\[] | story decorator functions - used to wrap stories example: \[story => <ThemeProvider>{story()}</ThemeProvider>]                           |
-| `stories*`   | string\[]                          | wild card search string for the stories internally using \`glob\` for the search: https://www.npmjs.com/package/glob example: "./stories/ |
+| Name         | Type                                                                                      | Description                                                                                                                                    |
+| ------------ | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `decorators` | [StoryRenderFn](#storyrenderfn)\[]                                                        | story decorator functions - used to wrap stories example: \[story => <ThemeProvider>{story()}</ThemeProvider>]                           |
+| `options`    | story sorting function**storySort**: **function** (`a`\*: string, `b`\*: string): number; | global options object                                                                                                                          |
+| `stories*`   | string\[]                                                                                 | wild card search string for the stories internally using \`glob\` for the search: https://www.npmjs.com/package/glob example: "./stories/ |
 
 ## StoryRenderFn
 

core/specification/src/stories.ts

@@ -165,6 +165,12 @@ export interface StoriesDoc {
    */
   stories?: string[];
 
+  /**
+   * if provided, will be used as the route for the page
+   * if not provided, the title in lowercase will be used as the route
+   */
+  route?: string;
+
   /**
    * configuration parameters passed to the story groups
    * configured either as CSF default export