Merge pull request #49 from ember-learn/easier-hbs-in-markdown

Easier hbs in markdown

Author: samselikoff

.eslintrc.js

@@ -30,7 +30,8 @@ module.exports = {
         'ember-cli-build.js',
         'config/**/*.js',
         'lib/**/*.js',
-        'tests/dummy/config/**/*.js'
+        'tests/dummy/config/**/*.js',
+        'tests-node/**/*.js'
       ],
       excludedFiles: [
         'app/**',
@@ -58,6 +59,14 @@ module.exports = {
       env: {
         embertest: true
       }
+    },
+
+    // node test files
+    {
+      files: ['tests-node/**/*.js'],
+      rules: {
+        'node/no-unpublished-require': 'off'
+      }
     }
   ]
 };

.travis.yml

@@ -17,6 +17,7 @@ env:
     # See https://git.io/vdao3 for details.
     - JOBS=1
   matrix:
+    - EMBER_TRY_SCENARIO=node
     - EMBER_TRY_SCENARIO=ember-lts-2.12
     - EMBER_TRY_SCENARIO=ember-lts-2.16
     - EMBER_TRY_SCENARIO=ember-release

addon/components/docs-demo/x-live-example/component.js

@@ -11,9 +11,7 @@ export default Component.extend({
 
     // Set initial template from snippet
     let name = this.get('name');
-
-    // We support either .hbs snippets or .md
-    let rawTemplate = snippets[`${name}.hbs`] || snippets[`${name}.md`];
+    let rawTemplate = snippets[name] || '';
 
     this.set('rawTemplate', this._unindent(rawTemplate));
 

addon/components/docs-snippet/template.hbs

@@ -12,5 +12,5 @@
     {{/copy-button}}
   {{/if}}
 
-  {{code-snippet name=(if hasBlock (concat name '.hbs') name) language=language}}
+  {{code-snippet name=name language=language}}
 </div>

config/ember-try.js

@@ -1,6 +1,10 @@
 module.exports = {
   useYarn: true,
   scenarios: [
+    {
+      name: 'node',
+      command: 'yarn test:node'
+    },
     {
       name: 'ember-lts-2.12',
       npm: {

index.js

@@ -71,6 +71,7 @@ module.exports = {
 
     this._super.included.apply(this, arguments);
 
+    includer.options.includeFileExtensionInSnippetNames = includer.options.includeFileExtensionInSnippetNames || false;
     includer.options.snippetSearchPaths = includer.options.snippetSearchPaths || ['tests/dummy/app'];
     includer.options.snippetRegexes = Object.assign({}, {
       begin: /{{#(?:docs-snippet|demo.example|demo.live-example)\sname=(?:"|')(\S+)(?:"|')/,

lib/utils/compile-markdown.js

@@ -3,14 +3,18 @@
 const marked = require('marked');
 const highlightjs = require('highlightjs');
 
-module.exports = function compileMarkdown(string, options) {
-  let config = { highlight };
+module.exports = function compileMarkdown(source, config) {
+  let tokens = marked.lexer(source);
+  let markedOptions = {
+    highlight,
+    renderer: new HBSRenderer(config)
+  };
 
-  if (options && options.targetHandlebars) {
-    config.renderer = new HBSRenderer();
+  if (config && config.targetHandlebars) {
+    tokens = compactParagraphs(tokens);
   }
 
-  return `<div class="docs-md">${marked(string, config)}</div>`;
+  return `<div class="docs-md">${marked.parser(tokens, markedOptions).trim()}</div>`;
 };
 
 function highlight(code, lang) {
@@ -21,22 +25,73 @@ function highlight(code, lang) {
   }
 }
 
+// Whitespace can imply paragraphs in Markdown, which can result
+// in interleaving between <p> tags and block component invocations,
+// so this scans the Marked tokens to turn things like this:
+//    <p>{{#my-component}}<p>
+//    <p>{{/my-component}}</p>
+// Into this:
+//    <p>{{#my-component}} {{/my-component}}</p>
+function compactParagraphs(tokens) {
+  let compacted = [];
+
+  compacted.links = tokens.links;
+
+  let balance = 0;
+  for (let token of tokens) {
+    if (balance === 0) {
+      compacted.push(token);
+    } else {
+      let last = compacted[compacted.length - 1];
+      last.text = `${last.text} ${token.text}`;
+    }
+
+    balance += count(/\{\{#/g, token.text);
+    balance -= count(/\{\{\//g, token.text);
+  }
+
+  return compacted;
+}
+
+function count(regex, string) {
+  let total = 0;
+  while (regex.exec(string)) total++;
+  return total;
+}
+
 class HBSRenderer extends marked.Renderer {
-  // Escape curlies in code spans/blocks to avoid treating them as Handlebars
+  constructor(config) {
+    super();
+    this.config = config || {};
+  }
+
   codespan() {
-    return this._escapeCurlies(super.codespan.apply(this, arguments));
+    return this._processCode(super.codespan.apply(this, arguments));
   }
 
   code() {
-    let code = this._escapeCurlies(super.code.apply(this, arguments));
+    let code = this._processCode(super.code.apply(this, arguments));
     return code.replace(/^<pre>/, '<pre class="docs-md__code">');
   }
 
   // Unescape quotes in text, as they may be part of a Handlebars statement
   text() {
-    return super.text.apply(this, arguments)
-      .replace(/&quot;|&#34;/g, `"`)
-      .replace(/&apos;|&#39;/g, `'`);
+    let text = super.text.apply(this, arguments);
+    if (this.config.targetHandlebars) {
+      text = text
+        .replace(/&quot;|&#34;/g, `"`)
+        .replace(/&apos;|&#39;/g, `'`);
+    }
+    return text;
+  }
+
+  // Escape curlies in code spans/blocks to avoid treating them as Handlebars
+  _processCode(string) {
+    if (this.config.targetHandlebars) {
+      string = this._escapeCurlies(string);
+    }
+
+    return string;
   }
 
   _escapeCurlies(string) {

package.json

@@ -17,7 +17,8 @@
     "build": "ember build",
     "lint:js": "eslint .",
     "start": "ember serve",
-    "test": "ember try:each"
+    "test": "ember try:each",
+    "test:node": "qunit tests-node"
   },
   "dependencies": {
     "@glimmer/syntax": "^0.30.5",
@@ -33,7 +34,7 @@
     "ember-cli-clipboard": "^0.8.1",
     "ember-cli-htmlbars": "^2.0.3",
     "ember-cli-sass": "7.1.3",
-    "ember-code-snippet": "^2.0.0",
+    "ember-code-snippet": "dfreeman/ember-code-snippet#exclude-file-extension",
     "ember-component-css": "^0.3.5",
     "ember-data": "^2.18.0",
     "ember-href-to": "^1.15.1",
@@ -64,6 +65,7 @@
   },
   "devDependencies": {
     "broccoli-asset-rev": "^2.6.0",
+    "common-tags": "^1.7.2",
     "ember-ajax": "^3.0.0",
     "ember-cli": "~2.18.1",
     "ember-cli-dependency-checker": "^2.1.0",
@@ -85,7 +87,8 @@
     "ember-source": "~2.18.0",
     "eslint-plugin-ember": "^5.0.3",
     "eslint-plugin-node": "^5.2.1",
-    "loader.js": "^4.6.0"
+    "loader.js": "^4.6.0",
+    "qunit": "^2.5.0"
   },
   "engines": {
     "node": "^4.5 || 6.* || >= 7.*"

tests-node/unit/utils/compile-markdown-test.js

@@ -0,0 +1,40 @@
+'use strict';
+
+const QUnit = require('qunit'), test = QUnit.test;
+const stripIndent = require('common-tags').stripIndent;
+const compileMarkdown = require('../../../lib/utils/compile-markdown');
+
+QUnit.module('Unit | compile-markdown', function(hooks) {
+  test('compacting paragraphs', function(assert) {
+    let input = stripIndent`
+      {{#foo-bar}}
+
+      {{/foo-bar}}
+    `;
+
+    let result = compileMarkdown(input, { targetHandlebars: true });
+    let expected = stripIndent`
+      <div class="docs-md"><p>{{#foo-bar}} {{/foo-bar}}</p></div>
+    `;
+
+    assert.equal(result, expected);
+  });
+
+  test('compacting implicit code blocks', function(assert) {
+    // Surrounding whitespace + 4-space indent = code block in MD
+    let input = stripIndent`
+      {{#foo-bar}}
+
+          hello
+
+      {{/foo-bar}}
+    `;
+
+    let result = compileMarkdown(input, { targetHandlebars: true });
+    let expected = stripIndent`
+      <div class="docs-md"><p>{{#foo-bar}} hello {{/foo-bar}}</p></div>
+    `;
+
+    assert.equal(result, expected);
+  });
+});

tests/dummy/app/app.js

@@ -3,7 +3,7 @@ import Resolver from './resolver';
 import loadInitializers from 'ember-load-initializers';
 import config from './config/environment';
 
-// BEGIN-SNIPPET sample-snippet
+// BEGIN-SNIPPET sample-snippet.js
 const App = Application.extend({
   modulePrefix: config.modulePrefix,
   podModulePrefix: config.podModulePrefix,

tests/dummy/app/pods/application/template.hbs

@@ -1,5 +1,4 @@
-{{! BEGIN-SNIPPET docs-demo-application-template }}
-{{! // tests/dummy/app/templates/application.hbs }}
+{{! BEGIN-SNIPPET docs-demo-application-template.hbs }}
 {{outlet}}
 
 {{docs-keyboard-shortcuts}}

tests/dummy/app/pods/docs/components/docs-demo/controller.js

@@ -3,11 +3,9 @@ import Controller from '@ember/controller';
 export default Controller.extend({
 
   actions: {
-    // BEGIN-SNIPPET docs-demo-multiple
     toggleIsShowing() {
       this.toggleProperty('isShowing');
     }
-    // END-SNIPPET
   }
 
 });

tests/dummy/app/pods/docs/components/docs-demo/demo1/template.hbs

@@ -1,11 +1,11 @@
-{{! BEGIN-SNIPPET docs-demo-basic-src }}
+{{! BEGIN-SNIPPET docs-demo-basic-src.hbs }}
 {{#docs-demo as |demo|}}
-  {{#demo.example name='docs-demo-basic'}}
-      <p>I am a <strong>handlebars</strong> template!</p>
-      <p>The value is: {{val}}</p>
-      <div>
-        {{input value=val}}
-      </div>
+  {{#demo.example name='docs-demo-basic.hbs'}}
+    <p>I am a <strong>handlebars</strong> template!</p>
+    <p>The value is: {{val}}</p>
+    <div>
+      {{input value=val}}
+    </div>
   {{/demo.example}}
 
   {{demo.snippet 'docs-demo-basic.hbs'}}

tests/dummy/app/pods/docs/components/docs-demo/demo2/component.js

@@ -3,11 +3,11 @@ import Component from '@ember/component';
 export default Component.extend({
 
   actions: {
-    // BEGIN-SNIPPET docs-demo-multiple
+    // BEGIN-SNIPPET docs-demo-multiple.js
     toggleIsShowing() {
       this.toggleProperty('isShowing');
     }
     // END-SNIPPET
   }
-  
+
 });

tests/dummy/app/pods/docs/components/docs-demo/demo2/template.hbs

@@ -1,6 +1,6 @@
 {{#docs-demo as |demo|}}
-  {{#demo.example data-test-id='docs-demo-multiple'}}
-    {{!-- BEGIN-SNIPPET docs-demo-multiple --}}
+  {{#demo.example data-test-id='docs-demo-multiple.hbs'}}
+    {{!-- BEGIN-SNIPPET docs-demo-multiple.hbs --}}
     <button onclick={{action 'toggleIsShowing'}}>
       Press me!
     </button>

tests/dummy/app/pods/docs/components/docs-demo/demo3/template.hbs

@@ -1,13 +1,13 @@
-{{!-- BEGIN-SNIPPET docs-demo-custom-src --}}
+{{!-- BEGIN-SNIPPET docs-demo-custom-src.hbs --}}
 {{#docs-demo as |demo|}}
-  {{#demo.example name='docs-demo-custom'}}
+  {{#demo.example name='docs-demo-custom.md'}}
     <pre>
     # Markdown
     - Has syntax highlighting, too
     </pre>
   {{/demo.example}}
 
   {{demo.snippet 'docs-demo-custom-src.hbs' label='Source'}}
-  {{demo.snippet 'docs-demo-custom.hbs' label='My Custom Label' language='markdown'}}
+  {{demo.snippet 'docs-demo-custom.md' label='My Custom Label' language='markdown'}}
 {{/docs-demo}}
 {{!-- END-SNIPPET --}}

tests/dummy/app/pods/docs/components/docs-demo/demo4/template.hbs

@@ -1,6 +1,6 @@
-{{! BEGIN-SNIPPET live-example-src }}
+{{! BEGIN-SNIPPET live-example-src.hbs }}
 {{#docs-demo as |demo|}}
-  {{#demo.live-example name='live-example'}}
+  {{#demo.live-example name='live-example.hbs'}}
     <p>The air up here is {{foo}}</p>
 
     {{input value=foo}}

tests/dummy/app/pods/docs/components/docs-hero/demo/template.hbs

@@ -1,5 +1,5 @@
 {{#docs-demo as |demo|}}
-  {{#demo.example name='docs-hero'}}
+  {{#demo.example name='docs-hero.hbs'}}
     {{docs-hero
       logo='ember'
       slim-heading='Super'

tests/dummy/app/pods/docs/components/docs-logo/demo1/styles.scss

@@ -1,4 +1,4 @@
-// BEGIN-SNIPPET docs-logo-ember-styles
+// BEGIN-SNIPPET docs-logo-ember-styles.scss
 .my-ember-addon-logo {
   background: #333;
   color: white;

tests/dummy/app/pods/docs/components/docs-logo/demo1/template.hbs

@@ -1,5 +1,5 @@
 {{#docs-demo as |demo|}}
-  {{#demo.example name='docs-logo-ember'}}
+  {{#demo.example name='docs-logo-ember.hbs'}}
     <div class='my-ember-addon-logo'>
       {{docs-logo}}
     </div>

tests/dummy/app/pods/docs/components/docs-logo/demo2/styles.scss

@@ -1,4 +1,4 @@
-// BEGIN-SNIPPET docs-logo-ember-cli-styles
+// BEGIN-SNIPPET docs-logo-ember-cli-styles.scss
 .my-ember-cli-addon-logo {
   background: #F44336;
   color: white;

tests/dummy/app/pods/docs/components/docs-logo/demo2/template.hbs

@@ -1,5 +1,5 @@
 {{#docs-demo as |demo|}}
-  {{#demo.example name='docs-logo-ember-cli'}}
+  {{#demo.example name='docs-logo-ember-cli.hbs'}}
     <div class='my-ember-cli-addon-logo'>
       {{docs-logo logo='ember-cli'}}
     </div>

tests/dummy/app/pods/docs/components/docs-logo/demo3/styles.scss

@@ -1,4 +1,4 @@
-// BEGIN-SNIPPET docs-logo-ember-data-styles
+// BEGIN-SNIPPET docs-logo-ember-data-styles.scss
 .my-ember-data-addon-logo {
   background: #2196F3;
   color: white;

tests/dummy/app/pods/docs/components/docs-logo/demo3/template.hbs

@@ -1,5 +1,5 @@
 {{#docs-demo as |demo|}}
-  {{#demo.example name='docs-logo-ember-data'}}
+  {{#demo.example name='docs-logo-ember-data.hbs'}}
     <div class='my-ember-data-addon-logo'>
       {{docs-logo logo='ember-data'}}
     </div>