feat: pass MDX frontmatter title into page <title>

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

@@ -1,5 +1,7 @@
 ---
 title: Markdown
+description: 'Carbon Gatsby theme markdown documentation'
+keywords: 'ibm,carbon,gatsby,mdx,markdown'
 ---
 
 <PageDescription>
@@ -21,6 +23,18 @@ For most pages, we recommend starting with a `PageDescription` followed by `Anch
   <AnchorLink>Blockquotes</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: 'Carbon Gatsby theme markdown documentation'
+keywords: 'ibm,carbon,gatsby,mdx,markdown'
+---
+```
+
 ## Text decoration
 
 Emphasis, aka italics, with _asterisks_ or _underscores_.

packages/example/src/pages/guides/configuration.mdx

@@ -16,6 +16,7 @@ Gatsby themes allow you to override configuration from the theme by defining the
   <AnchorLink>Image Compression</AnchorLink>
   <AnchorLink>Global Search</AnchorLink>
   <AnchorLink>Edit on Github link</AnchorLink>
+  <AnchorLink>Other options</AnchorLink>
 </AnchorLinks>
 
 ## Site Title and Description
@@ -148,14 +149,20 @@ To add a link to the bottom of each page that points to the current page source
 
 - `additionalFontWeights` – add support for additional Plex font weights. Don't forget to specify italics for the additional weights if needed.
 - `mdxExtensions` – change the file extensions processed by `gatsby-mdx` (default ['.mdx', '.md'])
+- `titleType` – pick between three formats for the `<title>` element for your site. Here are the three options using this page as an example:
+
+  - `page`: "Configuration" (default)
+  - `site`: "Gatsby Theme Carbon"
+  - `append`: "Gatsby Theme Carbon – Configuration"
 
 ```js
 plugins: [
     {
       resolve: 'gatsby-theme-carbon',
       options: {
         additionalFontWeights: ['200', '200i'],
-        mdxExtensions: ['.mdx']
+        mdxExtensions: ['.mdx'],
+        titleType: 'append'
       },
     },
   ],

packages/example/src/pages/index.mdx

@@ -1,5 +1,4 @@
 import HomepageTemplate from 'gatsby-theme-carbon/src/templates/Homepage';
-
 export default HomepageTemplate;
 
 ## MDX content starts here

packages/gatsby-theme-carbon/gatsby-node.js

@@ -21,7 +21,8 @@ exports.onPreBootstrap = ({ store, reporter }) => {
 // We need to provide the actual file that created a specific page to append links for EditLink.
 // We can't do page queries from MDX templates, so we'll add the page's relative path to context after it's created.
 // The context object **is** supplied to MDX templates through the pageContext prop.
-exports.onCreatePage = ({ page, actions }) => {
+exports.onCreatePage = ({ page, actions }, pluginOptions) => {
+  const { titleType = 'page' } = pluginOptions;
   const { createPage, deletePage } = actions;
   const [relativePagePath] = page.componentPath.split('src/pages').splice('-1');
   deletePage(page);
@@ -30,6 +31,7 @@ exports.onCreatePage = ({ page, actions }) => {
     context: {
       ...page.context,
       relativePagePath,
+      titleType,
     },
   });
 };

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

@@ -10,7 +10,16 @@ import Container from './Container';
 
 import '../styles/index.scss';
 
-const Layout = ({ children, homepage, shouldHideHeader, ...rest }) => {
+const Layout = ({
+  children,
+  homepage,
+  shouldHideHeader,
+  titleType,
+  pageTitle,
+  pageDescription,
+  pageKeywords,
+  ...rest
+}) => {
   const is404 = children.key === null;
 
   useLayoutEffect(() => {
@@ -27,7 +36,12 @@ const Layout = ({ children, homepage, shouldHideHeader, ...rest }) => {
 
   return (
     <>
-      <Meta />
+      <Meta
+        titleType={titleType}
+        pageTitle={pageTitle}
+        pageDescription={pageDescription}
+        pageKeywords={pageKeywords}
+      />
       <Header shouldHideHeader={shouldHideHeader} />
       <Switcher />
       <LeftNav

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

@@ -2,19 +2,34 @@ import React from 'react';
 import { Helmet } from 'react-helmet';
 import { useMetadata } from '../util/hooks';
 
-const Meta = () => {
+const Meta = ({ pageTitle, pageDescription, pageKeywords, titleType }) => {
   const { title, description, keywords } = useMetadata();
+
+  const getPageTitle = () => {
+    switch (titleType) {
+      case 'page':
+        // use site title for fallback
+        return pageTitle || title;
+      case 'site':
+        return title;
+      case 'append':
+        return `${title}${pageTitle ? ` – ${pageTitle}` : ''}`;
+      default:
+        return null;
+    }
+  };
+
   return (
     <Helmet
-      title={title}
+      title={getPageTitle()}
       meta={[
         {
           name: 'description',
-          content: description,
+          content: pageDescription || description,
         },
         {
           name: 'keywords',
-          content: keywords,
+          content: pageKeywords || keywords,
         },
       ]}
     />

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

@@ -13,8 +13,8 @@ import PageTabs from '../components/PageTabs';
 import Main from '../components/Main';
 
 const Default = ({ pageContext, children, location }) => {
-  const { frontmatter = {}, relativePagePath } = pageContext;
-  const { tabs, title } = frontmatter;
+  const { frontmatter = {}, relativePagePath, titleType } = pageContext;
+  const { tabs, title, description, keywords } = frontmatter;
   const scrollDirection = useScrollDirection();
   const shouldHideHeader = !!tabs && scrollDirection === 'down';
 
@@ -41,7 +41,14 @@ const Default = ({ pageContext, children, location }) => {
 
   const currentTab = getCurrentTab();
   return (
-    <Layout shouldHideHeader={shouldHideHeader} homepage={false}>
+    <Layout
+      shouldHideHeader={shouldHideHeader}
+      homepage={false}
+      pageTitle={title}
+      pageDescription={description}
+      pageKeywords={keywords}
+      titleType={titleType}
+    >
       <PageHeader
         shouldHideHeader={shouldHideHeader}
         title={title}

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

@@ -14,17 +14,26 @@ const Homepage = ({
   SecondCallout,
   location,
   pageContext,
-}) => (
-  <Layout homepage>
-    {Banner}
-    {FirstCallout}
-    <Main>{children}</Main>
-    {SecondCallout}
-    <NextPrevious location={location} pageContext={pageContext} />
-    <WebsiteBackToTopBtn />
-  </Layout>
-);
-
+}) => {
+  const { frontmatter = {}, titleType } = pageContext;
+  const { title, description, keywords } = frontmatter;
+  return (
+    <Layout
+      pageTitle={title}
+      pageDescription={description}
+      pageKeywords={keywords}
+      titleType={titleType}
+      homepage
+    >
+      {Banner}
+      {FirstCallout}
+      <Main>{children}</Main>
+      {SecondCallout}
+      <NextPrevious location={location} pageContext={pageContext} />
+      <WebsiteBackToTopBtn />
+    </Layout>
+  );
+};
 Homepage.defaultProps = {
   Banner: (
     <HomepageBanner