Configure Gatsby "Sharp" library and gatsby-mdx plugins

To get the best performance and quality for images the awesome Gatsby's
awesome support for the high performance Node.js image processing
library "Sharp" (1) is used through `gatsby-plugin-sharp` (2),
`gatsby-transformer-sharp` (3) and gatsby-image (4).

To automatically process all images the transformer provides GraphQL
query fragments like `GatsbyImageSharpFluid`. They are used within
custom fragments that have been implemented to fit the project structure.

References:
  (1) https://github.com/lovell/sharp
  (2) https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-sharp
  (3) https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-transformer-sharp
  (4) https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-image

GH-129

.gatsby/plugins/mdx.js

@@ -0,0 +1,39 @@
+/*
+ * Copyright (C) 2018-present Arctic Ice Studio <[email protected]>
+ * Copyright (C) 2018-present Sven Greb <[email protected]>
+ *
+ * Project:    Nord Docs
+ * Repository: https://github.com/arcticicestudio/nord-docs
+ * License:    MIT
+ */
+
+/**
+ * @file The configuration for the Gatsby plugin `gatsby-mdx`.
+ * @author Arctic Ice Studio <[email protected]>
+ * @author Sven Greb <[email protected]>
+ * @since 0.10.0
+ * @see https://mdxjs.com
+ * @see https://github.com/ChristopherBiscardi/gatsby-mdx
+ */
+
+const remarkBreaks = require("remark-breaks");
+const remarkGitHub = require("remark-github");
+const rehypeSlug = require("rehype-slug");
+
+const { metadataNordDocs } = require("../../src/data/project");
+
+const remarkGitHubOptions = {
+  repository: `${metadataNordDocs.repository.url}`,
+  mentionStrong: false
+};
+
+module.exports = {
+  defaultLayouts: {
+    blog: require.resolve("../../src/components/templates/blog/BlogPost.jsx"),
+    docs: require.resolve("../../src/components/templates/docs/DocsPage.jsx")
+  },
+  footnotes: true,
+  gatsbyRemarkPlugins: [],
+  hastPlugins: [rehypeSlug],
+  mdPlugins: [remarkBreaks, [remarkGitHub, remarkGitHubOptions]]
+};

gatsby-config.js

@@ -39,6 +39,7 @@ const gatsbyPluginGoogleGtagConfig = require("./.gatsby/plugins/google/gtag");
 const gatsbyPluginManifestConfig = require("./.gatsby/plugins/manifest");
 const gatsbyPluginRobotsTxtConfig = require("./.gatsby/plugins/robots-txt");
 const gatsbyPluginSourceGraphQlConfig = require("./.gatsby/plugins/source-graphql");
+const gatsbyPluginMdxConfig = require("./.gatsby/plugins/mdx");
 
 module.exports = {
   siteMetadata: {
@@ -57,6 +58,8 @@ module.exports = {
     "gatsby-plugin-sitemap",
     "gatsby-plugin-webpack-size",
     "gatsby-plugin-lodash",
+    "gatsby-plugin-sharp",
+    "gatsby-transformer-sharp",
     {
       resolve: "gatsby-plugin-canonical-urls",
       options: {
@@ -110,6 +113,10 @@ module.exports = {
       resolve: "gatsby-source-graphql",
       options: gatsbyPluginSourceGraphQlConfig
     },
+    {
+      resolve: "gatsby-mdx",
+      options: gatsbyPluginMdxConfig
+    },
     /* NOTE: The following plugins rely on the order in this array and must be placed at last in order work properly! */
     {
       resolve: "gatsby-plugin-manifest",

src/data/graphql/fragmentPropTypes.js

@@ -0,0 +1,127 @@
+/*
+ * Copyright (C) 2018-present Arctic Ice Studio <[email protected]>
+ * Copyright (C) 2018-present Sven Greb <[email protected]>
+ *
+ * Project:    Nord Docs
+ * Repository: https://github.com/arcticicestudio/nord-docs
+ * License:    MIT
+ */
+
+/**
+ * @file Provides prop types for global GraphQL fragments.
+ * @author Arctic Ice Studio <[email protected]>
+ * @author Sven Greb <[email protected]>
+ * @since 0.10.0
+ */
+
+import PropTypes from "prop-types";
+
+/**
+ * GraphQL fragment prop types for the Gatsby Image "fluid" object returned from the "ImageSharpFluid" query type.
+ *
+ * @see https://github.com/gatsbyjs/gatsby/blob/e6d7dc3a7adc122fd6a3c606978bc79dc59fce07/packages/gatsby-image/src/index.js#L444-L453
+ */
+const contentMdxImageFluidPropTypes = {
+  fluid: PropTypes.shape({
+    aspectRatio: PropTypes.number.isRequired,
+    base64: PropTypes.string,
+    originalImg: PropTypes.string,
+    originalName: PropTypes.string,
+    presentationHeight: PropTypes.number,
+    presentationWidth: PropTypes.number,
+    sizes: PropTypes.string.isRequired,
+    src: PropTypes.string.isRequired,
+    srcSet: PropTypes.string.isRequired,
+    srcSetWebp: PropTypes.string,
+    srcWebp: PropTypes.string,
+    tracedSVG: PropTypes.string
+  })
+};
+
+/**
+ * GraphQL fragment prop types for the frontmatter of a MDX content document.
+ */
+const contentMdxDocumentFrontmatterPropTypes = {
+  contentImages: PropTypes.arrayOf(
+    PropTypes.shape({
+      ...contentMdxImageFluidPropTypes
+    }),
+    PropTypes.shape({
+      ...contentMdxImageFluidPropTypes
+    })
+  ),
+  draft: PropTypes.bool,
+  title: PropTypes.string
+};
+
+/**
+ * GraphQL fragment prop types for the frontmatter of a blog post.
+ */
+const contentBlogPostFrontmatterPropTypes = {
+  frontmatter: PropTypes.shape({
+    introduction: PropTypes.string,
+    publishTime: PropTypes.string,
+    ...contentMdxDocumentFrontmatterPropTypes
+  })
+};
+
+/**
+ * GraphQL fragment prop types for the frontmatter of a docs page.
+ */
+const contentDocsPageFrontmatterPropTypes = {
+  frontmatter: PropTypes.shape({
+    subline: PropTypes.string,
+    ...contentMdxDocumentFrontmatterPropTypes
+  })
+};
+
+/**
+ * GraphQL fragment prop types for the node fields for content.
+ */
+const contentNodeFieldsPropTypes = {
+  contentSourceType: PropTypes.string,
+  slug: PropTypes.string,
+  slugParentRoute: PropTypes.string
+};
+
+/**
+ * GraphQL fragment prop types for the node fields of a blog post.
+ */
+const contentBlogPostFieldsPropTypes = {
+  fields: PropTypes.shape({
+    date: PropTypes.string,
+    relativeDirectory: PropTypes.string,
+    ...contentNodeFieldsPropTypes
+  })
+};
+
+/**
+ * GraphQL fragment prop types for the node fields of a blog post.
+ */
+const contentDocsPageFieldsPropTypes = {
+  fields: PropTypes.shape({ ...contentNodeFieldsPropTypes })
+};
+
+/**
+ * Prop types of the GraphQL fragment for a blog post.
+ */
+const contentBlogPostPropTypes = {
+  ...contentBlogPostFieldsPropTypes,
+  ...contentBlogPostFrontmatterPropTypes
+};
+
+/**
+ * Prop types of the GraphQL fragment for a blog post.
+ */
+const contentDocsPagePropTypes = {
+  ...contentDocsPageFieldsPropTypes,
+  ...contentDocsPageFrontmatterPropTypes
+};
+
+export {
+  contentBlogPostPropTypes,
+  contentBlogPostFrontmatterPropTypes,
+  contentDocsPagePropTypes,
+  contentDocsPageFrontmatterPropTypes,
+  contentMdxImageFluidPropTypes
+};

src/data/graphql/fragments.js

@@ -0,0 +1,132 @@
+/*
+ * Copyright (C) 2018-present Arctic Ice Studio <[email protected]>
+ * Copyright (C) 2018-present Sven Greb <[email protected]>
+ *
+ * Project:    Nord Docs
+ * Repository: https://github.com/arcticicestudio/nord-docs
+ * License:    MIT
+ */
+
+/**
+ * @file Provides global GraphQL fragments.
+ * @author Arctic Ice Studio <[email protected]>
+ * @author Sven Greb <[email protected]>
+ * @since 0.10.0
+ */
+
+import { graphql } from "gatsby";
+
+/**
+ * GraphQL fragment for fluid MDX document images.
+ * The value of the `maxWidth` query parameter is based on the maximum witdh of the content wrapper HTML element and
+ * the media breakpoints of the used global theme for "4K" devices.
+ */
+export const gqlFragmentContentMdxDocumentImageFluid = graphql`
+  fragment contentMdxDocumentImageFluid on ImageSharp {
+    fluid(maxWidth: 2560, quality: 90) {
+      originalImg
+      originalName
+      presentationHeight
+      presentationWidth
+      ...GatsbyImageSharpFluid
+    }
+  }
+`;
+
+/**
+ * GraphQL fragment for the frontmatter fields of an MDX blog post.
+ */
+export const gqlFragmentContentBlogPostFrontmatter = graphql`
+  fragment contentBlogPostFrontmatter on Mdx {
+    frontmatter {
+      contentImages {
+        childImageSharp {
+          ...contentMdxDocumentImageFluid
+        }
+      }
+      draft
+      heroImage {
+        childImageSharp {
+          ...contentMdxDocumentImageFluid
+        }
+      }
+      introduction
+      publishTime
+      title
+    }
+  }
+`;
+
+/**
+ * GraphQL fragment for the frontmatter fields of an MDX docs page.
+ */
+export const gqlFragmentContentDocsPageFrontmatter = graphql`
+  fragment contentDocsPageFrontmatter on Mdx {
+    frontmatter {
+      contentImages {
+        childImageSharp {
+          ...contentMdxDocumentImageFluid
+        }
+      }
+      draft
+      subline
+      title
+    }
+  }
+`;
+
+/**
+ * GraphQL fragment for the node fields of an MDX blog post.
+ * Gatsby internally relies on Moment.js for the provided `formatString` function.
+ * The allowed tokens can be found in the official Moment.js documentation.
+ *
+ * @see https://momentjs.com/docs/#/displaying/format
+ * @see https://www.gatsbyjs.org/docs/graphql-reference/#format
+ */
+export const gqlFragmentContentBlogPostFields = graphql`
+  fragment contentBlogPostFields on Mdx {
+    fields {
+      contentSourceType
+      date(formatString: "YYYY-MM-DDTHH:MM:ssZZ")
+      relativeDirectory
+      slug
+      slugParentRoute
+    }
+  }
+`;
+
+/**
+ * GraphQL fragment for the node fields of an MDX docs page.
+ */
+export const gqlFragmentContentDocsPagesFields = graphql`
+  fragment contentDocsPageFields on Mdx {
+    fields {
+      contentSourceType
+      relativeDirectory
+      slug
+      slugParentRoute
+    }
+  }
+`;
+
+/**
+ * GraphQL fragment for MDX blog posts.
+ * Includes the node `fields` and the frontmatter fields defined in each MDX blog post file.
+ */
+export const gqlFragmentContentBlogPost = graphql`
+  fragment contentBlogPost on Mdx {
+    ...contentBlogPostFields
+    ...contentBlogPostFrontmatter
+  }
+`;
+
+/**
+ * GraphQL fragment for MDX docs page.
+ * Includes the node `fields` and the frontmatter fields defined in each MDX docs page file.
+ */
+export const gqlFragmentContentDocsPage = graphql`
+  fragment contentDocsPage on Mdx {
+    ...contentDocsPageFields
+    ...contentDocsPageFrontmatter
+  }
+`;