`docs-demo` fails to compile template with certain actions on elements

[alexlafroscia]

trafficstars

I'm trying to re-write my documentation for ember-steps using this addon and am running into trouble with the docs-demo component. For example, this snippet fails to compile in a Markdown file, despite being valid Handlebars

{{#docs-demo as |demo|}}
  {{#demo.example name='cookbook-tabs.hbs'}}
    {{#step-manager as |w|}}
      <button {{action w.transition-to 'first'}}>
        First Tab
      </button>
      <button>
        Second Tab
      </button>

      <hr>

      {{#w.step name='first'}}
        This content is on the first tab
      {{/w.step}}

      {{#w.step name='second'}}
        This content is on the second tab
      {{/w.step}}
    {{/step-manager}}
  {{/demo.example}}

  {{demo.snippet 'cookbook-tabs.hbs'}}
{{/docs-demo}}

It chokes on this part:

<button {{action w.transition-to 'first'}}>
  First
</button>

with the following error:

Closing tag button (on line 7) without an open tag.

Some different variations of the {{action}} also fail, such as this:

<button {{action w.transition-to 'first'}}>
  First
</button>

This one passes compilation, but doesn't actually do what I want it to

<button {{action w.transition-to}}>
  First
</button>

[dfreeman]

We do some slightly odd things to try and make Marked (our md parser) play nicely with handlebars syntax, but ultimately some weirdness like this still leaks through. In short, Marked sees the open <button> as invalid HTML because of the action, so it winds up escaping the < and >, but then leaving the dangling </button>.

https://runkit.com/dan-freeman/5aa86d39af01d30012bc8215

We can avoid this by switching to pedantic mode, but that opts us into whatever other old behavior the original markdown perl script had.

I think to solve this fully we'll need to take a different tack on the overall approach we're trying to use to get everything playing nicely together, possibly with some sort of pre-/postprocessor pair to stub out chunks of handlebars content during markdown compilation.

[dfreeman]

@alexlafroscia as a short-term workaround, you might try indenting that entire block by four spaces, which will cause Marked to interpret it all as a code block

[samselikoff]

@dfreeman Any thoughts/direction on a good approach here? I can carve out some time to work on it.

Pinging @pzuraq and @ef4 in case y'all have ideas too!

[dfreeman]

Three approaches that come to mind:

1. Investigate other markdown parsers to see if any others place more nicely with our needs
2. Advise people to move their hbs into dedicated local components if it reaches the point of complexity that this issue pops up
3. Preprocess the markdown files before handing them to marked, then do the same thing backwards afterwards e.g.

   # Heading
   {{#some-component as |sc|}}
     <p {{action sc.foo}}>Hello</p>
   {{/some-component}}
   

   # Heading
   <hbs-placeholder-1>
     <p hbs-placeholder-2>Hello</p>
   </hbs-placeholder-1>
   

[samselikoff]

think we should go with #2 for now, especially for docs-demo.