
Markdown-in-js: inline Markdown for React and JSX - kylemathews
https://github.com/threepointone/markdown-in-js
======
Touche
This is a great illustration why using random babel plugins you find on the
internet is super dangerous.

This works because it _assumes_ you have named your local identifier either
`markdown` or `md` and are using that. If you want to use something else you
need to specify a custom pragma: [https://github.com/threepointone/markdown-
in-js#pragma](https://github.com/threepointone/markdown-in-js#pragma). And
that feature didn't exist until 6 hours ago.

Why is this dangerous? Let's imagine you use `markdown` and you chug along for
another 5 months on this project and you need to use `mdown` in some file, or
maybe a coworker uses `mdown` because why not? So it doesn't work. And you're
confused. And you spend hours trying to figure out why your app is broke.

People need to realize that by using a bunch AST transforms you are creating
your own one-off language, and one that has no _visual indicator_ that this is
different in any way. It's just a tagged template literal, right? Stick to
babel plugins for official language features that at least have a chance of
becoming part of JavaScript. This thing is going to stop working as soon as
the developer loses interest, and then you're going to be stuck with your
Frankenstein language no one can understand.

~~~
phpnode
Here's a PR that fixes this issue -
[https://github.com/threepointone/markdown-in-
js/pull/2](https://github.com/threepointone/markdown-in-js/pull/2)

~~~
Touche
Note that local identifiers (such as vars) mask the import identifier so it
will be easy to create a false positive.

~~~
morgante
It seems like you're looking to find something to complain about. Yes, you
generally have to be careful about variable collisions. That is in no way
specific to this module and, frankly, is something any competent programmer
should be aware of.

~~~
Touche
It is specific to this project, in that it will rewrite your code to mean
something other than what you intended it to mean.

I'm not being critical of this project, I'm being critical of the all too
common practice these days of installing a dozen or more Babel plugins to fix
every problem that exists, and thus creating your own one-off language that
will be unreadable in 6 months.

Babel has become the new hammer in front-end development. Everything looks
like a nail.

~~~
morgante
I really don't see where you're getting that from. How on earth does it
"rewrite your code to mean something other than what you intended it to mean?"
I explicitly included the "markdown" identifier. What on earth could I have
meant otherwise?

How is:

    
    
       import markdown from 'markdown-in-js';
    
       const MyMarkdown = markdown`#Headline`;
    

any less clear than:

    
    
       import markdown from 'markdown-function-tool';
    
       const MyMarkdown = markdown('#Headline');
    

It's totally explicit and actually allows compile-time validation. I really
don't understand your objection.

This will not be "unreadable in 6 months" any more than JSX or GraphQL are.
Since I have plenty of projects that are over 6 months old using those
techniques, I'm quite confident they work fine. It's not like there's any
magic or implicit references going on.

~~~
Touche
Because if you do:

    
    
       import markdown from 'markdown-in-js';
    
       var markdown = function() { }
    
       var foo = markdown` #Header ... `;
    

It will incorrectly rewrite this template literal. And while they could
potentially fill this hole, it doesn't change the fact this is unreadable
code; there's nothing from the code that signifies it will be converted into
some function calls the way that JSX or GraphQL at least have some visual
signifiers.

JSX and GraphQL, I'm not a fan of either, but are at least real projects with
standards texts written for. This is _not_ a criticism of this project, but
the practice of installing a bunch of AST transforms to save you a couple of
keystrokes creates code that reads as 1 thing, but compiles to something much
different.

If you don't recognize how changing your code to mean something different
based on an AST is essentially creating a one-off language, I don't know how
to help you.

~~~
morgante
> It will incorrectly rewrite this template literal.

That is a bug and should be fixed.

I'm not sure what visual signifiers that GraphQL has which this doesn't.

It's a fairly clear pattern of what's going on. I really don't see what is
"unreadable" about it.

~~~
Touche
It's a leaky abstraction. The point is to make your code do something other
than what you described it as doing (because it will do it "better"). That's
what makes it unreadable; hiding behavior from code decreases readability.

I'm not that familiar with GraphQL, but as far as I can tell it doesn't depend
on AST transforms. It seems to be a DSL that uses tagged templates. There's
nothing wrong with DSLs.

------
threepointone
Hi folks, author here. I wrote this for myself for a docs site I'm building,
and didn't want to ship a markdown parser to the browser. It's mostly for
aesthetics, without sacrificing performance. Custom components for primitives
are a nice addition, especially for styling.

I don't know whether it's a good idea, but I like it so far.

~~~
tracker1
I'm pretty happy to see it... IMHO, this is actually a great value add for
React, as when typing longer text, I'd rather use MD more often than not... I
wish that common markdown was closer to gfm, but to each their own. Still a
nice thing to have.

------
andreasklinger
Maybe a stupid Q - i assume there is a good reason - most likely related to
syntax clash…

Why is this not a component?

as in:

<Markdown> Text </Markdown>

~~~
tlrobinson
Looks like it's advertised as "zero-overhead", i.e. it gets compiled by Babel
at build time. Not sure it would make a big difference for most apps though.

I think more importantly it allows you to use JSX inside of your Markdown, and
use custom React components in place of normal HTML elements that Markdown
would normally emit.

I like the idea of a <Markdown> component though.

~~~
LeanderK
i am not really into this stuff, but would this be a good use for
[http://webcomponents.org](http://webcomponents.org)?

~~~
svachalek
It would not be hard to create a web component that translates markdown at
runtime; there are probably a few in there already. But that's a very
different use-case than transpilation.

Personally, I don't see much need for handling this at compile-time, but it is
what it is, and runtime rendering is a different thing entirely.

------
nathancahill
I'm all for pushing the boundaries of syntax with Babel, but frankly this
looks horrible. Is there an appealing reason to use this? I could see it being
interesting to render Markdown (like from a CMS) at runtime, but at compile
time there's not much benefit over JSX right?

~~~
masterj
It could be very useful for docs sites, blogs, coding books. Anything where
ease-of-authoring is the highest priority. You could maintain it in markdown
but also inject your custom components for examples or bits of interactivity.

------
bArray
Slightly related, I wrote some basic JS a while back to convert a page full of
markdown into HTML client side, without locking up the client:

Original - [http://coffeespace.org.uk/loader-
orig.js](http://coffeespace.org.uk/loader-orig.js) Minified -
[http://coffeespace.org.uk/loader.js](http://coffeespace.org.uk/loader.js)

Why? I don't know, it seemed like a great idea at the time to get my clients
doing all the heavy lifting. Page download times are typically less than all
other pages given how rich the content is.

------
b34r
I made something similar: [https://www.npmjs.com/package/markdown-to-
jsx](https://www.npmjs.com/package/markdown-to-jsx)

------
true_religion
Is there a demo?

