Make it easier to write HBS in Markdown

Author: dfreeman

.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-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) {
+module.exports = function compileMarkdown(source, options) {
+  let tokens;
   let config = { highlight };
 
   if (options && options.targetHandlebars) {
     config.renderer = new HBSRenderer();
+    tokens = compactParagraphs(source);
+  } else {
+    tokens = marked.lexer(source);
   }
 
-  return `<div class="docs-md">${marked(string, config)}</div>`;
+  return `<div class="docs-md">${marked.parser(tokens, config).trim()}</div>`;
 };
 
 function highlight(code, lang) {
@@ -21,6 +25,36 @@ function highlight(code, lang) {
   }
 }
 
+function compactParagraphs(source) {
+  let tokens = marked.lexer(source);
+  let compacted = [];
+
+  compacted.links = tokens.links;
+
+  let diff = 0;
+  for (let token of tokens) {
+    let wasBalanced = diff === 0;
+
+    diff += count(/\{\{#/g, token.text);
+    diff -= count(/\{\{\//g, token.text);
+
+    if (wasBalanced) {
+      compacted.push(token);
+    } else {
+      let last = compacted[compacted.length - 1];
+      last.text = `${last.text} ${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
   codespan() {

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/pods/application/template.hbs

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

tests/dummy/app/pods/docs/quickstart/template.md

@@ -10,91 +10,82 @@ This quickstart guide will get you going with a docs site for your brand new add
 
 2. **Add the docs route.** Open `tests/dummy/app/router.js` and add a route named `docs`. Go ahead and make it nested, since this is where you'll be defining additional documentation pages.
 
-  ```js
-  // tests/dummy/app/router.js
-  this.route('docs', function() {
-    this.route('api', function() {
-      this.route('class', { path: '/:class_id' });
+  {{#docs-snippet name='quickstart-router' title='tests/dummy/app/router.js'}}
+    this.route('docs', function() {
+      this.route('api', function() {
+        this.route('class', { path: '/:class_id' });
+      });
     });
-  });
-  ```
+  {{/docs-snippet}}
 
 3. **Create your app skeleton.** Open your application template and add the DocsNavbar component, customizing its properties for your project. You can also add the global keyboard shortcuts component (use `?` to show the help window). Here's our application template:
 
-  {{docs-snippet name="docs-demo-application-template.hbs"}}
+  {{docs-snippet name="docs-demo-application-template" title="tests/dummy/app/templates/application.hbs"}}
 
 4. **Create your docs skeleton.** Create a template for the `docs` route and add the DocsViewer component.
 
-  ```hbs
-  {{! tests/dummy/app/pods/docs/template.hbs }}
-  {{#docs-viewer as |viewer|}}
-
-    {{#viewer.nav as |nav|}}
-      {{nav.item 'Overview' 'docs.index'}}
-    {{/viewer.nav}}
-
-    {{#viewer.main}}
-      <div class="docs-container docs__center">
-        <div class="docs-section">
-          {{outlet}}
+  {{#docs-snippet name='quickstart-skeleton' title='tests/dummy/app/pods/docs/template.hbs'}}
+    {{#docs-viewer as |viewer|}}
+      {{#viewer.nav as |nav|}}
+        {{nav.item 'Overview' 'docs.index'}}
+      {{/viewer.nav}}
+
+      {{#viewer.main}}
+        <div class="docs-container docs__center">
+          <div class="docs-section">
+            {{outlet}}
+          </div>
         </div>
-      </div>
-    {{/viewer.main}}
-
-  {{/docs-viewer}}
-  ```
+      {{/viewer.main}}
+    {{/docs-viewer}}
+  {{/docs-snippet}}
 
 5. **Fill out the index of your docs page.** We called it Overview but you can call it whatever you want. Since Addon Docs supports markdown templates out of the box, we can make this a Markdown file.
 
-  ```md
-  <!-- tests/dummy/app/templates/docs/index.md -->
-  # Overview
+  {{#docs-snippet name='quickstart-markdown' title='tests/dummy/app/templates/docs/index.md' language='markdown'}}
+    # Overview
 
-  This is my new addon, and it rocks!
-  ```
+    This is my new addon, and it rocks!
+  {{/docs-snippet}}
 
 6. **Add a 404 route.** Add a route to the end of your router and create an associated template.
 
-  ```js
-  // tests/dummy/app/router.js
-  this.route('not-found', { path: '/*path' });
-  ```
+  {{#docs-snippet name='quickstart-404-route' title='tests/dummy/app/router.js'}}
+    this.route('not-found', { path: '/*path' });
+  {{/docs-snippet}}
 
   <br />
 
-  ```hbs
-  {{! tests/dummy/app/templates/not-found.hbs  }}
-  <div class="docs-container">
-    <h1>Not found</h1>
-    <p>This page doesn't exist. {{#link-to 'index'}}Head home?{{/link-to}}</p>
-  </div>
-  ```
+  {{#docs-snippet name='quickstart-404-template' title='tests/dummy/app/templates/not-found.hbs'}}
+    <div class="docs-container">
+      <h1>Not found</h1>
+      <p>This page doesn't exist. {{#link-to 'index'}}Head home?{{/link-to}}</p>
+    </div>
+  {{/docs-snippet}}
+
 8. **Add more docs pages.** It's up to you how to structure your docs - use the Snippet, Viewer and Demo components to help you write your documentation. Let's add another page to ours: we'll add the route, link to our docs viewer, and the actual template.
 
-  ```js
-  // tests/dummy/app/router.js
-  this.route('docs', function() {
-    this.route('installation');
-  });
-  ```
+  {{#docs-snippet name='quickstart-more-docs' title='tests/dummy/app/router.js'}}
+    this.route('docs', function() {
+      this.route('installation');
+    });
+  {{/docs-snippet}}
 
   <br />
 
-  ```hbs
-  {{! tests/dummy/app/templates/docs.hbs }}
-  {{#viewer.nav as |nav|}}
-    {{nav.item 'Installation' 'docs.installation'}}
-  {{/viewer.nav}}
-  ```
+  {{#docs-snippet name='quickstart-more-nav' title='tests/dummy/app/templates/docs.hbs'}}
+    {{#viewer.nav as |nav|}}
+      {{nav.item 'Installation' 'docs.installation'}}
+    {{/viewer.nav}}
+  {{/docs-snippet}}
 
   <br />
 
-  ```md
-  <!-- tests/dummy/app/templates/docs/installation.md -->
-  # Installation
+  {{#docs-snippet name='quickstart-installation-readme' title='tests/dummy/app/templates/docs/installation.md'}}
+    # Installation
 
-  To install My Addon, run...
-  ```
+    To install My Addon, run...
+  {{/docs-snippet}}
 
 8. **Round out your site.**
   - **Add a favicon.** We recommend using [Ember CLI Favicon]( https://github.com/davewasmer/ember-cli-favicon).