MDX is the combination of Markdown with JSX. This document defines a syntax for MDX (without JavaScript, MDXjs does that) by describing how to parse it. 1.2 Who created MDX?

• The magic of MDX is that it knows how to treat the above file as a Markdown file but also as a JavaScript module in the sense that it can import and use React's JSX. Using MDX with Gatsby Even though MDX isn't Gatsby-specific, this article is about setting up MDX with Gatsby specifically and some of the hurdles you might face.
• A.mdx file has exactly the same syntax as a regular Markdown file, but lets you import interactive JSX components and embed them within your content. Support for Vue components is in alpha. It’s easy to get MDX set up with Create React App. There are MDX plugins for Next.js and Gatsby.
• MDX is a standard file format that combines Markdown with JSX. This means you can use Markdown’s terse syntax (such as # heading) for your documentation, and freely embed JSX component blocks at any point in the file.

Released:

Extension for Python-Markdown that makes lists truly sane. Custom indents for nested lists and fix for messy linebreaks.

Project description

An extension for Python-Markdown that makes lists truly sane. Features custom indents for nested lists and fix for messy linebreaks and paragraphs between lists.

Features

• nested_indent option: Custom indent for nested lists. Defaults to 2. Doesn't mess with code indents, which is still 4.

• truly_sane option: Makes linebreaks and paragraphs in lists behave as usually expected by user. No longer adds weird p, no extra linebreaks, no longer fuses lists together when they shouldn't be fused (see screenshots and examples below). Defaults to True.

• Inherits sane lists behavior, which doesn't allow the mixing of ordered and unordered lists.

Installation

Pypi:

Directly from git:

Usage

Basic:

With explicit config:

Screenshots and examples

You can preview the new behaviour live at rentry.co (uses nested_indent: 2, truly_sane: True)

Some ugly screenshots because I'm lazy and cannot into gimp:

HTML

Data:

No extension:

Truly sane + 4 spaces:

Release historyRelease notifications | RSS feed

1.2

1.1.1

1.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Hashes for mdx_truly_sane_lists-1.2-py3-none-any.whl

Hashes for mdx_truly_sane_lists-1.2.tar.gz

In this post i'm going to discuss the term 'Fold it in' which I think was first coined byspences10 and it relates to a method of using React Components inMDX without the need to import them each and every time.

This term may or may not make 100% sense but naming things is hard and having a shorter way to describe an approach ormethod in my experience can be quite helpful, but whatever, 'you do you'

On a recent stream with my NatterPops chums we implemented MDX in Benedicte's blog and wedid attempt to explain what we meant by 'fold it in' You can watch that below.

In an attempt to explain a little more i've documented a couple of ways this approach can be used.

In this example i'll be specifically referring to methods I use in my Gatsby builds when working with MDX

MDX

For those not familiar with MDX it's similar to Markdown and additionally provides a method to render React componentsalong with typical Markdown syntax... MDX is brilliant and I love it!

Here's an example 👇

This will result in something like the below 👇

This is a heading written in markdown

This is the body written in markdown

And this is a React component 👇

This is a quote - from someone

You'll see near the top of some-blog-post.mdx there's a familiar looking import statement, this is pretty much whatyou'd expect to see if you were in Jsx land.

The import statement works the same way in MDX and allows you to import React components and render them alongside theusual Markdown syntax, but because it's a React component you can be a little more fancy. In this example i've addedx2 Svg quote icons either side of the text.

This approach works great for 'one off' components but in the case of the <CustomBlockquote /> you might want to useit more regularly when writing blog posts and having to import it for each and every MDX file can be a bit of a faff.

Fold it in

It's at this point where you might like to think about providing all MDX files with the ability to render the<CustomBlockquote /> component without needing to import it first. It's here where the term 'fold it in' makes a bitmore sense.

By 'folding' the component in to the <MDXProvider /> it will be ready to use by any MDX file without the need toimport it first.

Mdx Js

Your implementation of MDX will likely be different to mine but you will probably have an <MDXProvider /> somewhere inyour project. Here's a stripped back MDX Template file.

MDXProvider

To 'fold' components into MDX I use the components prop on the <MDXProvider /> and pass in the components i'd liketo make available to all MDX files.

Now that the <CustomBlockquote /> component has been 'folded' in there's no need to import it in the MDX blog post.

I've been asked a number of times about how this might affect bundle size / page size because using this method bundlesthe <CustomBlockquote /> component with each page regardless of if it's being used or not.

I have to be honest I don't know if that's actually the case. My assumption would be that webpack is smart enough toknow if a component is in use or not and therefore would only bundle the <CustomBlockquote /> as and when it'srequired but that's all a bit low level for me.

If you have questions surrounding the potential performance impacts of using this approach you might like to ask eitherChris Biscardi or John Otander, they're both veryapproachable chaps and were heavily involved in the creation of MDX.

However, if you have any other questions i'll do my best to answer them!

MDXRenderer

In the above example i'm using the <MDXProvider /> from @mdx-js/react and passing in a React component, in this nextbit i'm going to use the <MDXRenderer /> from gatsby-plugin-mdx to fold in 'data'.

I'll use the <CustomBlockquote /> component again but this time rather than rendering it's children i'm going to passdata stored in frontmatter back through the <MDXRenderer /> and make it available as a prop in the MDX body 🥴

Frontmatter

First I add a new field in frontmatter called quotes, it's of type array but looks like a list syntax in Markdown.If the below diff is a little hard to read, the quotes field should look like this, the --- are important as theysignify the beginning and end of frontmatter

Props instead of children

This is a weird one, but notice now instead of rendering the children of <CustomBlockquote /> as text I'm using anescaped Jsx syntax and pointing it to props.quotes[0]

The [0] is normal array syntax and represents an index from an array

MDXRenderer Props

In order for props.quotes[0] to equal something other than null I now query the frontmatter from the MDX Templatefile and pass the quotes back to the <MDXRenderer /> on a prop i've also called quotes

This is a slightly contrived example but I suppose it might be useful if you had a really long blog post with lots ofquotes and rather than having to scroll through the page and find one that might need editing you could find the quotein question by looking at the top of the file in the frontmatter. 🤷‍♂️

A more 'Real World' example of how the <MDXRenderer /> can be used to pass data from frontmatter back to the MDXbody can be see in this rather outdated post: MDX Embedded Images.

React Markdown Mdx

In this post I pass local image files from frontmatter, process them withchildImageSharp in the MDX Template before passing them back to the <MDXRenderer /> to display them anywhere in theMDX body.

Phew... that just about wraps things up... see you around 🕺