Markdown updates (#170)

* fix: update markdown styles

* feat: separate provider from components for easier shadowing

* chore: switch from emotion to scss modules

* feat: remove h1 margin-top to allow for more dynamic leads

* fix: punctuation

* refactor: code style

* docs: update markdown docs

packages/example/src/pages/components/PageDescription.mdx

@@ -8,7 +8,7 @@ The `<PageDescription>` component is generally used for intro text at the top of
 
 </PageDescription>
 
-Please note that this component is _extremely_ picky about white space, the line break above and below your content is required, and if you even have an extra space on the empty lines above/below it won't render correctly.
+Please note that this component, like all MDX components, is picky about white space, the line break above and below your content is required, and if you even have an extra space on the empty lines above/below it won't render correctly.
 
 ## Example
 

packages/example/src/pages/components/markdown.mdx

@@ -35,6 +35,12 @@ Combined emphasis with **asterisks and _underscores_**.
 Strikethrough uses two tildes. ~~Scratch this.~~
 ```
 
+## Headers
+
+Since the `h1` role effectively consumed by the page header, we style `h1` tags the same as `h2` tags. The only difference is the lack of a margin-top on `h1` components.
+
+This means the start of your content should be either a [PageDescription](/components/PageDescription) or an `h1` tag (single #). We recommend the former strategy. For most content, we think `PageDescription` → `AnchorLinks` creates a nice hierarchy.
+
 # H1
 
 ## H2
@@ -62,9 +68,8 @@ Strikethrough uses two tildes. ~~Scratch this.~~
 3. Actual numbers don't matter, just that it's a number
 4. And another item.
 
-- Unordered list can use asterisks
-
-* Or minuses
+- Unordered list can use asterisks `*`
+- Or minuses `-` to create list items
 
 #### Code
 
@@ -74,9 +79,9 @@ Strikethrough uses two tildes. ~~Scratch this.~~
 3. Actual numbers don't matter, just that it's a number
 4. And another item.
 
-* Unordered list can use asterisks
+- Unordered list can use asterisks `*`
+- Or minuses `-` to create list items
 
-- Or minuses
 ```
 
 ## Links

packages/gatsby-theme-carbon/src/components/AnchorLinks/AnchorLink.js

@@ -1,15 +1,13 @@
 import React from 'react';
-import { settings } from 'carbon-components';
 import GHSlugger from 'github-slugger';
+import { link } from './AnchorLinks.module.scss';
 
 const slugger = new GHSlugger();
 
-const { prefix } = settings;
-
 const AnchorLink = ({ to, children }) => {
   const href = to || `#${slugger.slug(children)}`;
   return (
-    <a className={`${prefix}--anchor-links__link`} href={href}>
+    <a className={link} href={href}>
       {children}
     </a>
   );

packages/gatsby-theme-carbon/src/components/AnchorLinks/AnchorLinks.js

@@ -1,26 +1,27 @@
 import React from 'react';
 import PropTypes from 'prop-types';
 import classnames from 'classnames';
-import { settings } from 'carbon-components';
-import responsiveStyles from '../shared/responsiveStyles';
-
-const { prefix } = settings;
+import {
+  list,
+  listSmall,
+  multipleColumns,
+  item,
+} from './AnchorLinks.module.scss';
 
 export default class AnchorLinks extends React.Component {
   render() {
     const { children, small } = this.props;
     const isColumn = React.Children.count(children) > 6;
-    const classNames = classnames({
-      [`${prefix}--anchor-links__list`]: true,
-      [`${prefix}--anchor-links__list--small`]: small,
-      [`${prefix}--anchor-links__list--column`]: isColumn,
+    const classNames = classnames(list, {
+      [listSmall]: small,
+      [multipleColumns]: isColumn,
     });
 
     return (
-      <ul css={responsiveStyles} className={classNames}>
-        {children.map((item, i) => (
-          <li key={i} className={`${prefix}--anchor-links__item`}>
-            {item}
+      <ul className={classNames}>
+        {children.map((link, i) => (
+          <li key={i} className={item}>
+            {link}
           </li>
         ))}
       </ul>
@@ -29,6 +30,6 @@ export default class AnchorLinks extends React.Component {
 }
 
 AnchorLinks.propTypes = {
-  children: PropTypes.node,
+  children: PropTypes.node.isRequired,
   small: PropTypes.bool,
 };

packages/gatsby-theme-carbon/src/components/AnchorLinks/anchor-links.scss → packages/gatsby-theme-carbon/src/components/AnchorLinks/AnchorLinks.module.scss

@@ -1,14 +1,29 @@
-.#{$prefix}--anchor-links__list {
-  width: auto;
+@import '~carbon-components/scss/globals/scss/vars';
+@import '~@carbon/elements/scss/type/type';
+
+.list {
   margin-bottom: 0;
   margin-top: $spacing-05;
-
+  width: 100%;
   @include carbon--breakpoint('md') {
     margin-bottom: $spacing-07;
+    width: 75%;
   }
+  @include carbon--breakpoint('lg') {
+    width: 58.33%;
+  }
+}
+
+.list--small {
+  margin-top: $spacing-05;
+}
+
+.list--small .link {
+  @include carbon--type-style('body-long-02');
+  margin-bottom: 0;
 }
 
-.#{$prefix}--anchor-links__item {
+.list-item {
   @include carbon--type-style('expressive-heading-03', true);
   width: auto;
   list-style: none;
@@ -22,7 +37,7 @@
   }
 }
 
-.#{$prefix}--anchor-links__link {
+.link {
   @include carbon--type-style('expressive-heading-03', true);
   position: relative;
   display: inline-block;
@@ -51,18 +66,8 @@
 }
 
 // Multiple Columns
-.#{$prefix}--anchor-links__list--column {
+.multiple-columns {
   @include carbon--breakpoint('md') {
     column-count: 2;
   }
 }
-
-// Small
-.#{$prefix}--anchor-links__list--small {
-  margin-top: $spacing-05;
-}
-
-.#{$prefix}--anchor-links__list--small .#{$prefix}--anchor-links__link {
-  @include carbon--type-style('body-long-02');
-  margin-bottom: 0;
-}

packages/gatsby-theme-carbon/src/components/Aside/Aside.js

@@ -1,9 +1,7 @@
 import React from 'react';
 import PropTypes from 'prop-types';
 import classnames from 'classnames';
-import { settings } from 'carbon-components';
-
-const { prefix } = settings;
+import { aside } from './Aside.module.scss';
 
 export default class Aside extends React.Component {
   static propTypes = {
@@ -18,7 +16,7 @@ export default class Aside extends React.Component {
   render() {
     const { children, className } = this.props;
 
-    const captionClasses = classnames([`${prefix}--aside`], {
+    const captionClasses = classnames(aside, {
       [className]: className,
     });
 

packages/gatsby-theme-carbon/src/components/Aside/aside.scss → packages/gatsby-theme-carbon/src/components/Aside/Aside.module.scss

@@ -1,11 +1,14 @@
-.#{$prefix}--aside {
+@import '~carbon-components/scss/globals/scss/vars';
+@import '~@carbon/elements/scss/type/type';
+
+.aside {
   @include carbon--type-style('body-long-01');
   position: relative;
   padding-top: $spacing-04;
   top: -$spacing-04;
 }
 
-.#{$prefix}--aside:before {
+.aside:before {
   content: '';
   position: absolute;
   top: 0;
@@ -15,7 +18,7 @@
   background: $ui-05;
 }
 
-.#{$prefix}--aside .#{$prefix}--paragraph {
+:global(.#{$prefix}--row) .aside p {
   @include carbon--type-style('body-long-01');
   width: 75%;
   padding-right: $spacing-05;

packages/gatsby-theme-carbon/src/components/Caption/caption.scss

@@ -11,7 +11,7 @@ img + .#{$prefix}--caption {
 }
 
 // Caption after video
-.#{$prefix}--video + .#{$prefix}--caption {
+[class^='Video-module--video'] + .#{$prefix}--caption {
   margin-top: -$spacing-08;
 }
 

packages/gatsby-theme-carbon/src/components/DoDontExample/do-dont-example.scss

@@ -152,6 +152,6 @@
 }
 
 // Video
-.#{$prefix}--example .#{$prefix}--video {
+.#{$prefix}--example [class^='Video-module--video'] {
   margin-bottom: 0;
 }

packages/gatsby-theme-carbon/src/components/MDXProvider/MDXProvider.js

@@ -0,0 +1,9 @@
+import React from 'react';
+import { MDXProvider as Provider } from '@mdx-js/react';
+import defaultComponents from './defaultComponents';
+
+const MDXProvider = ({ components = defaultComponents, ...rest }) => (
+  <Provider components={components} {...rest} />
+);
+
+export default MDXProvider;

packages/gatsby-theme-carbon/src/components/MDXProvider/defaultComponents.js

@@ -0,0 +1,54 @@
+import React from 'react';
+
+import { P, H1, H2, H3, H4, H5, Ul, Ol, Blockquote } from '../markdown';
+import PageTable from '../PageTable';
+import Code from '../Code';
+import PageDescription from '../PageDescription';
+import Video from '../Video';
+import DoDontExample from '../DoDontExample';
+import Caption from '../Caption';
+import ResourceCard from '../ResourceCard';
+import ArticleCard from '../ArticleCard';
+import Aside from '../Aside';
+import FeatureCard from '../FeatureCard';
+import ImageCard from '../ImageCard';
+import { Row, Column, Grid } from '../Grid';
+import { AnchorLink, AnchorLinks } from '../AnchorLinks';
+import { Tab, Tabs } from '../Tabs';
+import Link from '../Link';
+
+const components = {
+  wrapper: function Wrapper({ children, ...props }) {
+    return <div {...props}>{children}</div>;
+  },
+  h1: H1,
+  h2: H2,
+  h3: H3,
+  h4: H4,
+  h5: H5,
+  p: P,
+  ol: Ol,
+  ul: Ul,
+  blockquote: Blockquote,
+  pre: Code,
+  table: PageTable,
+  a: Link,
+  PageDescription,
+  Video,
+  DoDontExample,
+  Row,
+  Column,
+  Grid,
+  Caption,
+  ResourceCard,
+  ArticleCard,
+  Aside,
+  FeatureCard,
+  ImageCard,
+  AnchorLink,
+  AnchorLinks,
+  Tab,
+  Tabs,
+};
+
+export default components;

packages/gatsby-theme-carbon/src/components/MDXProvider/index.js

@@ -0,0 +1,3 @@
+import MDXProvider from './MDXProvider';
+
+export default MDXProvider;

packages/gatsby-theme-carbon/src/components/Video/Video.js

@@ -1,7 +1,6 @@
 import React from 'react';
 import PropTypes from 'prop-types';
 import cx from 'classnames';
-
 import { video, vimeo } from './Video.module.scss';
 
 export const Video = ({ vimeoId, title, ...props }) => {