Based on https://tailwindcss.com/components/navigation#responsive-header

• Implement a menu für narrow screens

The approach of automatically parsing asset ids from MDX is to complicated to maintain. We should replace this technique via Contentful:

• New ContentType "MediaReference". Fields:
  • Asset ID
  • Asset context (to determine how it will be rendered)

Our custom editor / field UI extension could fill the field for the user. Investigation is need how to achieve this properly.

See: https://github.com/axe312ger/gatsby-mdx-suite/blob/master/gatsby-theme-mdx-suite/gatsby-node.js#L22-L54

Basically align video component to be able to just consume the graphql query result like we handle this for images already

will simplify https://github.com/axe312ger/gatsby-mdx-suite/blob/master/starters/contentful/src/templates/page.js#L36-L42 a lot

we introduced a few new components

• updated the asset parsing config in the starter

related: #25

As editor I want to be able to preview my content in all breakpoints to simplify review process

Simliar to:

• https://blocks-ui.com/demo/

• https://sizzy.co/

• Add a responsive preview to the editor

• add info to slug that index is a special case
• rename publishingDate to publicationDate

the context and reducer approach at the moment is problematic for SSR.

we might go for a simple map object for now, keeping the hook names to avoid breaking the api

We should add a svg icon library to render simple actions like move, fullscreen and so on for the docs.

The user of the theme can benefit from this as well

• ensure license allows usage & reusage
• ensure only used icons will be added to the payload
• add icon set

Candidates so far

• https://github.com/sschoger/heroicons-ui
• http://www.zondicons.com/
• https://cox-auto-kc.github.io/react-entypo/#/

While developing, you can accidentally use dependencies from other packages. This works fine on your machine, but as soon your publish this, it might cause issus in other people projects

For this we already have the npm run check-dependencies script in the root package.

• create a action that executes that script
• exclude starters + theme or go crazy and add gatsby support to depcheck

Add a playground to test and edit MDX

• create subpage in docs
• inline live editor fullscreen
• add useful default content

• Headings within content should be linkable
• consider option to add anchor to the front of the heading like tailwind does https://tailwindcss.com/docs/line-height#relative-line-heights
• consider option to link heading to itself like theme ui does https://theme-ui.com/color-modes#setting-the-color-mode

Having a global configuration for grid gaps in place is neat, but do we really have a good visual rythm?

Especially investigate how tailwind, theme ui and typographyjs play together

Our data can already handle multiple examples per component.

• Add a tab for every found example to the component demo section

• text component like Text, ResponsiveText, Link, CTA should be inline by default (span?)
• image component should get inline attribute

It can be very confusing, especially for clients, when the website needs time x (depending on the size of the new page payload) till they can reload to see new changes

We can improve the experience via:

• a pretty modal similar to https://www.gatsbyjs.org/docs/add-offline-support-with-a-service-worker/#displaying-a-message-when-a-service-worker-updates
• consider option to automatically reload
• consider option to ask for reload via https://developer.mozilla.org/en-US/docs/Web/API/notification

We got the basics (Colors & raw theme json output), but to make this really useful, we need to visualize the following theme config values:

• widths / gab / sizes
• colors + palette
• ransparent color set text shadow
• font families
• breakpoints

Current status:
https://gatsby-mdx-suite.netlify.com/docs/theme

As soon first tests of custom logic are set up, especially critical ones, readd dependabot to this repo

To allow container elements like viewport, section and so on have the same distance to each other, they should share the same theme config variable.

Add a page to the website that explains how to:

• write custom components and add it to your project
• how to parse and access asset referenced within the MDX source
• explain how we parse components for docs
  • react-docgen
  • MDX support for all descriptions
  • Uses @example doclet to parse examples
  • List available tokens (randomImageId, ...)

• how to use MDX
• special tricks like
• ...

• reduce image resolutation
• use superfast preset for videos
• limit number of assets being prepared for the docs rendering

As we have tailwind css now available, reworking these components is pretty straight forward.

columns will become , with smart but not-configurable adaptive behavior. We can simply use https://tailwindcss.com/docs/grid-template-columns

grid becomes a advanced, configurable, wrapping css grid wrapper with configurable adaptive behavior (users basically pass value for grid-template-rows && grid-template-columns)

As we have custom colors and color sets, we should help developers to access them easier.

• generate tailwind classes including our new colors
• check if we can get the sets into tailwind
• ease up resolving from color set name -> primary/secondary/background color when within a styled template literal
• check if we can use https://theme-ui.com/guides/nested-theme-providers instead of our custom logic

theme ui supports color modes out of the box, change the default theme to use all (useful) features of this

https://theme-ui.com/color-modes/

• add color mode switch to docs
• how do our color sets behave with this?
• add default dark mode
• add option to automatically switch to dark mode
• consider colorblind / a11y mode

No ensure styling is aligned through the whole MDX document, we should replace Markdown link and image components with ours

https://mdxjs.com/getting-started#table-of-components

https://github.com/axe312ger/gatsby-mdx-suite/blob/master/mdx/basic/gatsby-image.js

it basically adds svg support for https://github.com/axe312ger/gatsby-transformer-inline-svg

maybe related to https://github.com/timhagn/gatsby-background-image

theme ui supports color modes out of the box, change the default theme to use all (useful) features of this

https://theme-ui.com/color-modes/

• add color mode switch to docs
• how do our color sets behave with this?
• add default dark mode
• add option to automatically switch to dark mode
• consider colorblind / a11y mode

When scrolling the kitchen sync, the editor takes up a lot of space.

• make the editor optional by added a toggle to show/hide it

Allow components from node_modules, yarn workspace projects and src directory

That way we can have:

• project specific components
• community repo components
• it will work within this mono repo and other lerna/yarn workspace repos

gatsby clean && rm -rdf .docz

Currently we have some configuration in our own custom property within the theme.

We can get rid of this by extending sizes and similar properties in the theme

https://github.com/axe312ger/gatsby-mdx-suite/blob/master/gatsby-theme-mdx-suite/src/gatsby-plugin-theme-ui/index.js#L6-L8

• content column width -> sizes
• grid gap -> sizes
• content column gap -> sizes
• check if we can easily use breakpoint values by passing array values

Add action that simply lints all the code

Goal is to support windows out of the box, there are several smaller and bigger issues yet, here is a incomplete list:

• using env vars POSIX still does not work on default windows termin
• ...? more!?

The goal is to just nicely glue other projects together, workarounds should be removed on mid-term, preferably by contribution to other projects.

For now:

• twin.macro requires a commonjs config while theme-ui is commonly used with es-modules as gatsby supports these within src. We currently create the tailwind.config.js by babel-transforming and resolving the config on our own. https://github.com/axe312ger/gatsby-mdx-suite/blob/master/starters/contentful/scripts/generate-tailwind-config.js
• we currently overwrite values manually to make the tailwind config actually work with twin. Its very likely due to different behaviour of config parsing in both projects. ben-rogerson/twin.macro#8
• Could not detect more on a quick research in the code base. There is more 🕵

Move style related helpers to their own file

• Check if we have other helpers hidden somewhere else
• Related #63

extract custom code from into helpers package to simplify using this css trick in other components

https://github.com/axe312ger/gatsby-mdx-suite/blob/master/mdx/copy/responsive-text.js#L18-L37

Additionally to the common prop-types package, we could support and implement airbnb's version. It adds a lot of useful propTypes that allow us give users more context about what is possible. Even validation while editing should be possible.

https://github.com/airbnb/prop-types

These could be especially useful:

• and: ensure that all provided propType validators pass
  • foo: and([number, nonNegativeInteger])
• between: provide an object with an gt or gte number, and an lt or lte number (only one item allowed from each pairs; one or both pairs may be provided), and the resulting propType validator will ensure the prop value is a number within the given range. Alternatively, you can provide a function that takes the props object and returns a number for each of the gt/gte/lt/lte values.
  • foo: between({ gte: 0, lte: 5 })
  • foo: between({ gt: 0, lt: 5 })
• elementType: require that the prop be a specific type of React element - takes a Component, an HTML tag name, or "*" to match everything.
  • foo: elementType('span')
  • foo: elementType(Component)
• numericString: require the prop be a string that is conceptually numeric.
  • foo: numericString()
• or: recursively allows only the provided propTypes, or arrays of those propTypes.
  • foo: or([bool.isRequired, explicitNull()])
• range: provide a min, and a max, and the prop must be an integer in the range [min, max)
  • foo: range(-1, 2)
• stringEndsWith: takes a non-empty string, and returns a validator that ensures the prop value is a string that ends with it.
  • foo: stringEndsWith('.png')
• stringStartsWith: takes a non-empty string, and returns a validator that ensures the prop value is a string that starts with it.
  • foo: stringStartsWith('prefix-')
• valuesOf: a non-object requiring PropTypes.objectOf. Takes a propType validator, and applies it to every own value on the propValue.
  • foo: valuesOf(number)

• breakpoints
• colors
• whole theme config
• ...?

Probably name it pageContext as it will contain all relevant data to render the current page.

As the current page already has the active locale in its context, we can drop LocationContext completely.

Structure:

const {
...pageContext, // contains gatsbys pageContext values
data // contains data required to render MDX components
} = useContext(PageContext)

currently we always have contentful access && preview token in all environments available.

its enough to just have an access token that changes and switch the api url in the contentful source plugin

• get ride of the preview token env variable
• refactor so we support gatsby cloud setup without requiring to alter proposed env var config

Many people are familar with Markdown, a few with HTML/XML, very little with MDX.

Give some basic instructions in the docs how to use the MDX data format as an author.

Provide information about:

• headlines && paragraphs
• text formatting
• lists
• images
• linking
• structure / MDX
• Explain why the empy line is needed to switch context

We got several regressions when merging tailwind & theme ui. Especially for font sizes.

Fix these 🙃

Related:

• #79
• #63
• #64

We currently completely handle the rendering of the

Consider moving this into gatsby-transformer-video or add it as gatsby-video

See:

• https://github.com/axe312ger/gatsby-mdx-suite/blob/master/mdx/video/video.js#L61-L74
• https://github.com/axe312ger/gatsby-mdx-suite/blob/master/mdx/video/video.js#L96-L107

Lets move it to its own plugin, so we can improve it separately :)

https://github.com/axe312ger/gatsby-mdx-suite/blob/master/gatsby-theme-mdx-suite/gatsby-node.js#L11-L43

Currently, the code will break when the user will remove the video, youtube or instagram integration.

This is because the docs gather dummy information for all possible data formats to allow assets being used within the live editor.

• Use gatsby schema customization to add dummy types when source plugins are not enabled

There are many reasons why you should not do that, a good write up is this: https://css-tricks.com/use-target_blank/

But there are some cases where it makes sense, maybe you want to link your PWD within you marketing pages etc.

• make sure all core media components are properly supported, especially new video
• check if we can properly detect and render smaller thumbnails for component

The theme should have an option to skip rendering the docs on production environments.

Why?

This can speed up bundeling massively since the @mdx-js/runtime takes a while to be packed into the docs sub bundle.

Note: User should be able to control the rendering condition as everybody has their own prod/live/staging/whatever setup