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.
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.
This issue documents the integration of MDX with gatsby-mdx to implement the logic and layout for
/docsand/blogpages.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.
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.
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
onCreateNodeandcreatePagesAPIs 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-sharpand 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-elementsatom 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
MDXProvidercomponent 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
/blogwhich 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
onCreateNodeAPI in combination with Gatsby'smappingconfiguration feature. This allows to map the paths of images to aFilenode 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
heroImagefield that queries for ahero.(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 customVideoMDX component will be implemented including the optionalheroVideoandheroVideoPosterGraphQL 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 postheroVideo.Known Problems
To prevent the
unknwon fieldGraphQL 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
onCreateNodeandcreatePagesAPIs.gatsby-plugin-sharp,gatsby-transformer-sharpandgatsby-mdxincluding custom GraphQL fragments with theGatsbyImageSharpFluidtype.HTMLElementspackage tohtml-elementsto reflect its purpose as package and not as a React component.Image(wrapsGatsbyImage),ShinkedWidthandVideoplaced in the new atom core packagemdx-elements.DocsPageandBlogPosttemplate componentsPaperSheetstyled component for uniform docs designMDXProviderto map custom HTML components to default Markdown elements