powered by
LOGO

Why Not MDX?

FTD is often compared with MDX, mdsvex.

What is MDX?
React is a pretty popular Javascript library, and it exposes a syntax called JSX. JSX almost looks like HTML, but unlike HTML where the elements used, e.g. <p> that are provided by Web Browser, JSX allows you to use “react components”, e.g. <HelloComponent>.

Since JSX almost looks like HTML, it is easy to use compared to JavaScript, and is also quite familiar to people who understand HTML. HTML is easier to learn than JavaScript. So this gives a lot of JavaScript power without having to write JavaScript.

So what is MDX? MD of MDX refers to Markdown, and X is from JSX. MDX lets you write Markdown and JSX in the same file.

example.mdx
**Hello**, world!

Below is an example of markdown in JSX.

<div style={{padding: '1rem', backgroundColor: 'violet'}}>
  Try and change the background color to `tomato`.
</div>
In the above snippet we see Markdown, ** around “Hello” will make it appear as bold text, this is Markdown. And <div> is a JSX syntax for creating a “div”.

What is SVX?
Like React, svelte is another popular JavaScript framework for creating components. svelte components can be mixed with Markdown prose using mdsvex, also known as .svx.

example.svx
# mdsvex
svelte in markdown

<Penguin walk={true} />
Checkout their example to see what is possible with mdsvex.

Component Vs Prose Language
First difference between FTD with MDX or SVX is that the language in which you write your .mdx or .svx is not the same as the language in which you write the actual component implementation.

To write a new React component you have to switch to JavaScript:

shopping-list.jsx
class ShoppingList extends React.Component {
  render() {
    return (
      <div className="shopping-list">
        <h1>Shopping List for {this.props.name}</h1>
        <ul>
          <li>Instagram</li>
          <li>WhatsApp</li>
          <li>Oculus</li>
        </ul>
      </div>
    );
  }
}

// Example usage: <ShoppingList name="Mark" />
This is how you create a new component in React. You will have to add a lot of dependencies, configure webpack or some such JavaScript build system.

Similarly to create a new svelte component you have to write something like this:

HelloWorld.svelte
<`script`>
    let name = 'world';
</`script`>

<h1>Hello {name}!</h1>
This looks like HTML but is svelte syntax.

The authors have to completely switch the language when they are creating any component. And this is not a simple switch. Markdown is the base language of either of these technologies, mdx and svx, and Markdown is really easy to learn. Then you learn the HTML like syntax and add some components. HTML syntax is also quite easy to learn.

But to create even the simplest components you have to switch to JavaScript and JavaScript is a full blown programming language. And it’s not just JavaScript, React or svelte are quite non trivial learning curves on their own even if you know JavaScript.

Having to deal with two completely different languages, two languages whose learning curves are drastically different (how many people in your company can learn MDX/SVX? Maybe everyone. How many can realistically learn enough React to create components? Not even the entire software team.) means the expressive power available to authors is constrained by what is provided as existing components, if someone arrives at even slight variation to some component they have to either know JavaScript or they have to create a support ticket.

MDX/SVX: Basic Event Handling Is Difficult
When creating architecture diagrams, or visualisations of different kinds, say you want to tweak the documentation based on author’s preferred language, or based on operating system or browser of the reader etc, you want limited event handling to quickly create and update variables, and based on those variables show and hide portions of documentation.

We have been creating largely static documentation. But if some powers are given authors and creative people a lot can be created, but is not possible today because of upwards battle of learning JavaScript.

Layout Control
MDX/SVX typically require you to provide some sort of “layout”, in svx you do:

\---
layout: blog
\---
And in mdx you do something like:
import MyLayout from './MyLayout'

<MyLayout>

# Hello

This section has custom styles

</MyLayout>

This part of the document uses default styles
In both these examples the layout is not in the control of the author. If author wants to place to element side by side with some control over padding/spacing, author has to hope such a component or “layout” has been provided. Authors can not create their own layouts.

Data Modelling
The data modelling aspects of MDX and SVX are quite weak. Say you want to show your team on some page. You have to hope someone has created a <TeamMember> component, else with Markdown you will have a very boring presentation.

Now even if someone has anticipated your need and created the <TeamMember> component, there are going to be difficulties. If you want to specify more than one attribute for team member with prose in it.

<TeamMember name="Some Name">
    Bio of the member.
</TeamMember>
Here if you wanted to have Markdown styling in the Bio, it is easy, these frameworks support it and it’s easy to author. But if you wanted to style name attribute, or have another attribute like role where you want to use multiline text, it would become ugly.
<TeamMember
    name="John Doe, \"JD\""
    role="She is the customer success person and is responsible for timely handling of support queries etc."
>
    Bio of the member.
</TeamMember>
If an attribute becomes long it is not easy to put line breaks, you have to escape every double quote, and so on. It’s tricky and ugly.

You can always do something like this:

<TeamMember>
    <Name>Jane Doe, "JD"</Name>
    <Role>
        She is the customer success person and is responsible for timely
        handling of support queries etc.
    </Role>
    <Bio>
        Bio of Jane.
    </Bio>
</TeamMember>
This is definitely less torture to write compared to the previous example, but it completely defeats the point of using Markdown, this is too much syntax, markdwon was created because people do not like writing this kind of syntax.

But there is a much bigger problem. Here the order in which name, role and bio are displayed are decided by the author. In this case the name will show before role and bio in the end.

One can create hacky components that will do either parsing or run time DOM traversal to extract and tweak things, but it will mess with React’s virtual DOM rendering, and is not the React natural way of doing things. You can find a huge collection of React libraries, but none are used like this.

We want to pass clean data to the end component and let components figure out how to render them.

Consider FTD Samples
For team-member we could have a syntax like this:

-- team-member: Jane Doe, "JD"
role:
> She is the customer success person and is responsible for timely
> handling of support queries etc.

Bio of Jane.
As you can see its quite clean, you can nest things easily if you wanted to, and there is no double-quote in sight unless you want it in the text.

If you are going to show Jane Doe in more than places or pages you can easily create a component:

-- team-member jd: Jane Doe, "JD"
role:
> She is the customer success person and is responsible for timely
> handling of support queries etc.

Bio of Jane.
Look at how little difference there is between using a component and creating a new component, now you can use the newly created jd component anywhere:
-- jd:
It’s great to avoid duplication.
LOGO

Why Not MDX?

FTD is often compared with MDX, mdsvex.

What is MDX?
React is a pretty popular Javascript library, and it exposes a syntax called JSX. JSX almost looks like HTML, but unlike HTML where the elements used, e.g. <p> that are provided by Web Browser, JSX allows you to use “react components”, e.g. <HelloComponent>.

Since JSX almost looks like HTML, it is easy to use compared to JavaScript, and is also quite familiar to people who understand HTML. HTML is easier to learn than JavaScript. So this gives a lot of JavaScript power without having to write JavaScript.

So what is MDX? MD of MDX refers to Markdown, and X is from JSX. MDX lets you write Markdown and JSX in the same file.

example.mdx
**Hello**, world!

Below is an example of markdown in JSX.

<div style={{padding: '1rem', backgroundColor: 'violet'}}>
  Try and change the background color to `tomato`.
</div>
In the above snippet we see Markdown, ** around “Hello” will make it appear as bold text, this is Markdown. And <div> is a JSX syntax for creating a “div”.

What is SVX?
Like React, svelte is another popular JavaScript framework for creating components. svelte components can be mixed with Markdown prose using mdsvex, also known as .svx.

example.svx
# mdsvex
svelte in markdown

<Penguin walk={true} />
Checkout their example to see what is possible with mdsvex.

Component Vs Prose Language
First difference between FTD with MDX or SVX is that the language in which you write your .mdx or .svx is not the same as the language in which you write the actual component implementation.

To write a new React component you have to switch to JavaScript:

shopping-list.jsx
class ShoppingList extends React.Component {
  render() {
    return (
      <div className="shopping-list">
        <h1>Shopping List for {this.props.name}</h1>
        <ul>
          <li>Instagram</li>
          <li>WhatsApp</li>
          <li>Oculus</li>
        </ul>
      </div>
    );
  }
}

// Example usage: <ShoppingList name="Mark" />
This is how you create a new component in React. You will have to add a lot of dependencies, configure webpack or some such JavaScript build system.

Similarly to create a new svelte component you have to write something like this:

HelloWorld.svelte
<`script`>
    let name = 'world';
</`script`>

<h1>Hello {name}!</h1>
This looks like HTML but is svelte syntax.

The authors have to completely switch the language when they are creating any component. And this is not a simple switch. Markdown is the base language of either of these technologies, mdx and svx, and Markdown is really easy to learn. Then you learn the HTML like syntax and add some components. HTML syntax is also quite easy to learn.

But to create even the simplest components you have to switch to JavaScript and JavaScript is a full blown programming language. And it’s not just JavaScript, React or svelte are quite non trivial learning curves on their own even if you know JavaScript.

Having to deal with two completely different languages, two languages whose learning curves are drastically different (how many people in your company can learn MDX/SVX? Maybe everyone. How many can realistically learn enough React to create components? Not even the entire software team.) means the expressive power available to authors is constrained by what is provided as existing components, if someone arrives at even slight variation to some component they have to either know JavaScript or they have to create a support ticket.

MDX/SVX: Basic Event Handling Is Difficult
When creating architecture diagrams, or visualisations of different kinds, say you want to tweak the documentation based on author’s preferred language, or based on operating system or browser of the reader etc, you want limited event handling to quickly create and update variables, and based on those variables show and hide portions of documentation.

We have been creating largely static documentation. But if some powers are given authors and creative people a lot can be created, but is not possible today because of upwards battle of learning JavaScript.

Layout Control
MDX/SVX typically require you to provide some sort of “layout”, in svx you do:

\---
layout: blog
\---
And in mdx you do something like:
import MyLayout from './MyLayout'

<MyLayout>

# Hello

This section has custom styles

</MyLayout>

This part of the document uses default styles
In both these examples the layout is not in the control of the author. If author wants to place to element side by side with some control over padding/spacing, author has to hope such a component or “layout” has been provided. Authors can not create their own layouts.

Data Modelling
The data modelling aspects of MDX and SVX are quite weak. Say you want to show your team on some page. You have to hope someone has created a <TeamMember> component, else with Markdown you will have a very boring presentation.

Now even if someone has anticipated your need and created the <TeamMember> component, there are going to be difficulties. If you want to specify more than one attribute for team member with prose in it.

<TeamMember name="Some Name">
    Bio of the member.
</TeamMember>
Here if you wanted to have Markdown styling in the Bio, it is easy, these frameworks support it and it’s easy to author. But if you wanted to style name attribute, or have another attribute like role where you want to use multiline text, it would become ugly.
<TeamMember
    name="John Doe, \"JD\""
    role="She is the customer success person and is responsible for timely handling of support queries etc."
>
    Bio of the member.
</TeamMember>
If an attribute becomes long it is not easy to put line breaks, you have to escape every double quote, and so on. It’s tricky and ugly.

You can always do something like this:

<TeamMember>
    <Name>Jane Doe, "JD"</Name>
    <Role>
        She is the customer success person and is responsible for timely
        handling of support queries etc.
    </Role>
    <Bio>
        Bio of Jane.
    </Bio>
</TeamMember>
This is definitely less torture to write compared to the previous example, but it completely defeats the point of using Markdown, this is too much syntax, markdwon was created because people do not like writing this kind of syntax.

But there is a much bigger problem. Here the order in which name, role and bio are displayed are decided by the author. In this case the name will show before role and bio in the end.

One can create hacky components that will do either parsing or run time DOM traversal to extract and tweak things, but it will mess with React’s virtual DOM rendering, and is not the React natural way of doing things. You can find a huge collection of React libraries, but none are used like this.

We want to pass clean data to the end component and let components figure out how to render them.

Consider FTD Samples
For team-member we could have a syntax like this:

-- team-member: Jane Doe, "JD"
role:
> She is the customer success person and is responsible for timely
> handling of support queries etc.

Bio of Jane.
As you can see its quite clean, you can nest things easily if you wanted to, and there is no double-quote in sight unless you want it in the text.

If you are going to show Jane Doe in more than places or pages you can easily create a component:

-- team-member jd: Jane Doe, "JD"
role:
> She is the customer success person and is responsible for timely
> handling of support queries etc.

Bio of Jane.
Look at how little difference there is between using a component and creating a new component, now you can use the newly created jd component anywhere:
-- jd:
It’s great to avoid duplication.