Reacting Magically¶

Our philosophy is that content creators write the website. This means that what you write in your markdown file is what you will see on the website: you are in total control. We are just here to show you how to make the most of this new way of creating coherent community content. This page will teach you how to add automagic, ready-made React components to your files so that they really pop.

What is Mdx?¶

In short: it's your normal markdown -

md

- with an added little

x

factor. In practice, the

x

means that we can

extend

the capabilities of markdown and, in fact, create entire React components directly in our content files. If you don't know what a React component is, or why you would want to have them in your content files, don't stress! This section is all about showing you how this is actually a writing superpower, and how you can put it to best use when contributing.

You might have used a markdown cheatsheet before to figure out how to handle headings, links, images, and other basic necessities. The beauty of

mdx

is that all that stuff still works exactly the same. You'll still be writing what appears - for the most part - to be normal markdown. It's just that we can now do so much more...

Writing markdown which renders responsive React components is a superpower. We hope you'll use it responsibly.

How do I begin?¶

The easiest place to start is just by looking the raw file for a page on the site. Everything is open source, so if you browse through that link, you'll see how simple it is to "inject" a React compnent into the middle of your normal writing.

There are a number of these pre-written components that you can use to make the content you write really beautiful. Now that you've got the basic idea - just add unique elements by writing

<Some Component\>

in your markdown file - you can venture to the recipes section to see a list of all the components on offer here. Once you've mastered the basics - buttons, Calls to Action (CTAs), images, headers - you can progress to passing your own "props" to some of the more advanced components this site offers, all while remaining in a familiar

mdx

file.

Next up, we'll teach you about "frontmatter": all the stuff you see at the top of the markdown files in this site, which we use to control both SEO (Search Enging Optimization) like what title, description and image appears for each page, as well as where each page appears in the site's navigation, and whether there are translations available for it.