Markdown-in-js: inline Markdown for React and JSX | Hacker News Reader

Markdown-in-js: inline Markdown for React and JSX

github.com

84 pointskylemathews30 comments

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. 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.

It's just applying a function to a tagged template literal at compile-time instead of run-time, but it doesn't change the semantics of the language. Calling it a one-off language is hyperbole. Think of it as a compiler optimization step.

You bring up a good point with the hard-coded name though. Instead of hardcoding in the pragma it should probably check the name in the require. This wouldn't be difficult to add, and the project is only two days old.

It's not a compiler optimization step. Your code will through without the plugin: https://github.com/threepointone/markdown-in-js/blob/master/...

Here's a PR that fixes this issue - https://github.com/threepointone/markdown-in-js/pull/2

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

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.

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.

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.

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.

> 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.

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.

Yes, I noted that in the PR. It's easy to fix it, why don't you try?

As noted above, I think the practice of installing a bunch of Babel plugins is the wrong approach to this problem. If you want to avoid parsing markdown in the client, then pre-compile it using one of the million markdown compilers that exist.

merged and published, thanks!

> creating your own one-off language

It seems to me that this is nearly universal among nontrivial front and projects. Each one, through its build configuration, has a slightly different subset of all the language features supported by the current crop of JavaScript derived languages.

I believe this is a much underappreciated risk, that some projects will pay a significant price for, a few years from now.

We are managing it on our projects by preferring TypeScript, which appears to be advancing forward at a healthy yet careful pace, and which offers some configurability of the exact meaning of the language (in the form of settings in one file), yet does not offer unlimited arbitrary combinations of add-ons.

(That said, the Babel ecosystem is amazing, with lots of very interesting work by very smart people.)

> It seems to me that this is nearly universal among nontrivial front and projects. Each one, through its build configuration, has a slightly different subset of all the language features supported by the current crop of JavaScript derived languages.

It don't know what you mean, but it's certainly avoidable. You can do a few things:

* Only use language features of the browsers you are targeting. If you are targeting evergreen browsers (not IE) you can use most of ES2015 including classes, arrow functions, and template literals.

* Or use a transpiler but stick to some sane judgment of presets, preferable Stage 3 or greater, but at least stuff that's on the standards track.

* Don't use stuff like this: https://www.npmjs.com/package/babel-root-import that exists only to save yourself a couple of keystrokes.

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.

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.

Sunil is legit.

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:

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.

i am not really into this stuff, but would this be a good use for http://webcomponents.org?

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.

There already exist multiple Markdown components, for example https://github.com/rexxars/react-markdown

The interesting thing here is that it is inline.

edit: No judgement if being inline is a pro or a con. Personally I prefer to keep it in a specific component, but I see the appeal fo this

If it was passed as "children" rather than a named prop, it should look pretty similar. It just wouldn't be pre-compiled.

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?

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.

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 Minified - 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.

I made something similar: https://www.npmjs.com/package/markdown-to-jsx

Is there a demo?

Reply on news.ycombinator.com