Gatsby-theme-mdx-suite-core NPM

Gatsby MDX Suite

This collection of packages provides a drop in solution to support MDX in your GatsbyJS content workflow.
The intention is to provide a feature rich but fully custimizable set of components ready to use for your authors.

Core features

Fully customizable, extend and alterable MDX components. We just provide some minimal layout for the components and integrate with theme-ui.
Simple MDX tag structures to keep editing simple.
Contentful support
Starters & a theme for fast integration into your GatsbyJS project
Full i18n integration with helpers to easily create menus and language switchers
No crazy magic. The components code are pretty simple and very common dependencies are used
Automated generation of documentation of all components used within the system. Provides basic information about Markdown and MDX as well.
Components to render Menus, Links, Language Switch & more

Upcomming support of WYSIWYG editors. Waiting for https://github.com/blocks/blocks to get more progress, in the meanwhile https://github.com/Ionaru/easy-markdown-editor is being used.
Automatic parsing of MDX content to create graphql relations to used assets like images, videos & others.
More components to come

GDPR/DSGVO compatability
This whole thing is still alpha, so more to come and anything might change.

Core dependencies

React using mostly the hooks API & contexts
GatsbyJS with themes -> EmotionJS, theme-ui, styled systems
Pretty plain integration of i18next

Project structure

GastbyJS theme: gatsby-theme-mdx-suite
- Has required configuration opions
- Integrates theme-ui & MDX into your project
- Ensures the documentation will be rendered
- Initializes the MDX data context and i18next
MDX components: ./mdx/* or @gatsby-mdx-suite/mdx-*
- Basic - Very basic stuff like images and links
- Layout - Add visual structure to the content. Grids, columns and more.
- Contentful - Useful components when using Contentful as CMS
- Bandcamp/Instagram/YoutTube - Render social media content like videos, posts, tracks and whole feeds
- Media - A media gallery lightbox component which supports mixed content
- More... ?
Helper packages: ./packages/* or @gatsby-mdx-suite/*
- Contexts: Important and required package. Provides the contexts to get data available within MDX
- i18n: Helpers to generate paths and render language switch component
- seo: SEO helper components
- menu: generate single menu levels or whole menu trees
Starters: ./starters/* or gatsby-starter-mdx-suite-*
- Get quickly started, should be used as example implementations as well

Getting started

Either go for one of the starters and start hacking.

Or integrate the gatsby-theme-mdx-suite like the starters do into your project.

Or wait till somebody found time to write a tutorial how to do it.

Automated documentation

Within the /docs route a documentation apge will be generated. This provides:

Provide an introduction to Markdown and MDX to help new users getting into editing
Give an overview of all components integrated into the project
Renders interactive playgrounds for all components, including a list of available attributes.
Provides further information for developers:
- Which data needs to be available for rendering?
- Any extra information on how to alter and customize the components.
- ...?

The problem of availability of data within MDX

Data needs to be available within MDX but is queried via static graphQL (https://github.com/axe312ger/gatsby-mdx-suite/issues/7)
The data layer needs to provide information which assets/data is used within MDX (https://github.com/axe312ger/gatsby-mdx-suite/issues/8)

Configuration

The most accurate documentation are the starters. Especially https://github.com/axe312ger/gatsby-mdx-suite/tree/master/starters/contentful.

Integrate into your project

This is just a quick listing, the whole readme will be improved soon and a getting starting guide provided.

npm i gatsby-theme-mdx-suite
Add gatsby-theme-mdx-suite to your gatsby-config.js
Configure the theme.
- Example: https://github.com/axe312ger/gatsby-mdx-suite/blob/master/starters/contentful/gatsby-config.js#L16-L42
When creating your sub-pages, ensure to pass all required data to it. This is required to properly render links, menu items and the language switcher.
- Example: https://github.com/axe312ger/gatsby-mdx-suite/blob/master/starters/contentful/gatsby-node.js#L45-L50
Query all required data in your gatsby page template. Pass it down to the MdxDataContext
- Example: https://github.com/axe312ger/gatsby-mdx-suite/blob/master/starters/contentful/src/templates/page.js#L18-L48
- Related Context: https://github.com/axe312ger/gatsby-mdx-suite/blob/master/packages/contexts/mdx-data.js
Adjust the theme to your design preferences via theme-ui.
- Example: https://github.com/axe312ger/gatsby-mdx-suite/tree/master/starters/contentful/src/gatsby-plugin-theme-ui

How to alter the design

The idea is to support these options to alter the design:

Currently possible

Provide your own theme configuraton via theme-ui
Wrap and extend existing components with your own styles & logic
Replace whole components (even copy & paste might be the right way some times)
You can use emotion to wrap any component and then target other components within your custom styles.
- https://emotion.sh/docs/styled#styling-any-component
- https://emotion.sh/docs/styled#targeting-another-emotion-component

In consideration

We might provide several attributes to alter styling
Shadow components via theme-ui or overwrite components by passing them to the root component (should work, still to be tested, might be a bad idea)