@docfy/ember 0.4.8 → 0.6.0

package/.docfy-config.js

@@ -31,6 +31,7 @@ module.exports = {
   ],
   labels: {
     components: 'Components',
+    plugins: 'Plugins',
     helpers: 'Helpers',
     core: '@docfy/core',
     ember: '@docfy/ember',

package/docs/writing-demos.md

@@ -22,7 +22,7 @@ Below you can see how a demo markdown file looks like.
 
 ```
 
-The demo will be injected into the owner file as a new section called "Examples";
+The demo will be inserted into the owner file as a new section called "Examples";
 you can see it below.
 
 Please note that you must pass a metadata to the code block, it can be seen
@@ -57,3 +57,53 @@ And here you can see how it looks like when rendered:
 ```hbs preview-template
 Click in the link to navigate to the home page: <DocfyLink @to="/">Home</DocfyLink>
 ```
+
+## Manual Insertion
+
+To make getting started with Docfy as simple as possible, by default demos will
+be automatically inserted into the owner file under a new section called
+"Examples" before the second heading of the page.
+
+If you want more control over how demos are inserted into the page, you can
+declare `manualDemoInsertion` in a markdown page's frontmatter.
+
+```
+---
+title: Document with many examples
+manualDemoInsertion: true
+---
+```
+
+When a page is using `manualDemoInsertion`, by default no demos are inserted
+into the page. Instead, you must provide markers in your markdown that will be
+replaced. They follow the form `[[demo:name-of-demo]]`.
+
+```md
+# Title here
+
+The demo will be inserted after this line.
+
+[[demo:demo1]]
+
+And the prose of the document will continue exactly how the author wishes.
+```
+
+Sometimes as an author, you want control over where in the page demos will be
+inserted, but you don't need to control this location demo by demo. As a
+shorthand, you can provide the `[[demos-all]]` marker to insert all demos.
+
+```md
+# Title here
+
+All demos go here.
+
+[[demos-all]]
+
+Below is the equivalent if you had to mark all demos individually.
+
+[[demo:demo1]]
+
+[[demo:demo2]]
+
+[[demo:demo3]]
+```

package/dummy-docs/packages/ember/plugins/manual-demo-insertion-demo/tomster.md

@@ -0,0 +1,15 @@
+# Tomster
+
+Lovable hamster
+
+```hbs template
+<div data-test-id="tomster">
+  {{#let (array 1 2 3 4 5) as |numbers|}}
+    <ol>
+      {{#each numbers as |number|}}
+        <li>Here is number {{number}}</li>
+      {{/each}}
+    </ol>
+  {{/let}}
+</div>
+```

package/dummy-docs/packages/ember/plugins/manual-demo-insertion-demo/zoey.md

@@ -0,0 +1,9 @@
+# Zoey
+
+Tomster's sister (also a lovable hamster).
+
+```hbs template
+<div data-test-id="zoey">
+  Ember is <em>so</em> {{concat 'g' 'r' 'e' 'a' 't'}}!
+</div>
+```

package/dummy-docs/packages/ember/plugins/manual-demo-insertion.md

@@ -0,0 +1,31 @@
+---
+category: ember
+subcategory: plugins
+manualDemoInsertion: true
+---
+
+# Manual Demo Insertion
+
+Docfy will automatically insert demos for a page into the page at build time. However, this convenience comes at the cost of choosing where the demos should be rendered.
+
+If you want control over where demos are rendered in a page, add `manualDemoInsertion: true` to your page's frontmatter. Then you can use `[[demo:name]]` or `[[demos-all]]` to mark where a specific demo or all demos should be rendered.
+
+These markers must be on their own line!
+
+## It works like this
+
+Here is the tomster demo
+
+[[demo:tomster]]
+
+And here is the zoey demo
+
+[[demo:zoey]]
+
+## Or you can add all demos
+
+[[demos-all]]
+
+## Conclusion
+
+With Docfy you get demos added to your pages for free, but with a little more work you can also get a bit more control.

package/helpers/docfy-eq.d.ts

@@ -1,3 +1,7 @@
 export declare function docfyEq(params: unknown[]): boolean;
-declare const _default: any;
+declare const _default: import("@ember/component/helper").FunctionBasedHelper<{
+    PositionalArgs: unknown[];
+    NamedArgs: Record<string, unknown>;
+    Return: boolean;
+}>;
 export default _default;

package/lib/index.js

@@ -26,7 +26,7 @@ const get_config_1 = __importDefault(require("./get-config"));
 const utils_1 = require("./plugins/utils");
 const calculate_cache_key_for_tree_1 = __importDefault(require("calculate-cache-key-for-tree"));
 const debug_1 = __importDefault(require("debug"));
-const debug = debug_1.default('@docfy/ember');
+const debug = (0, debug_1.default)('@docfy/ember');
 const templateOnlyComponent = `
 import Component from '@glimmer/component';
 export default class extends Component {}
@@ -72,7 +72,7 @@ class DocfyBroccoli extends broccoli_plugin_1.default {
                 ensureDirectoryExistence(fileName);
                 fs_1.default.writeFileSync(fileName, page.rendered);
                 const demoComponents = page.pluginData.demoComponents;
-                if (utils_1.isDemoComponents(demoComponents)) {
+                if ((0, utils_1.isDemoComponents)(demoComponents)) {
                     demoComponents.forEach((component) => {
                         component.chunks.forEach((chunk) => {
                             const chunkPath = path_1.default.join(this.outputPath, 'components', `${component.name.dashCase}.${chunk.ext}`);
@@ -104,7 +104,7 @@ module.exports = {
     docfyConfig: undefined,
     included(...args) {
         if (!isDeepAddonInstance(this)) {
-            this.docfyConfig = get_config_1.default(this.project.root);
+            this.docfyConfig = (0, get_config_1.default)(this.project.root);
             this.bridge = new broccoli_bridge_1.default();
         }
         this._super.included.apply(this, args);
@@ -115,10 +115,10 @@ module.exports = {
         switch (treeType) {
             case 'app':
             case 'addon': {
-                return calculate_cache_key_for_tree_1.default(treeType, this, [this.docfyConfig]);
+                return (0, calculate_cache_key_for_tree_1.default)(treeType, this, [this.docfyConfig]);
             }
             default:
-                return calculate_cache_key_for_tree_1.default(treeType, this);
+                return (0, calculate_cache_key_for_tree_1.default)(treeType, this);
         }
     },
     treeForApp(tree) {
@@ -144,7 +144,7 @@ module.exports = {
         }
         const EmberApp = require('ember-cli/lib/broccoli/ember-app'); // eslint-disable-line
         const modulePrefix = this.project.config(EmberApp.env()).modulePrefix;
-        trees.push(new broccoli_file_creator_1.default('output.js', docfy_output_template_1.default(modulePrefix)));
+        trees.push(new broccoli_file_creator_1.default('output.js', (0, docfy_output_template_1.default)(modulePrefix)));
         return new broccoli_merge_trees_1.default(trees);
     },
     treeForPublic() {

package/lib/plugins/extract-demos-to-components.js

@@ -18,17 +18,24 @@ const path_1 = __importDefault(require("path"));
  * This is necessary for apps using remark-autolink-headings, for example.
  */
 function createHeading(ctx) {
-    const heading = ctx.remark.runSync(ctx.remark.parse('## Examples'))
-        .children[0];
+    const heading = ctx.remark.runSync(ctx.remark.parse('## Examples')).children[0];
     heading.depth = 2;
     return heading;
 }
+const isTextMarker = (node) => node.type === 'paragraph' &&
+    node.children.length === 1 &&
+    node.children[0].type === 'text';
+const demoMarkerRegex = /^\[\[demo:(.+?)\]\]$/;
+const demoMarker = (node) => isTextMarker(node) && demoMarkerRegex.test(node.children[0].value);
+const demosAllMarkerRegex = /^\[\[demos-all\]\]$/;
+const demosAllMarker = (node) => isTextMarker(node) &&
+    demosAllMarkerRegex.test(node.children[0].value);
 /*
  * Insert Demo nodes into the page.
  */
 function insertDemoNodesIntoPage(page, toInsert) {
     if (Array.isArray(page.ast.children)) {
-        const secondHeading = unist_util_find_1.default(page.ast, (node) => node.type === 'heading' && node.depth !== 1);
+        const secondHeading = (0, unist_util_find_1.default)(page.ast, (node) => node.type === 'heading' && node.depth !== 1);
         if (secondHeading) {
             const index = page.ast.children.findIndex((el) => el === secondHeading);
             page.ast.children.splice(index, 0, ...toInsert);
@@ -38,7 +45,43 @@ function insertDemoNodesIntoPage(page, toInsert) {
         }
     }
 }
-exports.default = plugin_1.default({
+function replaceDemoMarkers(page, demos) {
+    if (Array.isArray(page.ast.children)) {
+        const markers = [];
+        const allMarkers = [];
+        (0, unist_util_visit_1.default)(page.ast, 'paragraph', (node) => {
+            if (demoMarker(node))
+                markers.push(node);
+            if (demosAllMarker(node))
+                allMarkers.push(node);
+        });
+        markers.forEach((marker) => {
+            const child = marker.children[0];
+            const matches = child.value.match(demoMarkerRegex);
+            if (!matches)
+                return;
+            // TODO: This is an inner loop and can cause perf issues if someone
+            // out there has many demos on a single page. It would be better to
+            // create a demo component hash that can be looked up by demo name.
+            const demoName = matches[1];
+            const demo = demos.find((d) => d.name.dashCase.endsWith(demoName));
+            if (!demo) {
+                console.warn(`Found demo marker "${demoName}" with no matching demo component in ${page.source}`);
+                return;
+            }
+            marker.type = 'div';
+            marker.children.splice(0, 1, ...(0, utils_1.createDemoNodes)(demo));
+        });
+        allMarkers.forEach((marker) => {
+            const demoNodes = demos
+                .map((component) => (0, utils_1.createDemoNodes)(component))
+                .flat();
+            marker.type = 'div';
+            marker.children.splice(0, 1, ...demoNodes);
+        });
+    }
+}
+exports.default = (0, plugin_1.default)({
     runWithMdast(ctx) {
         const seenNames = new Set();
         ctx.pages.forEach((page) => {
@@ -46,12 +89,12 @@ exports.default = plugin_1.default({
                 const demoComponents = [];
                 page.demos.forEach((demo) => {
                     const chunks = [];
-                    unist_util_visit_1.default(demo.ast, 'code', (node) => {
+                    (0, unist_util_visit_1.default)(demo.ast, 'code', (node) => {
                         if (['component', 'template', 'styles'].includes(node.meta || '')) {
                             chunks.push({
                                 snippet: node,
                                 code: node.value.replace(/\\{{/g, '{{'),
-                                ext: utils_1.getExt(node.lang || (node.meta === 'template' ? 'hbs' : 'js')),
+                                ext: (0, utils_1.getExt)(node.lang || (node.meta === 'template' ? 'hbs' : 'js')),
                                 type: node.meta
                             });
                         }
@@ -59,8 +102,8 @@ exports.default = plugin_1.default({
                     // 1. exclude extension
                     // 2. remove /index.md because of web conventions
                     const baseName = page.source.replace('/index.md', '').split('.')[0];
-                    const componentName = utils_1.generateDemoComponentName(`docfy-demo-${baseName}-${path_1.default.basename(demo.source).split('.')[0]}`, seenNames);
-                    const demoTitle = unist_util_find_1.default(demo.ast, (node) => node.type === 'heading' && node.depth === 1);
+                    const componentName = (0, utils_1.generateDemoComponentName)(`docfy-demo-${baseName}-${path_1.default.basename(demo.source).split('.')[0]}`, seenNames);
+                    const demoTitle = (0, unist_util_find_1.default)(demo.ast, (node) => node.type === 'heading' && node.depth === 1);
                     if (demoTitle) {
                         demoTitle.depth = 3;
                         demoTitle.data = Object.assign(Object.assign({}, (demoTitle.data || {})), { id: componentName.dashCase, docfyDelete: true // mark the heading to be deleted by @docfy/core TOC plugin
@@ -70,22 +113,31 @@ exports.default = plugin_1.default({
                         name: componentName,
                         chunks,
                         description: {
-                            title: demoTitle ? mdast_util_to_string_1.default(demoTitle) : undefined,
+                            title: demoTitle ? (0, mdast_util_to_string_1.default)(demoTitle) : undefined,
                             ast: demo.ast,
                             editUrl: demo.meta.editUrl
                         }
                     });
                     // Delete used code blocks
                     chunks.forEach(({ snippet }) => {
-                        utils_1.deleteNode(demo.ast.children, snippet);
+                        (0, utils_1.deleteNode)(demo.ast.children, snippet);
                     });
                 });
-                const toInsert = [createHeading(ctx)];
-                demoComponents.forEach((component) => {
-                    toInsert.push(...utils_1.createDemoNodes(component));
-                });
-                insertDemoNodesIntoPage(page, toInsert);
-                if (utils_1.isDemoComponents(page.pluginData.demoComponents)) {
+                if (page.meta.frontmatter.manualDemoInsertion) {
+                    // Manual demo insertion inserts demos into markdown files
+                    // wherever there is a demo marker ([[demo:name]] or [[demos-all]])
+                    replaceDemoMarkers(page, demoComponents);
+                }
+                else {
+                    // Automatic demo insertion creates an Example block after
+                    // the first heading.
+                    const toInsert = [createHeading(ctx)];
+                    demoComponents.forEach((component) => {
+                        toInsert.push(...(0, utils_1.createDemoNodes)(component));
+                    });
+                    insertDemoNodesIntoPage(page, toInsert);
+                }
+                if ((0, utils_1.isDemoComponents)(page.pluginData.demoComponents)) {
                     page.pluginData.demoComponents.push(...demoComponents);
                 }
                 else {

package/lib/plugins/preview-template.js

@@ -7,20 +7,20 @@ const unist_util_visit_1 = __importDefault(require("unist-util-visit"));
 const plugin_1 = __importDefault(require("@docfy/core/lib/plugin"));
 const utils_1 = require("./utils");
 const path_1 = __importDefault(require("path"));
-exports.default = plugin_1.default({
+exports.default = (0, plugin_1.default)({
     runWithMdast(ctx) {
         const seenNames = new Set();
         ctx.pages.forEach((page) => {
             const demoComponents = [];
-            unist_util_visit_1.default(page.ast, 'code', (node) => {
+            (0, unist_util_visit_1.default)(page.ast, 'code', (node) => {
                 if (['preview-template'].includes(node.meta || '')) {
                     demoComponents.push({
-                        name: utils_1.generateDemoComponentName(`docfy-demo-preview-${path_1.default.basename(page.meta.url)}`, seenNames),
+                        name: (0, utils_1.generateDemoComponentName)(`docfy-demo-preview-${path_1.default.basename(page.meta.url)}`, seenNames),
                         chunks: [
                             {
                                 snippet: node,
                                 code: node.value.replace(/\\{{/g, '{{'),
-                                ext: utils_1.getExt(node.lang || 'hbs'),
+                                ext: (0, utils_1.getExt)(node.lang || 'hbs'),
                                 type: node.meta
                             }
                         ]
@@ -28,9 +28,9 @@ exports.default = plugin_1.default({
                 }
             });
             demoComponents.forEach((demoComponent) => {
-                utils_1.replaceNode(page.ast.children, demoComponent.chunks[0].snippet, ...utils_1.createDemoNodes(demoComponent));
+                (0, utils_1.replaceNode)(page.ast.children, demoComponent.chunks[0].snippet, ...(0, utils_1.createDemoNodes)(demoComponent));
             });
-            if (utils_1.isDemoComponents(page.pluginData.demoComponents)) {
+            if ((0, utils_1.isDemoComponents)(page.pluginData.demoComponents)) {
                 page.pluginData.demoComponents.push(...demoComponents);
             }
             else {

package/lib/plugins/replace-internal-links-with-docfy-link.js

@@ -7,7 +7,7 @@ const plugin_1 = __importDefault(require("@docfy/core/lib/plugin"));
 const unist_util_visit_1 = __importDefault(require("unist-util-visit"));
 const unist_builder_1 = __importDefault(require("unist-builder"));
 function visitor(page) {
-    unist_util_visit_1.default(page.ast, 'link', (node, index, parent) => {
+    (0, unist_util_visit_1.default)(page.ast, 'link', (node, index, parent) => {
         if (node.url[0] === '/') {
             const data = node.data || (node.data = {});
             const props = (data.hProperties || (data.hProperties = {}));
@@ -18,9 +18,9 @@ function visitor(page) {
             })
                 .join(' ');
             const toInsert = [
-                unist_builder_1.default('html', `<DocfyLink @to="${urlParts[0]}" ${urlParts[1] ? `@anchor="${urlParts[1]}"` : ''} ${attributes}>`),
+                (0, unist_builder_1.default)('html', `<DocfyLink @to="${urlParts[0]}" ${urlParts[1] ? `@anchor="${urlParts[1]}"` : ''} ${attributes}>`),
                 ...node.children,
-                unist_builder_1.default('html', `</DocfyLink>`)
+                (0, unist_builder_1.default)('html', `</DocfyLink>`)
             ];
             parent === null || parent === void 0 ? void 0 : parent.children.splice(index, 1, ...toInsert);
         }
@@ -30,7 +30,7 @@ function visitor(page) {
  * This function finds all the links starting with an `/` and replace them with
  * the `DocfyLink` component.
  */
-exports.default = plugin_1.default({
+exports.default = (0, plugin_1.default)({
     runWithMdast(ctx) {
         ctx.pages.forEach((page) => {
             visitor(page);

package/lib/plugins/utils.js

@@ -27,30 +27,30 @@ const unist_builder_1 = __importDefault(require("unist-builder"));
  */
 function createDemoNodes(component) {
     const nodes = [
-        unist_builder_1.default('html', `<DocfyDemo @id="${component.name.dashCase}" as |demo|>`)
+        (0, unist_builder_1.default)('html', `<DocfyDemo @id="${component.name.dashCase}" as |demo|>`)
     ];
     if (component.description) {
-        nodes.push(unist_builder_1.default('html', `<demo.Description
+        nodes.push((0, unist_builder_1.default)('html', `<demo.Description
           ${component.description.title
             ? `@title="${component.description.title}" `
             : ''}${component.description.editUrl
             ? `@editUrl="${component.description.editUrl}"`
-            : ''}>`), component.description.ast, unist_builder_1.default('html', '</demo.Description>'));
+            : ''}>`), component.description.ast, (0, unist_builder_1.default)('html', '</demo.Description>'));
     }
-    nodes.push(unist_builder_1.default('html', '<demo.Example>'), unist_builder_1.default('html', `<${component.name.pascalCase} />`), unist_builder_1.default('html', '</demo.Example>'));
+    nodes.push((0, unist_builder_1.default)('html', '<demo.Example>'), (0, unist_builder_1.default)('html', `<${component.name.pascalCase} />`), (0, unist_builder_1.default)('html', '</demo.Example>'));
     if (component.chunks.length > 1) {
-        nodes.push(unist_builder_1.default('html', '<demo.Snippets as |Snippet|>'));
+        nodes.push((0, unist_builder_1.default)('html', '<demo.Snippets as |Snippet|>'));
         component.chunks.forEach((chunk) => {
-            nodes.push(unist_builder_1.default('html', `<Snippet @name="${chunk.type}">`), chunk.snippet, unist_builder_1.default('html', '</Snippet>'));
+            nodes.push((0, unist_builder_1.default)('html', `<Snippet @name="${chunk.type}">`), chunk.snippet, (0, unist_builder_1.default)('html', '</Snippet>'));
         });
-        nodes.push(unist_builder_1.default('html', '</demo.Snippets>'));
+        nodes.push((0, unist_builder_1.default)('html', '</demo.Snippets>'));
     }
     else {
         component.chunks.forEach((chunk) => {
-            nodes.push(unist_builder_1.default('html', `<demo.Snippet @name="${chunk.type}">`), chunk.snippet, unist_builder_1.default('html', '</demo.Snippet>'));
+            nodes.push((0, unist_builder_1.default)('html', `<demo.Snippet @name="${chunk.type}">`), chunk.snippet, (0, unist_builder_1.default)('html', '</demo.Snippet>'));
         });
     }
-    nodes.push(unist_builder_1.default('html', '</DocfyDemo>'));
+    nodes.push((0, unist_builder_1.default)('html', '</DocfyDemo>'));
     return nodes;
 }
 exports.createDemoNodes = createDemoNodes;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docfy/ember",
-  "version": "0.4.8",
+  "version": "0.6.0",
   "description": "Ember integration with Docfy",
   "keywords": [
     "ember-addon",
@@ -30,81 +30,94 @@
     "test:ember-compatibility": "echo 'ember try:each TODO'"
   },
   "dependencies": {
-    "@docfy/core": "^0.4.4",
+    "@docfy/core": "^0.6.0",
     "broccoli-bridge": "^1.0.0",
     "broccoli-file-creator": "^2.1.1",
-    "broccoli-funnel": "^3.0.3",
+    "broccoli-funnel": "^3.0.8",
     "broccoli-merge-trees": "^4.2.0",
     "broccoli-node-api": "^1.7.0",
-    "broccoli-plugin": "^4.0.3",
-    "broccoli-source": "^3.0.0",
+    "broccoli-plugin": "^4.0.7",
+    "broccoli-source": "^3.0.1",
     "calculate-cache-key-for-tree": "2.0.0",
-    "debug": "^4.3.1",
-    "ember-cli-babel": "^7.23.1",
-    "ember-cli-htmlbars": "^5.3.1",
-    "ember-cli-typescript": "^4.0.0",
-    "ember-get-config": "^0.3.0",
+    "debug": "^4.3.3",
+    "ember-cli-babel": "^7.26.11",
+    "ember-cli-htmlbars": "^6.0.1",
+    "ember-cli-typescript": "^4.2.1",
+    "ember-get-config": "^1.0.2",
     "mdast-util-to-string": "^2.0.0",
-    "remark-hbs": "^0.4.0",
+    "remark-hbs": "^0.4.1",
     "unist-builder": "^2.0.3",
     "unist-util-find": "^1.0.2",
     "unist-util-visit": "^2.0.2"
   },
   "devDependencies": {
-    "@docfy/plugin-with-prose": "^0.4.4",
+    "@babel/helper-define-map": "^7.16.7",
+    "@docfy/plugin-with-prose": "^0.6.0",
     "@ember/optional-features": "^2.0.0",
-    "@ember/test-helpers": "^2.1.4",
-    "@embroider/compat": "^0.36.0",
-    "@embroider/core": "^0.36.0",
-    "@embroider/webpack": "^0.36.0",
-    "@glimmer/component": "^1.0.3",
-    "@glimmer/tracking": "^1.0.3",
+    "@ember/test-helpers": "^2.6.0",
+    "@embroider/compat": "^1.0.0",
+    "@embroider/core": "^1.0.0",
+    "@embroider/webpack": "^1.0.0",
+    "@glimmer/component": "^1.0.4",
+    "@glimmer/tracking": "^1.0.4",
     "@mapbox/rehype-prism": "^0.5.0",
     "@tailwindcss/typography": "^0.4.0",
-    "@types/debug": "^4.1.5",
-    "@types/ember": "^3.16.3",
-    "@types/ember-qunit": "^3.4.13",
-    "@types/ember__test-helpers": "^1.7.3",
-    "@types/jest": "^26.0.20",
-    "@types/qunit": "^2.11.1",
-    "@types/rsvp": "^4.0.3",
+    "@types/ember-qunit": "^5.0.0",
+    "@types/ember-resolver": "^5.0.11",
+    "@types/ember__application": "^4.0.0",
+    "@types/ember__array": "^4.0.1",
+    "@types/ember__component": "^4.0.1",
+    "@types/ember__debug": "^4.0.0",
+    "@types/ember__error": "^4.0.0",
+    "@types/ember__object": "^4.0.0",
+    "@types/ember__routing": "^4.0.2",
+    "@types/ember__runloop": "^4.0.0",
+    "@types/ember__service": "^4.0.0",
+    "@types/ember__string": "^3.0.9",
+    "@types/ember__template": "^4.0.0",
+    "@types/ember__test": "^4.0.0",
+    "@types/ember__test-helpers": "^2.6.1",
+    "@types/htmlbars-inline-precompile": "^3.0.0",
+    "@types/qunit": "^2.11.3",
+    "@types/rsvp": "^4.0.4",
     "@types/sinon": "^9.0.10",
-    "autoprefixer": "^10.2.4",
+    "autoprefixer": "^10.4.2",
     "broccoli-asset-rev": "^3.0.0",
-    "ember-auto-import": "^1.10.1",
-    "ember-cli": "~3.24.0",
+    "ember-auto-import": "^2.4.0",
+    "ember-cli": "~4.1.1",
     "ember-cli-dependency-checker": "^3.2.0",
-    "ember-cli-fastboot": "^2.2.3",
-    "ember-cli-fastboot-testing": "^0.4.0",
-    "ember-cli-inject-live-reload": "^2.0.2",
-    "ember-cli-postcss": "^7.0.0",
+    "ember-cli-fastboot": "^3.2.0-beta.5",
+    "ember-cli-fastboot-testing": "^0.6.0",
+    "ember-cli-inject-live-reload": "^2.1.0",
+    "ember-cli-postcss": "^8.0.0",
     "ember-cli-sri": "^2.1.1",
     "ember-cli-typescript-blueprints": "^3.0.0",
     "ember-cli-uglify": "^3.0.0",
     "ember-disable-prototype-extensions": "^1.1.3",
     "ember-export-application-global": "^2.0.1",
     "ember-load-initializers": "^2.1.2",
-    "ember-maybe-import-regenerator": "^0.1.6",
-    "ember-qunit": "^5.1.1",
-    "ember-resolver": "^8.0.2",
+    "ember-maybe-import-regenerator": "^1.0.0",
+    "ember-qunit": "^5.1.5",
+    "ember-resolver": "^8.0.3",
     "ember-router-helpers": "^0.4.0",
     "ember-sinon": "^5.0.0",
-    "ember-source": "~3.24.1",
+    "ember-source": "~4.1.0",
     "ember-source-channel-url": "^3.0.0",
     "ember-template-lint": "^2.18.0",
-    "ember-try": "^1.4.0",
+    "ember-try": "^2.0.0",
     "loader.js": "^4.7.0",
     "npm-run-all": "^4.1.5",
-    "postcss-import": "^14.0.0",
-    "postcss-nested": "^5.0.3",
-    "prember": "^1.0.5",
-    "qunit": "^2.14.0",
-    "qunit-dom": "^1.6.0",
-    "refractor": "^3.3.1",
+    "postcss-import": "^14.0.2",
+    "postcss-nested": "^5.0.6",
+    "prember": "^1.1.0",
+    "qunit": "^2.17.2",
+    "qunit-dom": "^2.0.0",
+    "refractor": "^3.0.0",
     "remark-autolink-headings": "^6.0.0",
     "remark-code-import": "^0.2.0",
     "tailwindcss": "^2.0.2",
-    "typescript": "^4.1.3"
+    "typescript": "^4.1.3",
+    "webpack": "^5.67.0"
   },
   "engines": {
     "node": ">= 12"
@@ -122,5 +135,5 @@
       "prember"
     ]
   },
-  "gitHead": "367f4946c144db8c5ef4e03fe44ba7450c89849e"
+  "gitHead": "3745bd3c8c45202a0c11d8fd502b52a5e3f62493"
 }

package/src/plugins/extract-demos-to-components.ts

@@ -1,7 +1,7 @@
 import visit from 'unist-util-visit';
 import { Context, PageContent } from '@docfy/core/lib/types';
 import plugin from '@docfy/core/lib/plugin';
-import { Node } from 'unist';
+import { Node, Parent } from 'unist';
 import findNode from 'unist-util-find';
 import toString from 'mdast-util-to-string';
 import { DemoComponent, DemoComponentChunk, CodeNode } from './types';
@@ -23,12 +23,27 @@ import path from 'path';
  * This is necessary for apps using remark-autolink-headings, for example.
  */
 function createHeading(ctx: Context): Node {
-  const heading = (ctx.remark.runSync(ctx.remark.parse('## Examples'))
-    .children as Node[])[0];
+  const heading = (
+    ctx.remark.runSync(ctx.remark.parse('## Examples')).children as Node[]
+  )[0];
   heading.depth = 2;
   return heading;
 }
 
+const isTextMarker = (node: Parent): boolean =>
+  node.type === 'paragraph' &&
+  node.children.length === 1 &&
+  node.children[0].type === 'text';
+
+const demoMarkerRegex = /^\[\[demo:(.+?)\]\]$/;
+const demoMarker = (node: Parent): boolean =>
+  isTextMarker(node) && demoMarkerRegex.test(node.children[0].value as string);
+
+const demosAllMarkerRegex = /^\[\[demos-all\]\]$/;
+const demosAllMarker = (node: Parent): boolean =>
+  isTextMarker(node) &&
+  demosAllMarkerRegex.test(node.children[0].value as string);
+
 /*
  * Insert Demo nodes into the page.
  */
@@ -48,6 +63,49 @@ function insertDemoNodesIntoPage(page: PageContent, toInsert: Node[]): void {
   }
 }
 
+function replaceDemoMarkers(page: PageContent, demos: DemoComponent[]): void {
+  if (Array.isArray(page.ast.children)) {
+    const markers: Parent[] = [];
+    const allMarkers: Parent[] = [];
+
+    visit(page.ast, 'paragraph', (node: Parent) => {
+      if (demoMarker(node)) markers.push(node);
+      if (demosAllMarker(node)) allMarkers.push(node);
+    });
+
+    markers.forEach((marker) => {
+      const child = marker.children[0];
+      const matches = (child.value as string).match(demoMarkerRegex);
+      if (!matches) return;
+
+      // TODO: This is an inner loop and can cause perf issues if someone
+      // out there has many demos on a single page. It would be better to
+      // create a demo component hash that can be looked up by demo name.
+      const demoName = matches[1];
+      const demo = demos.find((d) => d.name.dashCase.endsWith(demoName));
+
+      if (!demo) {
+        console.warn(
+          `Found demo marker "${demoName}" with no matching demo component in ${page.source}`
+        );
+        return;
+      }
+
+      marker.type = 'div';
+      marker.children.splice(0, 1, ...createDemoNodes(demo));
+    });
+
+    allMarkers.forEach((marker) => {
+      const demoNodes = demos
+        .map((component) => createDemoNodes(component))
+        .flat();
+
+      marker.type = 'div';
+      marker.children.splice(0, 1, ...demoNodes);
+    });
+  }
+}
+
 export default plugin({
   runWithMdast(ctx: Context): void {
     const seenNames: Set<string> = new Set();
@@ -113,11 +171,19 @@ export default plugin({
           });
         });
 
-        const toInsert: Node[] = [createHeading(ctx)];
-        demoComponents.forEach((component) => {
-          toInsert.push(...createDemoNodes(component));
-        });
-        insertDemoNodesIntoPage(page, toInsert);
+        if (page.meta.frontmatter.manualDemoInsertion) {
+          // Manual demo insertion inserts demos into markdown files
+          // wherever there is a demo marker ([[demo:name]] or [[demos-all]])
+          replaceDemoMarkers(page, demoComponents);
+        } else {
+          // Automatic demo insertion creates an Example block after
+          // the first heading.
+          const toInsert: Node[] = [createHeading(ctx)];
+          demoComponents.forEach((component) => {
+            toInsert.push(...createDemoNodes(component));
+          });
+          insertDemoNodesIntoPage(page, toInsert);
+        }
 
         if (isDemoComponents(page.pluginData.demoComponents)) {
           page.pluginData.demoComponents.push(...demoComponents);

package/tsconfig.json

@@ -9,6 +9,7 @@
     "alwaysStrict": true,
     "strictNullChecks": true,
     "strictPropertyInitialization": true,
+    "skipLibCheck": true,
     "noFallthroughCasesInSwitch": true,
     "noUnusedLocals": true,
     "noUnusedParameters": true,