Skip to content

0.10.0
Compare
Choose a tag to compare
@arcticicestudio arcticicestudio released this 10 Mar 07:57
v0.10.0
This tag was signed with the committer’s verified signature.
arcticicestudio Arctic Ice Studio
GPG key ID: 60C54F1519346085
Learn about vigilant mode.
9e008a3

Changelog for the official Nord website and documentation

Release Date: 2019-03-10 Project Board Milestone

Initial website launch ahead!

This version finally marks the last release before the long awaited initial website launch. It mainly focused on the MDX integration for blog posts and docs pages to finish the last remaining base routes in order to start the migration of Nord's documentation and poject asset content.

I'm really hyped and happy to announce this great milestone. It's been a long time, but finally all essential parts are done and it is ready to see the light of the production environment.

More details and information can also be found in the tweet thread of the initial website announcement.

Features

The following issues are related to the “Components” and “Responsive Web” design concepts to adjust the rendered content based on the available width and provide an optimal UX on smaller viewports.

MDX Integration for docs and blog pages — #129 ⇄ #130 (⊶ 05d3211)
↠ Integrated MDX with gh-gatsby-mdx including the implementation of the logic, layout and style for blog posts and docs pages (/docs and /blog routes).

MDX

MDX is used to handle the actual content of the documentation and blog posts.
Gatsby allows to use Markdown for content 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 makes use of the MDX specification, 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're using the official implementation, the fully-featured MDX parser, loader and JSX renderer together with the great Gatsby plugin gh-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.

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

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

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“ is 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 are used within custom fragments that have been 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 was created that initially includes some custom React components that can be imported and placed in MDX based content:

  • Image — An Gatsby image that extends GatsbyImage and is wrapped in a <figure> element with an optional caption.
  • Video — An <video> element that uses the Image component to render a poster with Gatsby's image rendering mechanism while the media file is being loaded to prevent layout shifting. It is also wrapped in a <figure> element with an optional caption.
  • ShinkedWidth — An container component that shrinks the maxiumum width for a better visual style and more readable text.

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 is used to map the project's base components to their specific HTML elements.

Docs Pages

The design of docs pages imitate a paper sheet where the overall styles using 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 presents an overview of Nord's blog posts in a three-column grid of card components sorted descending by their publish date.

Each card consists of an cover image together with the title of the post. The latest post spans over two columns at the top for a nice visual structure and better recognizability.
While a one-column card uses a cover image the latest post uses 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 makes 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 are 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 is then handled by the Gatsby image processing plugin workflow also documented in the Image Processing section above.

Another required node is the heroImage field that queries for a hero.(png|jpg|jpeg) image that is 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 the custom MDX component has been 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 has been 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

New official Nord Spectrum community — #131 (⊶ d71e4f9)
↠ Updated all URLs and references to the new official Nord Spectrum community that is available as of 2019-03-03.
Previously the official Arctic Ice Studio community was used with it's channels for Nord projects.

The full changelog is available here

Assets 2
Loading