feat: add tutorial document type

core/specification/src/configuration.ts

@@ -14,12 +14,6 @@ export interface PageConfiguration {
    */
   label?: string;
 
-  /**
-   * if true, will create a home page with a top-level menu
-   * by default, only story and blogs have home pages
-   */
-  hasHomePage?: boolean;
-
   /**
    * whether to take a fullpage theme option
    */
@@ -29,6 +23,11 @@ export interface PageConfiguration {
    * whether to add navigation sidebars to the page
    */
   sidebars?: boolean;
+
+  /**
+   * whether to add to the top navigation menu
+   */
+  topMenu?: boolean;
 }
 
 export type PagesConfiguration = Record<PageType, PageConfiguration>;
@@ -53,12 +52,12 @@ export interface BuildConfiguration {
   /**
    * base url path for API documentation pages. Default is "docs/"
    */
-  pages: Record<PageType, Pick<PageConfiguration, 'basePath'>>;
+  pages?: Record<PageType, Pick<PageConfiguration, 'basePath'>>;
 
   /**
    * page types that are considred as categories fields as well
    */
-  categories: PageType[];
+  categories?: PageType[];
   /**
    * custom webpack fonfigurations setup. One or the other will be used
    */
@@ -70,7 +69,7 @@ export interface BuildConfiguration {
  * global configuration used at build time
  * stored in a file named main.js/main.ts
  */
-export interface RunConfiguration {
+export interface RunOnlyConfiguration {
   /**
    * story decorator functions - used to wrap stories
    * example: [story => <ThemeProvider>{story()}</ThemeProvider>]
@@ -131,6 +130,9 @@ export interface RunConfiguration {
   storySort?: (a: string, b: string) => number;
 }
 
+export type RunConfiguration = RunOnlyConfiguration &
+  Omit<BuildConfiguration, 'pages'>;
+
 export const defaultRunConfig: RunConfiguration = {
   siteTitle: 'Component controls',
   siteTitleAlt:
@@ -144,13 +146,13 @@ export const defaultRunConfig: RunConfiguration = {
   pages: {
     story: {
       label: 'Docs',
-      hasHomePage: true,
       sidebars: true,
+      topMenu: true,
     },
     blog: {
       label: 'Blog',
-      hasHomePage: true,
       sidebars: false,
+      topMenu: true,
     },
     author: {
       label: 'Authors',

core/store/src/Store/Store.ts

@@ -45,8 +45,7 @@ export class Store implements StoryStore {
       [key: string]: number;
     };
   } = {};
-  private _firstStory: string | undefined;
-  private _firstDoc: string | undefined;
+  private _firstDocument: { [key: string]: string | undefined } = {};
   /**
    * create a store with options
    */
@@ -102,16 +101,14 @@ export class Store implements StoryStore {
       }
 
       const sortedDocs = Object.keys(this.loadedStore.docs);
-      this._firstDoc = sortedDocs.find(name => {
-        //@ts-ignore
-        const doc = this.loadedStore.docs[name];
-        return doc.stories && doc.stories.length;
+      const { pages = {} } = this.loadedStore?.config || {};
+      Object.keys(pages).forEach(type => {
+        this._firstDocument[type as PageType] = sortedDocs.find(name => {
+          //@ts-ignore
+          const { type: docType = defPageType } = this.loadedStore.docs[name];
+          return docType === type;
+        });
       });
-      if (this._firstDoc) {
-        const doc = this.loadedStore.docs[this._firstDoc];
-        //point to first story of first doc
-        this._firstStory = doc.stories?.[0];
-      }
     }
   };
   /**
@@ -247,11 +244,9 @@ export class Store implements StoryStore {
   get config(): RunConfiguration | undefined {
     return this.loadedStore?.config;
   }
-  get firstStory(): string | undefined {
-    return this._firstStory;
-  }
-  get firstDoc(): string | undefined {
-    return this._firstDoc;
+
+  getFirstDocument(pageType: PageType): string | undefined {
+    return this._firstDocument[pageType];
   }
 
   getPagePath = (

core/store/src/types.ts

@@ -24,8 +24,7 @@ export interface StoryStore {
   getPagesByCategory: (category: string, value?: any) => Pages;
   getUniquesByCategory: (category: string) => { [key: string]: number };
   config: RunConfiguration | undefined;
-  firstStory: string | undefined;
-  firstDoc: string | undefined;
+  getFirstDocument: (pageType: PageType) => string | undefined;
   getPagePath: (pageType: PageType | undefined, name: string) => string;
   getStoryPath: (storyId: string) => string;
   updateStoryProp: (

examples/gatsby/.config/buildtime.js

@@ -4,6 +4,7 @@ module.exports = {
   stories: [
     '../../stories/src/blogs/*.mdx',
     '../../stories/src/authors/*.mdx',
+    '../../stories/src/tutorial/*.mdx',
     '../../stories/src/stories/*.stories.(js|jsx|tsx|mdx)',
     '../src/stories/*.stories.(js|jsx|tsx|mdx)',
     '../../../ui/app-components/src/**/*.stories.(js|jsx|tsx|mdx)',
@@ -17,6 +18,9 @@ module.exports = {
     blog: {
       basePath: 'blogs/',
     },
+    tutorial: {
+      basePath: 'tutorial/',
+    },
   },
   webpack: (config = {}, options = {}) => {
     return {

examples/gatsby/.config/runtime.js

@@ -17,6 +17,11 @@ module.exports = {
     story: {
       label: 'API',
     },
+    tutorial: {
+      label: 'Tutorial',
+      topMenu: true,
+      sidebars: true,
+    },
   },  
   storySort: (a, b) => {
     const aDoc = a.split('/')[0];

examples/stories/src/authors/atanas_stoyanov.mdx

@@ -2,16 +2,13 @@
 title: atanasster
 type: author
 ---
-import { Title, Subtitle, ExternalLink } from '@component-controls/components';
 
+<avatar src="https://pbs.twimg.com/profile_images/1195701448928968704/HpTyY7fB_400x400.jpg"/>
 
-<flex sx={{ flexDirection: 'column', alignItems: 'center' }}>
-  <avatar src="https://pbs.twimg.com/profile_images/1195701448928968704/HpTyY7fB_400x400.jpg"/>
-  <Title>Atanas Stoyanov</Title>
-  <Subtitle>prior software development products</Subtitle>
-  <ul>
-    <li>1990+: <ExternalLink href="http://www.scip.be/index.php?Page=ArticlesDelphi07&Lang=EN">Memproof</ExternalLink>, one of the best heap memory and resource 'leaks' debugger.</li>
-    <li>1990-2000: <ExternalLink href="https://smartbear.com/product/aqtime-pro/overview/">AQtime</ExternalLink>, performace and coverage profiling, won multiple awards..</li>
-    <li>2000+: <ExternalLink href="https://smartbear.com/product/testcomplete/overview/">TestComplete</ExternalLink>, functional UI tests automation, won multiple awards.</li>
-  </ul>
-</flex>  
+# Atanas Stoyanov
+
+## prior software development products
+
+- 1990+: [Memproof](http://www.scip.be/index.php?Page=ArticlesDelphi07&Lang=EN), one of the best heap memory and resource 'leaks' debugger.
+- 1990-2000: [AQtime](https://smartbear.com/product/aqtime-pro/overview/), performace and coverage profiling, won multiple awards.
+- 2000+: [TestComplete](https://smartbear.com/product/testcomplete/overview/), functional UI tests automation, won multiple awards.

examples/stories/src/blogs/home-page.mdx

@@ -18,25 +18,25 @@ export const BoxItem = props => (
   <Flex sx={{ flexDirection: 'column', alignItems: 'center', width: '100%'}}>
     <Title>component-controls</Title>
     <Text sx={{ my: 2 }}>
-      design -> develop -> test
+      design -> develop -> document -> test
     </Text>  
-    <Button as={DocsLink}>Getting started</Button>
+    <Button as={Link} href='/tutorial/'>Getting started</Button>
   </Flex>  
 </Flex>
 
 <Flex sx={{ flexDirection: 'column', alignItems: 'center', py: 5}}>
   <Flex sx={{ flexDirection: 'row', alignItems: 'center',  flexWrap: 'wrap', justifyContent: 'space-between', maxWidth: '1000px', width: '100%'}}>
     <BoxItem>
       <Subtitle>Start with Gatsby</Subtitle>
-      <Button as={Link} href='/storybook'>get started...</Button>
+      <Button as={Link} href='/tutorial/getting%20started/gatsby/'>get started...</Button>
     </BoxItem>
     <BoxItem>
       <Subtitle>Start with Vercel</Subtitle>
-      <Button as={Link} href='/storybook'>get started...</Button>
+      <Button as={Link} href='/tutorial/getting%20started/vercel/'>get started...</Button>
     </BoxItem>
     <BoxItem>
       <Subtitle>Start with Storybook</Subtitle>
-      <Button as={Link} href='/storybook'>get started...</Button>
+      <Button as={Link} href='/tutorial/getting%20started/storybook/'>get started...</Button>
     </BoxItem>
   </Flex>
 </Flex>  

examples/stories/src/tutorial/getting-started-gatsby.mdx

@@ -0,0 +1,33 @@
+---
+title: Getting started/Gatsby
+type: tutorial
+---
+
+# Getting started with Gatsby
+
+## Install
+
+```sh
+yarn add gatsby-theme-stories
+```
+
+## Configure
+
+the default options will configure `componnet-controls` to work with react apps,  with `reac-docgen` for prop-types and `react-docgen-typescript` for typescript props information
+
+in `gatsby-config.js`:
+
+```js
+  plugins: [
+    ...
+    {
+      resolve: '@component-controls/gatsby-theme-stories',
+      options: {
+        //path to the configuration files
+        configPath: '.config',
+      },
+    },
+    ...
+  ],
+
+```

examples/stories/src/tutorial/getting-started-storybook.mdx

@@ -0,0 +1,60 @@
+---
+title: Getting started/Storybook
+type: tutorial
+---
+
+# Getting started with Storybook
+
+## Install
+
+```sh
+yarn add @component-controls/storybook --dev
+```
+
+## Configure
+
+### Default options
+
+the default options will configure `componnet-controls` to work with react apps,  with `reac-docgen` for prop-types and `react-docgen-typescript` for typescript props information
+
+in `main.js`:
+
+```js
+module.exports = {
+  addons: ['@component-controls/storybook']
+}
+```
+
+### Use only `react-docgen` (even for typescript)
+
+Currently this is not recommended as the typescript support in `react-docgen` is a bit lagging.
+
+in `main.js`:
+
+```js
+module.exports = {
+  addons: [{
+    name: '@component-controls/storybook',
+    options: {
+      webpack: ['react-docgen'],
+    }
+  }]
+}
+```
+
+### Use built-in instrument for everything (not use storybook `addon-docs` at all)
+
+The following options will bypass the loaders installed by `addon-docs` and will rely only on the instrumenting loaders from `component-controls`
+
+in `main.js`:
+
+```js
+module.exports = {
+  addons: [{
+    name: '@component-controls/storybook',
+    options: {
+      webpack: ['instrument', 'react-docgen-typescript'],
+    }
+  }]
+}  
+```

examples/stories/src/tutorial/getting-started-vercel.mdx

@@ -0,0 +1,8 @@
+---
+title: Getting started/Vercel
+type: tutorial
+---
+
+# Getting started with Vercel
+
+## coming soon...

integrations/gatsby-theme-stories/src/components/Layout.tsx

@@ -1,18 +1,20 @@
 /** @jsx jsx */
 import { FC } from 'react';
 import { jsx } from 'theme-ui';
+import { PageType } from '@component-controls/specification';
 import { AppContext } from '@component-controls/app';
 const bundle = require('@component-controls/webpack-compile/bundle');
 
 import { GatsbyLink } from './GatsbyLink';
 
 interface LayoutProps {
   docId?: string;
+  type?: PageType;
 }
 
-export const Layout: FC<LayoutProps> = ({ docId, children }) => {
+export const Layout: FC<LayoutProps> = ({ docId, type, children }) => {
   return (
-    <AppContext docId={docId} store={bundle} linkClass={GatsbyLink}>
+    <AppContext docId={docId} store={bundle} linkClass={GatsbyLink} type={type}>
       {children}
     </AppContext>
   );

integrations/gatsby-theme-stories/src/gatsby-node.ts

@@ -89,6 +89,7 @@ exports.createPages = async (
             context: {
               type: catName as PageType,
               category: tag,
+              doc: null,
             },
           });
         });
@@ -98,6 +99,7 @@ exports.createPages = async (
             component: listTemplates[catName as PageType],
             context: {
               type: catName,
+              doc: null,
             },
           });
         }

integrations/gatsby-theme-stories/src/templates/CategoryList.tsx

@@ -7,14 +7,16 @@ import { Layout } from '../components/Layout';
 interface CategoryListProps {
   pathContext: {
     type: PageType;
+    doc: string;
   };
 }
 
 const CategroryListTemplate: FC<CategoryListProps> = ({
-  pathContext: { type },
+  pathContext: { type, doc },
 }) => {
+  console.log(doc);
   return (
-    <Layout>
+    <Layout type={type} docId={doc}>
       <CategoryList type={type} />
     </Layout>
   );