feat: New platform layout and JavaScript conversion (#2026)

Co-authored-by: Fiona Artiaga <[email protected]>

Author: dcramer

.editorconfig

@@ -0,0 +1,12 @@
+# http://editorconfig.org
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

.vscode/settings.json

@@ -5,22 +5,8 @@
 
   "editor.wordWrap": "on",
 
-  "files.associations": {
-    "*.js": "javascriptreact"
-  },
-
-  "liquid.format": false,
-
-  "[ruby]": {
-    "editor.detectIndentation": false,
-    "editor.tabSize": 2,
-    "editor.formatOnSave": true
-  },
-
-  "[html]": {
-    "editor.detectIndentation": false,
-    "editor.tabSize": 2,
-    "editor.formatOnSave": false
-  },
-  "search.usePCRE2": true
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": true
+  }
 }

README.md

@@ -98,7 +98,45 @@ foo bar
 </markdown>
 ```
 
-## Creating new SDK docs
+## Platform / SDK Docs
+
+The current generation platform content lives in `src/platforms` and follows some specific rules to generate content. These rules are enforced via the directory structure:
+
+```
+[platformName]/
+  child.mdx
+  childTwo/
+    index.mdx
+  common/
+    aSharedPage.mdx
+  guides/
+    [guideName]/
+      uniqueChild.mdx
+      childTwo/
+        index.mdx
+```
+
+Platforms will generate a list of "guides", and inherit all content within common. Given the above example, we end up with a variety of semi-duplicated URLs:
+
+```
+/platforms/platformName/
+/platforms/platformName/child/
+/platforms/platformName/childTwo/
+/platforms/platformName/aSharedPage/
+/platforms/platformName/guides/guideName/
+/platforms/platformName/guides/guideName/child/
+/platforms/platformName/guides/guideName/uniqueChild/
+/platforms/platformName/guides/guideName/childTwo/
+/platforms/platformName/guides/guideName/aSharedPage/
+```
+
+This is generated by inheriting all content with the ``command/`` directory, then adding (or overriding with) content from the siblings (or children as we'd call them). In the above example, you'll see ``aSharedPage`` is loaded at two different URLs, and ``childTwo`` is overwritten by ``guideName``.
+
+The sidebar on platform pages (handled by ``<PlatformSidebar>``) will generate with the Guide, or the Base Platform being the primary section, in addition to a list of other guides available in a section below it. This means that all content is focused on the current guide (usually a framework) they're in, ensuring ease of navigation.
+
+### Creating new SDK docs
+
+TODO: This needs updated!
 
 If you want to create new docs for SDKs you should start by choosing an SDK to copy from and change the parts necessary. Start by calling
 

gatsby-config.js

@@ -1,4 +1,7 @@
-// const path = require("path");
+require("ts-node").register({
+  files: true, // to that TS node hooks have access to local typings too
+});
+
 const activeEnv =
   process.env.GATSBY_ENV || process.env.NODE_ENV || "development";
 
@@ -96,7 +99,7 @@ const getPlugins = () => {
       resolve: `gatsby-transformer-json`,
       options: {
         typeName: ({ node, object, isArray }) => {
-          if (node.sourceInstanceName === "api-docs") {
+          if (node.sourceInstanceName === "api") {
             return "ApiDoc";
           }
           return null;
@@ -113,7 +116,14 @@ const getPlugins = () => {
     {
       resolve: `gatsby-source-filesystem`,
       options: {
-        name: `api-docs`,
+        name: `platforms`,
+        path: `${__dirname}/src/platforms`,
+      },
+    },
+    {
+      resolve: `gatsby-source-filesystem`,
+      options: {
+        name: `api`,
         path: `${__dirname}/src/api`,
       },
     },

gatsby-node.js

@@ -1,244 +1,4 @@
-const path = require("path");
-const { createFilePath } = require("gatsby-source-filesystem");
-
-exports.onCreateWebpackConfig = ({ stage, actions }) => {
-  actions.setWebpackConfig({
-    resolve: {
-      alias: {
-        "~src": path.join(path.resolve(__dirname, "src")),
-      },
-    },
-  });
-};
-
-// TODO(dcramer): move frontmatter out of ApiDoc and into Frontmatter
-exports.createSchemaCustomization = ({ actions, schema }) => {
-  const { createTypes } = actions;
-  const typeDefs = [
-    `
-    type MarkdownRemark implements Node {
-      frontmatter: Frontmatter
-      fields: Fields
-    }
-
-    type Mdx implements Node {
-      frontmatter: Frontmatter
-      fields: Fields
-    }
-
-    type Fields {
-      slug: String!
-      legacy: Boolean
-    }
-
-    type ApiParam {
-      type: String!
-      name: String!
-      description: String
-    }
-
-    type ApiDoc implements Node {
-      sidebar_order: Int
-      title: String!
-      fields: Fields
-
-      api_path: String!
-      authentication:  String
-      description: String
-      example_request: String
-      example_response: String
-      method: String!
-      parameters: [ApiParam]
-      path_parameters: [ApiParam]
-      query_parameters: [ApiParam]
-      warning: String
-    }
-  `,
-    schema.buildObjectType({
-      name: "Frontmatter",
-      fields: {
-        title: {
-          type: "String!",
-        },
-        keywords: {
-          type: "[String!]",
-        },
-        draft: {
-          type: "Boolean",
-        },
-        redirect_from: {
-          type: "[String!]",
-        },
-        noindex: {
-          type: "Boolean",
-        },
-        sidebar_order: {
-          type: "Int",
-          resolve(source, args, context, info) {
-            // For a more generic solution, you could pick the field value from
-            // `source[info.fieldName]`
-            return source[info.fieldName] !== null
-              ? source[info.fieldName]
-              : 10;
-          },
-        },
-
-        // wizard fields
-        // TODO(dcramer): move to a diff schema/type
-        support_level: {
-          type: "String",
-        },
-        type: {
-          type: "String",
-        },
-        doc_link: {
-          type: "String",
-        },
-        name: {
-          type: "String",
-        },
-      },
-    }),
-  ];
-  createTypes(typeDefs);
-};
-
-exports.onCreateNode = ({
-  node,
-  actions,
-  getNode,
-  createContentDigest,
-  createNodeId,
-}) => {
-  const { createNodeField, createNode } = actions;
-  if (node.internal.type === "Mdx" || node.internal.type === "MarkdownRemark") {
-    const value = createFilePath({ node, getNode });
-    createNodeField({
-      name: "slug",
-      node,
-      value,
-    });
-
-    createNodeField({
-      name: "legacy",
-      node,
-      value: value.indexOf("/clients/") === 0,
-    });
-  } else if (node.internal.type === "ApiDoc") {
-    const value = createFilePath({ node, getNode });
-    createNodeField({
-      name: "slug",
-      node,
-      value: `/api${value}`,
-    });
-    createNodeField({
-      name: "legacy",
-      node,
-      value: false,
-    });
-
-    const markdownNode = {
-      id: createNodeId(`${node.id} >>> MarkdownRemark`),
-      children: [],
-      parent: node.id,
-      internal: {
-        content: node.description,
-        contentDigest: createContentDigest(node.description),
-        mediaType: `text/markdown`,
-        type: `ApiDocMarkdown`,
-      },
-    };
-    createNode(markdownNode);
-
-    createNodeField({
-      node,
-      name: "description___NODE",
-      value: markdownNode.id,
-    });
-  }
-};
-
-exports.createPages = async function({ actions, graphql, reporter }) {
-  const createApi = async () => {
-    const { data, errors } = await graphql(`
-      query {
-        allApiDoc {
-          nodes {
-            id
-            title
-            fields {
-              slug
-            }
-          }
-        }
-      }
-    `);
-
-    if (errors) {
-      reporter.panicOnBuild('🚨  ERROR: Loading "createApi" query');
-    }
-    const component = require.resolve(`./src/components/pages/api.js`);
-    await Promise.all(
-      data.allApiDoc.nodes.map(async node => {
-        actions.createPage({
-          path: node.fields.slug,
-          component,
-          context: {
-            id: node.id,
-            title: node.title,
-          },
-        });
-      })
-    );
-  };
-
-  const createDocs = async () => {
-    const { data, errors } = await graphql(`
-      query {
-        allFile(filter: { sourceInstanceName: { eq: "docs" } }) {
-          nodes {
-            id
-            childMarkdownRemark {
-              frontmatter {
-                title
-              }
-              fields {
-                slug
-              }
-            }
-            childMdx {
-              frontmatter {
-                title
-              }
-              fields {
-                slug
-              }
-            }
-          }
-        }
-      }
-    `);
-
-    if (errors) {
-      reporter.panicOnBuild('🚨  ERROR: Loading "createDocs" query');
-    }
-    const component = require.resolve(`./src/components/pages/doc.js`);
-    await Promise.all(
-      data.allFile.nodes.map(async node => {
-        const child = node.childMarkdownRemark || node.childMdx;
-        if (child && child.fields) {
-          actions.createPage({
-            path: child.fields.slug,
-            component,
-            context: {
-              id: node.id,
-              title: child.frontmatter.title,
-            },
-          });
-        }
-      })
-    );
-  };
-
-  await Promise.all([createApi(), createDocs()]);
-};
+exports.onCreateNode = require("./src/gatsby/onCreateNode").default;
+exports.onCreateWebpackConfig = require("./src/gatsby/onCreateWebpackConfig").default;
+exports.createPages = require("./src/gatsby/createPages").default;
+exports.createSchemaCustomization = require("./src/gatsby/createSchemaCustomization").default;