feat: export custom Title component from MDX (#420)

* feat: export custom title components from MDX

* Update packages/example/src/pages/components/MDX.mdx

Co-Authored-By: emyarod <emyarod@users.noreply.github.com>

packages/example/src/data/nav-items.yaml

@@ -24,6 +24,8 @@
   pages:
     - title: Markdown
       path: /components/markdown
+    - title: MDX
+      path: /components/MDX
     - title: Grid
       path: /components/Grid
     - title: Accordion

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

@@ -0,0 +1,55 @@
+---
+title: MDX
+description: guide for working with MDX and gatsby-theme-carbon
+---
+
+export const Title = () => (
+  <span>
+    First line <br /> Second line
+  </span>
+);
+
+<PageDescription>
+
+MDX allows for certain things beyond what markdown is capable of. Content here
+will discuss using those features to augment or modify the default content
+layout.
+
+</PageDescription>
+
+<AnchorLinks>
+  <AnchorLink>Frontmatter</AnchorLink>
+  <AnchorLink>Custom title</AnchorLink>
+</AnchorLinks>
+
+## Frontmatter
+
+You can declare frontmatter in your `.mdx` files to provide specific metadata for the theme to use.
+The most important of which is the `title`. You can also provide a description and keywords which will be added to the `head` of your document.
+
+```md
+---
+title: Markdown
+description: Usage instructions for the Markdown component
+keywords: 'ibm,carbon,gatsby,mdx,markdown'
+---
+```
+
+## Custom title
+
+You can export a `Title` component in order to render a unique title for a single page. This is particularly useful for including line breaks at a specific location.
+
+**Note:** You still need to provide a regular string title to the frontmatter for search, navigation, and the HTML header title to work.
+
+```jsx
+---
+title: MDX
+description: custom title page
+---
+
+export const Title = () => (
+  <span>
+    First line <br /> Second line
+  </span>
+);
+```

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

@@ -1,7 +1,6 @@
 ---
 title: Markdown
-description: Usage instructions for the Markdown component
-keywords: 'ibm,carbon,gatsby,mdx,markdown'
+description: Usage instructions for markdown
 ---
 
 <PageDescription>
@@ -23,18 +22,6 @@ For most pages, we recommend starting with a `PageDescription` followed by `Anch
   <AnchorLink>Blockquotes and citations</AnchorLink>
 </AnchorLinks>
 
-## MDX Frontmatter
-
-You can declare frontmatter in your `.mdx` files to provide specific metadata for the theme to use. The most important of which is the `title`. You can also provide a descriptions and keywords which will be added to the `head` of your document.
-
-```md
----
-title: Markdown
-description: Usage instructions for the Markdown component
-keywords: 'ibm,carbon,gatsby,mdx,markdown'
----
-```
-
 ## Text decoration
 
 Emphasis, aka italics, with _asterisks_ or _underscores_.

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

@@ -21,7 +21,7 @@ PageHeader.propTypes = {
   /**
    * Specify the title for the page
    */
-  title: PropTypes.string,
+  title: PropTypes.node,
 };
 
 export default PageHeader;

packages/gatsby-theme-carbon/src/templates/Default.js

@@ -10,7 +10,7 @@ import NextPrevious from '../components/NextPrevious';
 import PageTabs from '../components/PageTabs';
 import Main from '../components/Main';
 
-const Default = ({ pageContext, children, location }) => {
+const Default = ({ pageContext, children, location, Title }) => {
   const { frontmatter = {}, relativePagePath, titleType } = pageContext;
   const { tabs, title, theme, description, keywords } = frontmatter;
 
@@ -45,7 +45,7 @@ const Default = ({ pageContext, children, location }) => {
       pageKeywords={keywords}
       titleType={titleType}
     >
-      <PageHeader title={title} label="label" tabs={tabs} />
+      <PageHeader title={Title ? <Title /> : title} label="label" tabs={tabs} />
       {tabs && <PageTabs slug={slug} tabs={tabs} currentTab={currentTab} />}
       <Main padded>
         {children}