feature: support using unified as a template tag. #40

ChristianMurphy · 2018-11-04T18:54:23Z

Inspired by hyperHTML and lit-html.
This PR adds new templateTag and templateTagSync functions.

These new functions allow unified to be applied as a tag/modifier function to any template string.

Simple Example:

var unified = require('unified')
var markdown = require('remark-parse')
var remark2rehype = require('remark-rehype')
var doc = require('rehype-document')
var format = require('rehype-format')
var stringify = require('rehype-stringify')

var html = unified()
  .use(markdown)
  .use(remark2rehype)
  .use(doc)
  .use(format)
  .use(stringify)
  .templateTagSync

console.log(html`# Hello world!`.toString())

Yields:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <h1>Hello world!</h1>
  </body>
</html>

Interpolation Example:

var unified = require('unified')
var markdown = require('remark-parse')
var remark2rehype = require('remark-rehype')
var doc = require('rehype-document')
var format = require('rehype-format')
var stringify = require('rehype-stringify')

var html = unified()
  .use(markdown)
  .use(remark2rehype)
  .use(doc)
  .use(format)
  .use(stringify)
  .templateTagSync

var file = html`
# Hello world!
${['First', 'Second', 'Third'].map(header => `## ${header} subsection`).join('\n')}
`

console.log(file.toString())

Yields:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <h1>Hello world!</h1>
    <h2>First subsection</h2>
    <h2>Second subsection</h2>
    <h2>Third subsection</h2>
  </body>
</html>

wooorm · 2018-11-04T19:12:42Z

Wow, this is super interesting!

I’m mainly wondering though, why do this? As in, your first example could be rewritten like so:

var unified = require('unified')
var markdown = require('remark-parse')
var remark2rehype = require('remark-rehype')
var doc = require('rehype-document')
var format = require('rehype-format')
var html = require('rehype-stringify')

var html = unified()
  .use(markdown)
  .use(remark2rehype)
  .use(doc)
  .use(format)
  .use(html)
  .processSync

console.log(html(`# Hello world!`).toString())

Note the processSync and the parens. As they’re so similar, what’s the benefit of having this?

ChristianMurphy · 2018-11-04T19:22:20Z

Template tags have a different signature than process expects.
For example:

console.log`1 ${2} 3 ${4}`
// [ "1 ", " 3 ", "" ]
// 2
// 4

Templates will take the static text and turn it into an array.
And takes interpolated values and spreads those across the other parameters.

This new function applies the String.raw helper which normalizes the values to something process can consume.

console.log(String.raw`1 ${2} 3 ${4}`)
// '1 2 3 4'

wooorm · 2018-11-04T19:25:36Z

Right I understand that part, but for your example, one could also do console.log(`1 ${2} 3 ${4}`), which yields the same as the last one with String.raw.

I get that it’s new and interesting, and maybe that’s good enough, but I don’t see much added value over calling a function ;)

ChristianMurphy · 2018-11-04T19:34:36Z

As it stands it's mostly syntax sugar to avoid needing (). 🙂

Where it could go is more interesting, similar to how MDX allows adding non-markdown content mid-document, supporting template literals opens up the possibility of being able to mixin new content types mid-document into any unified supported language.

wooorm · 2018-11-04T19:38:30Z

@ChristianMurphy Right! So it gets interesting when it would be possible to “evaluate” the tag and the template in a build step?

ChristianMurphy · 2018-11-04T19:43:32Z

My thought would be to use data type of interpolated values to determine how to evaluate.
typeof string would evaluate using current parser.
typeof object | function would switch to a different processing track.

ChristianMurphy · 2018-11-04T19:55:55Z

typeof object | function would switch to a different processing track

In the alternative track, unified would parse the content surrounding the interpolated value, then add the interpolated value directly into the AST.

E.G.

var unified = require('unified')
var markdown = require('remark-parse')
var remark2rehype = require('remark-rehype')
var doc = require('rehype-document')
var format = require('rehype-format')
var html = require('rehype-stringify')
const h = require('hastscript')

var md2ht = unified()
  .use(markdown)
  .use(remark2rehype)
  .use(doc)
  .use(format)
  .use(html)
  .templateTagSync

md2ht`## ${h('samp', 'sample header')}`

would generate

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <h2>
      <samp>
        sample header
      </samp>
    </h2>
  </body>
</html>

wooorm · 2018-11-04T19:58:23Z

@ChristianMurphy Huhh, very interesting indeed! I like where this is heading. But I foresee that a) this feature would change in the future, as b) we’re not entirely sure how this would work yet.

It could of course be that first we need the implementation before we can create interesting cases, but I feel like it’s better to develop both together. Develop both the implementation and the use-cases together?

ChristianMurphy · 2018-11-04T20:16:25Z

I feel like it’s better to develop both together. Develop both the implementation and the use-cases together?

I agree.
Personally, I see this as the first step toward being able try out potential use cases.
If it should start as an external wrapper for unified, rather than a core processor function, that's fine.
This PR is mostly to get a discussion started.

wooorm · 2018-11-04T21:07:08Z

@Hypercubed interested in hearing your thoughts on this!

Hypercubed · 2018-11-05T01:53:08Z

It's very interesting when you add the value interpolation, as you discussed. In lit-html they have directives that can do may cool things like handling async functions. At the moment I have a couple of comments:

The unified transformations are static usually with a stringification at the end. If the final result is text I don't really see directives being a help. This is unlike lit-html where directives can do interesting things when rending the dom. lit-html keeps track of static and dynamic parts of the template to allow efficient DOM updates. This simply has no benefit when generating static strings.
In lit-html the static and dynamic parts of the template are handled very differently. The static parts must be complete HTML elements (for example html<h1>${name} + html<h2> doesn't work). You cannot use dynamic content to generate elements (for example html<${tag}>${name}<${tag}>) for this reason and also because the dynamic parts are HTML escaped. The reason is, as discussed in my point Component/duo support, try catch? #1, lit-html needs to separate static and dynamic parts for efficient updates.
In your example md2ht## ${h('samp', 'sample header')} you are mixing md and HTML (actually HAST) this can be an issue. The function would need to know the final product is HTML and mixing syntax leads would lead to issues I would image.

All this said I think it would be very interesting if unified was able to convert to something like lit-html... then using a unified md2lit template method would be 💯

ChristianMurphy · 2018-11-05T02:55:01Z

Thanks for the feedback @wooorm and @Hypercubed!

something like lit-html... then using a unified md2lit template method would be 💯

It would be.
For that, it'd be nice to have incremental parsing, allowing more targeted updates of content.

ChristianMurphy requested a review from wooorm November 4, 2018 18:54

feature: support using unified as a template tag.

4527d01

ChristianMurphy force-pushed the feat/template-tag branch from 0bfa080 to 4527d01 Compare November 4, 2018 19:01

This comment has been minimized.

Sign in to view

docs: correct templateTagSync example

22bef15

ChristianMurphy closed this Nov 5, 2018

wooorm added the 💬 type/discussion This is a request for comments label Aug 10, 2019

ChristianMurphy deleted the feat/template-tag branch March 6, 2020 12:52

ChristianMurphy mentioned this pull request Sep 30, 2021

Add template literal tag syntax-tree/mdast-util-from-markdown#26

Closed

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feature: support using unified as a template tag. #40

feature: support using unified as a template tag. #40

ChristianMurphy commented Nov 4, 2018 •

edited

This comment has been minimized.

wooorm commented Nov 4, 2018

ChristianMurphy commented Nov 4, 2018 •

edited

wooorm commented Nov 4, 2018 •

edited

ChristianMurphy commented Nov 4, 2018 •

edited

wooorm commented Nov 4, 2018

ChristianMurphy commented Nov 4, 2018 •

edited

ChristianMurphy commented Nov 4, 2018 •

edited

wooorm commented Nov 4, 2018

ChristianMurphy commented Nov 4, 2018

wooorm commented Nov 4, 2018

Hypercubed commented Nov 5, 2018 •

edited

ChristianMurphy commented Nov 5, 2018

feature: support using unified as a template tag. #40

feature: support using unified as a template tag. #40

Conversation

ChristianMurphy commented Nov 4, 2018 • edited

This comment has been minimized.

wooorm commented Nov 4, 2018

ChristianMurphy commented Nov 4, 2018 • edited

wooorm commented Nov 4, 2018 • edited

ChristianMurphy commented Nov 4, 2018 • edited

wooorm commented Nov 4, 2018

ChristianMurphy commented Nov 4, 2018 • edited

ChristianMurphy commented Nov 4, 2018 • edited

wooorm commented Nov 4, 2018

ChristianMurphy commented Nov 4, 2018

wooorm commented Nov 4, 2018

Hypercubed commented Nov 5, 2018 • edited

ChristianMurphy commented Nov 5, 2018

ChristianMurphy commented Nov 4, 2018 •

edited

ChristianMurphy commented Nov 4, 2018 •

edited

wooorm commented Nov 4, 2018 •

edited

ChristianMurphy commented Nov 4, 2018 •

edited

ChristianMurphy commented Nov 4, 2018 •

edited

ChristianMurphy commented Nov 4, 2018 •

edited

Hypercubed commented Nov 5, 2018 •

edited