Add starting point for migrations docs

Author: sam-b-rose

polaris-migrator/README.md

@@ -10,11 +10,12 @@ Codemod transformations to help upgrade your Polaris codebase.
 npx @shopify/polaris-migrator <transform> <path>
 ```
 
-- `transform` - name of transform, see available transforms below.
-- `path` - files or directory to transform
+- `transform` - name of migration, see available migrations on the docs site below.
+- `path` - files or directory to perform migration
 - `--dry` Do a dry-run, no code will be edited
 - `--print` Prints the changed output for comparison
+- `--force` Ignores the safety check for a clean git status
 
 ## Documentation
 
-Visit [polaris.shopify.com/docs/advanced-features/migrations](https://polaris.shopify.com/docs/advanced-features/migrations) to view available migrations.
+Visit [polaris.shopify.com/docs/advanced-features/migrations](https://polaris.shopify.com/docs/migrations) to view available migrations.

polaris.shopify.com/content/docs/index.md

@@ -0,0 +1,8 @@
+---
+title: Getting started
+description:
+keywords:
+  - getting started
+  - installing
+  - setup
+---

polaris.shopify.com/content/docs/migrations/index.md

@@ -0,0 +1,77 @@
+---
+title: Migrations
+description: Polaris provides Codemod migrations to help upgrade your codebase when a feature is deprecated.
+keywords:
+  - codemod
+  - migration
+  - migrator
+  - upgrade
+  - updated
+  - version
+  - components
+  - transform
+---
+
+Polaris provides Codemod migrations to help upgrade your codebase.
+
+Codemods are transformations that run on your codebase programmatically. This allows for a large amount of changes to be applied without having to manually go through every file.
+
+## Usage
+
+`npx @shopify/polaris-migrator <migration> <path>`
+
+- `migration` - name of migration, see available migrations below.
+- `path` - files or directory to perform migration (supports globs)
+- `--dry` Do a dry-run, no code will be edited
+- `--print` Prints the changed output for comparison
+- `--force` Ignores the safety check for a clean git status
+
+## Polaris v10
+
+### `replace-text-component`
+
+Replaces legacy text components `DisplayText`, `Heading`, `Subheading`, `Caption`, `TextStyle`, `VisuallyHidden` with the new `Text` component. This migration will include the proper styling props to match the replaced component.
+
+For example:
+
+```jsx
+import {DisplayText, TextStyle} from '@shopify/react';
+
+export default function App() {
+  return (
+    <>
+      <DisplayText size="medium">
+        Get started with finances on Shopify
+      </DisplayText>
+      <p>
+        <TextStyle variation="subdued">
+          Start getting the most from your store’s finances by completing these
+          tasks.
+        </TextStyle>
+      </p>
+    </>
+  );
+}
+```
+
+Transforms to:
+
+```jsx
+import {Text} from '@shopify/react';
+
+export default function App() {
+  return (
+    <>
+      <Text variation="heading2xl" as="p">
+        Get started with finances on Shopify
+      </Text>
+      <p>
+        <Text variant="bodyMd" as="span" color="subdued">
+          Start getting the most from your store’s finances by completing these
+          tasks.
+        </Text>
+      </p>
+    </>
+  );
+}
+```

polaris.shopify.com/pages/docs/[doc].tsx

@@ -0,0 +1,77 @@
+import type {GetStaticPaths, GetStaticProps, NextPage} from 'next';
+import fs from 'fs';
+import path from 'path';
+import globby from 'globby';
+
+import Layout from '../../src/components/Layout';
+import Longform from '../../src/components/Longform';
+import Markdown from '../../src/components/Markdown';
+import PageMeta from '../../src/components/PageMeta';
+import {docsNavItems} from '../../src/data/navItems';
+import {parseMarkdown} from '../../src/utils/markdown.mjs';
+import {MarkdownFile} from '../../src/types';
+
+interface Props {
+  readme: MarkdownFile['readme'];
+  title: string;
+  description?: string;
+}
+
+const docsDirectory = path.join(process.cwd(), 'content/docs');
+
+const Documentation: NextPage<Props> = ({
+  readme,
+  title,
+  description,
+}: Props) => {
+  return (
+    <Layout navItems={docsNavItems} title={title}>
+      <PageMeta title={title} description={description} />
+
+      <Longform>
+        {description ? <Markdown text={description} /> : null}
+        <Markdown text={readme} />
+      </Longform>
+    </Layout>
+  );
+};
+
+export const getStaticProps: GetStaticProps<Props, {doc: string}> = async ({
+  params,
+}) => {
+  const mdFilePath = path.resolve(
+    process.cwd(),
+    `${docsDirectory}/${params?.doc || ''}/index.md`,
+  );
+
+  if (fs.existsSync(mdFilePath)) {
+    const markdown = fs.readFileSync(mdFilePath, 'utf-8');
+    const {readme, frontMatter}: MarkdownFile = parseMarkdown(markdown);
+    const {title, description} = frontMatter;
+    const props: Props = {
+      title,
+      description: description || null,
+      readme,
+    };
+
+    return {props};
+  } else {
+    return {notFound: true};
+  }
+};
+
+export const getStaticPaths: GetStaticPaths = async () => {
+  const globPath = path.resolve(process.cwd(), 'content/docs/*/*.md');
+  const paths = globby.sync(globPath).map((fileName: string) => {
+    return fileName
+      .replace(`${process.cwd()}/content`, '')
+      .replace('/index.md', '');
+  });
+
+  return {
+    paths,
+    fallback: false,
+  };
+};
+
+export default Documentation;

polaris.shopify.com/pages/docs/index.tsx

@@ -0,0 +1,56 @@
+import type {GetStaticProps, NextPage} from 'next';
+import fs from 'fs';
+import path from 'path';
+
+import Layout from '../../src/components/Layout';
+import Longform from '../../src/components/Longform';
+import Markdown from '../../src/components/Markdown';
+import {docsNavItems} from '../../src/data/navItems';
+import {parseMarkdown} from '../../src/utils/markdown.mjs';
+import {MarkdownFile} from '../../src/types';
+import PageMeta from '../../src/components/PageMeta';
+
+interface Props {
+  title: string;
+  description: string;
+  readme: MarkdownFile['readme'];
+}
+
+const Documentation: NextPage<Props> = ({readme, description, title}) => {
+  return (
+    <Layout title={title} navItems={docsNavItems}>
+      <PageMeta title={title} />
+
+      <Longform>
+        <Markdown text={description} />
+        <Markdown text={readme} />
+      </Longform>
+    </Layout>
+  );
+};
+
+const docsDirectory = path.join(process.cwd(), 'content/docs');
+
+export const getStaticProps: GetStaticProps<
+  Props,
+  {category: string; doc: string}
+> = async () => {
+  const fullPath = path.join(docsDirectory, 'index.md');
+  const content = fs.readFileSync(fullPath, 'utf-8');
+  const {readme, frontMatter}: MarkdownFile = parseMarkdown(content);
+  const {title, description} = frontMatter;
+
+  if (content) {
+    const props: Props = {
+      readme,
+      title,
+      description,
+    };
+
+    return {props};
+  }
+
+  throw new Error(`Attempted to load this path but it was not found: ${path}`);
+};
+
+export default Documentation;

polaris.shopify.com/src/components/Longform/Longform.module.scss

@@ -134,7 +134,7 @@
     display: none;
   }
 
-  p code {
+  *:not(pre) > code {
     font-family: var(--font-family-mono);
     font-size: 0.9em;
     font-weight: var(--font-weight-500);
@@ -173,7 +173,7 @@
 
     th,
     td {
-      padding: 0.6rem .70588rem;
+      padding: 0.6rem 0.70588rem;
       border-bottom: 1px solid var(--border-color-light);
 
       &:first-child {
@@ -193,7 +193,6 @@
           padding-right: 2.8rem;
         }
       }
-
     }
 
     tbody {

polaris.shopify.com/src/data/navItems.ts

@@ -14,16 +14,16 @@ export const foundationsNavItems: NavItemWithIcon[] = [
     title: 'Foundations',
     children: [
       {
-        title: "About Polaris",
-        url: "/foundations/foundations/about-polaris",
-        icon: "HintMajor",
+        title: 'About Polaris',
+        url: '/foundations/foundations/about-polaris',
+        icon: 'HintMajor',
         description:
           "Learn what the Polaris design system is and how it's used by designers and developers to build world-class Shopify admin experiences.",
       },
       {
-        title: "Experience values",
-        url: "/foundations/foundations/experience-values",
-        icon: "HeartMajor",
+        title: 'Experience values',
+        url: '/foundations/foundations/experience-values',
+        icon: 'HeartMajor',
         description:
           'At Shopify, we empower commerce at a global scale. We build products, tools, and services for people to start, manage, and scale their businesses. We manage enormous complexity for commerce giants, and give new entrepreneurs the best chance to succeed.',
       },
@@ -200,16 +200,16 @@ export const foundationsNavItems: NavItemWithIcon[] = [
     title: 'Patterns',
     children: [
       {
-        title: "Design Patterns",
-        url: "/foundations/patterns/design-patterns",
-        icon: "RefreshMajor",
+        title: 'Design Patterns',
+        url: '/foundations/patterns/design-patterns',
+        icon: 'RefreshMajor',
         description:
-          "Design patterns provide repeatable UX solutions to common merchant situations.",
+          'Design patterns provide repeatable UX solutions to common merchant situations.',
       },
       {
-        title: "Loading",
-        url: "/foundations/patterns/loading",
-        icon: "ClockMajor",
+        title: 'Loading',
+        url: '/foundations/patterns/loading',
+        icon: 'ClockMajor',
         description:
           "Navigating the Shopify admin should be fast, meaningful, and focused, but unintentional loading can get in the way and break a merchant's flow. To deliver a continuous experience, we need to consider loading states when planning and prototyping.",
       },
@@ -316,3 +316,19 @@ export const contributingNavItems = [
     ],
   },
 ];
+
+export const docsNavItems = [
+  {
+    title: 'Documention',
+    children: [
+      {
+        title: 'Getting started',
+        url: '/docs',
+      },
+      {
+        title: 'Migrations',
+        url: '/docs/migrations',
+      },
+    ],
+  },
+];