Markdown has historically been a favourite format for programmers to put in writing documentation. It’s easy sufficient for nearly everybody to study and adapt to whereas making it straightforward to format and magnificence content material. It was so in style that instructions from Markdown have been utilized in chat purposes like Slack and Whatsapp as doc purposes, like Dropbox Paper and Notion. When GitHub launched Markdown assist for README documentation, in addition they rendered HTML content material from it — so, for instance, we might drop in some hyperlink and picture parts and they might render simply tremendous.
Regardless that Markdown isn’t damaged by any stretch of the creativeness, there’s all the time room for enchancment. That is the place Markdown Prolonged (MDX) is available in.
Frontend Armory makes use of MDX on its schooling playground, Demoboard. The playground helps MDX natively to create pages that serve each as demo and documentation, which is tremendous very best for demonstrating React ideas and elements..Brent Jackson has a model new approach of constructing web sites pairing MDX and Styled System. Every web page is written in MDX and Styled System types the blocks. It’s presently in improvement, however yow will discover extra particulars on the web site.Utilizing mdx-deck or Spectacle might make your subsequent presentation extra fascinating. You’ll be able to present demos straight in your deck with out switching screens!MDX Go, ok-mdx and Docz all present instruments for documenting element libraries in MDX. You’ll be able to drop elements proper within the documentation with Markdown and it’ll simply work™.Some websites, together with Zeit Now and Prisma docs, use MDX to put in writing content material.
Talking of embedding, MDX makes it really easy to embed iFrames created by third-party companies, say YouTube, Vimeo, Giphy, and many others.
Use it alongside Markdown
You’ll know a file is written in MDX as a result of it has an .mdx extension on the filename. However let’s take a look at what it seems to be like to truly write one thing in MDX.
import InteractiveChart from “../path/interactive-chart”;
# Hey – I am a Markdown heading
That is simply markdown textual content
See that? It’s nonetheless doable to make use of Markdown and we will write it alongside React elements once we need interactive visualizations or styling. Right here is an instance from my portfolio:
One other advantage of MDX is that, identical to elements, the information are composable. Because of this pages will be break up into a number of chunks and reused, rendering them all of sudden.
import Header from “./path/Header.mdx”
import Footer from “./path/Footer.mdx”
# Right here goes the precise content material.
Some random content material goes [here](hyperlink textual content)
Implementing MDX into apps
There are MDX plugins for many of the widespread React based mostly integration platforms, like Gatsby and Subsequent.
To combine it in a create-react-app undertaking, MDX offers a Babel Macro that may be imported into the app:
import from ‘./mdx.macro’
const MyDocument = React.lazy(() => importMDX(‘./my-document.mdx’))
It’s also possible to check out MDX on the playground they created for it.
MDX contributors are very actively engaged on bringing assist for Vue. A pattern is already obtainable on GitHub. That is although in Alpha and never prepared for manufacturing.
MDX plugins and extensions
A key benefit of MDX is that it’s a part of the unified consortium for content material that organizes comment content material. Because of this MDX can straight assist the huge ecosystem of comment plugins and rehype plugins — there’s no have to reinvent the wheel. A few of these plugins, together with remark-images and remark-redact, are exceptional to say the least. To make use of a plugin with MDX, you’ll be able to add them to them to your corresponding loader or plugin. You’ll be able to even write your personal MDX plugins by referring to the MDX Information for creating plugins.
MDX is only some years outdated however its affect has been rising within the content material house. From writing weblog posts and visualizing knowledge to creating interactive demos and decks, MDX is nicely suited for a lot of makes use of — nicely past what now we have coated right here on this introduction.