MDX Integration for docs and blog pages

[arcticicestudio]

Associated epic: #24, #63, #69

This issue documents the integration of MDX with gatsby-mdx to implement the logic and layout for /docs and /blog pages.

Responsive Design

All sections will follow the responsive design concept to adjust the rendered content based on the available width and provide an optimal UX on smaller viewports.

MDX

This issue handles the actual content of the documentation and blog posts.
Gatsby allows to use Markdown for it that comes with the nice side effect that the already existing documentations can simply be adapted and reused, but unfortunately it is limited to it's reduced and simplified syntax.

To also use the great power of React for content and not only layout and design this project will make use of the [MDX specification][gh-mdx-spec], a new language and abstract syntax tree definition.

In order to ensure a vibrant ecosystem and community, tooling needs to exist for formatting, linting, and plugins. This tooling requires a foundational specification and abstract syntax tree so that parsing is properly handled before transforming to JSX/Hyperscript/React/etc and potentially leveraging existing plugin ecosystems.

We will use the official implementation, the fully-featured MDX parser, loader and JSX renderer together with the great Gatsby plugin gatsby-mdx to allow to seamlessly use JSX in Markdown documents by importing components and export metadata or any other ECMAScript compliant data structures like frontmatter.

• 💻 Everything is a component: Use existing components inside your MDX and import other MDX files as plain components.
• 🔧 Customizable: Decide which component is rendered for each Markdown element ({ h1: MyHeading }).
• 📚 Markdown-based: The simplicity and elegance of Markdown remains, you interleave JSX only when you want to.
• 🔥 Blazingly blazing fast: MDX has no runtime, all compilation occurs during the build stage.

More details are provided by the official MDX and gatsby-mdx websites that include docs to get started, usage examples and advanced configuration and customization information.

Integration

To integrate MDX Gatsby's onCreateNode and createPages APIs will be implemented to handle the generation of the GraphQL MDX nodes and the subsequent automated creation of the docs pages and blog posts.

Image Processing

To get the best performance and quality for images Gatsby's awesome support for the high performance Node.js image processing library “Sharp“ will be used through gatsby-plugin-sharp, gatsby-transformer-sharp and gatsby-image.

To automatically process all images the transformer provides GraphQL query fragments like GatsbyImageSharpFluid. They will be used within custom fragments that'll be implemented to fit the project structure.

Custom Content Components

In order to create great documentations and blog posts with interactive elements a new mdx-elements atom core package will be created initially including some custom React components that can be imported and placed in MDX based content.

To reduce the requirement of imports and "logical Markdown" almost all HTML elements supported by the official Markdown as well as the GitHub Flavored Markdown Specification the MDXProvider component will be used to map the project's base components to their specific HTML elements.

Docs Pages

The design of docs pages will imitate a paper sheet where the overall styles will use a darker background so that the white paper stands out for a clear and sharp content visualization.

Blog Posts

The last remaining main page is /blog which will present an overview of Nord's blog posts in a three-column grid of card components sorted descending by their publish date. Each card will consist of an cover image together with the title of the post. The latest post will span over two columns at the top for a nice visual structure and better recognizability.
While a one-column card will use a cover image the latest post will use a banner that will either be the same image with a larger width, a variant of it or a completly different one.

A blog post itself will make use of the MDX features and the custom MDX components mentioned in the paragraph above. To simplify the usage of the cover and banner image they will be processed with Gatsby's onCreateNode API in combination with Gatsby's mapping configuration feature. This allows to map the paths of images to a File node that will then be handled by the Gatsby image processing plugin workflow also documented in the Image Processing section above.

Another required node will be the heroImage field that queries for a hero.(png|jpg|jpeg) image that'll be used as the hero of a blog post.
To also allow the usage of videos in blog posts or even as header a custom Video MDX component will be implemented including the optional heroVideo and heroVideoPoster GraphQL node fields.

All together that results in the following required and optional images/videos mapped to specific node fields with reserved file names per blog post directory for simple usage via GraphQL queries:

• bannerImage ↹ banner.(png|jpg|jpeg) — The required banner image of a blog post card (used when currently the latest two-column wide post placed on top of the grid).
• coverImage ↹ cover.(png|jpg|jpeg) — The required cover image of a one-column blog post.
• heroImage ↹ hero.(png|jpg|jpeg) — The required hero image of a blog post.
• heroVideo ↹ hero.(mp4|webm) — The optional hero video of a blog post.
• heroVideoPoster ↹ heroposter.(png|jpg|jpeg) — The optional poster image of a blog post heroVideo.

Known Problems

To prevent the unknwon field GraphQL error during build time (e.g. when there are no blog posts yet) a dummy/placeholder blog post and docs page will be created.
Anyway, they will be removed as soon as there is finally the first blog post and docs page. Later on the project will migrate to the shiny new schema customization API.

Tasks

• Install dependencies:
  • @babel/polyfill
  • @mdx-js/tag
  • camelcase
  • gatsby-image
  • gatsby-mdx
  • gatsby-plugin-sharp
  • gatsby-transformer-sharp
• Install development dependencies:
  • rehype-slug
  • remark-breaks
  • remark-github
  • @mdx-js/mdx
  • glob
• Implement Gatsby onCreateNode and createPages APIs.
• Configure gatsby-plugin-sharp, gatsby-transformer-sharp and gatsby-mdx including custom GraphQL fragments with the GatsbyImageSharpFluid type.
• Rename HTMLElements package to html-elements to reflect its purpose as package and not as a React component.
• Initially implement MDX-specific components Image (wraps GatsbyImage), ShinkedWidth and Video placed in the new atom core package mdx-elements.
• Implement DocsPage and BlogPost template components
  • Implement PaperSheet styled component for uniform docs design
  • Use MDXProvider to map custom HTML components to default Markdown elements
  • Implement wrapper component for doc pages to define specific style like Inter UI font family.
• Implement blog post grid and card components including the corresponsing GraphQL node fields and queries.