@docfy/ember 0.5.0 → 0.7.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/components/docfy-output-demo/edit-page.md

@@ -20,3 +20,35 @@ repository URL as well as the branch to edit.
   {{/if}}
 </DocfyOutput>
 ```
+
+For this to work, you need to include `repository` in your docfy-config:
+
+```js
+// in your docfy-config.js
+module.exports = {
+  repository: {
+    url: 'https://github.com/@username/repo-name',
+    editBranch: 'main',
+  },
+  ...// rest of your config
+}
+```
+
+
+## Enterprise (aka on premise) git services
+
+`page.editUrl` works for Github, Bitbucket, Gitlab and Sourcehut.
+
+For on-premise instances git solutions (i.e. on-premise Gitlab, or on-premise Bitbucket), we expose the `page.relativePath` so that you might construct your own custom editUrl:
+
+```hbs 
+<DocfyOutput @fromCurrentURL={{true}} as |page|>
+  {{#if page.relativePath}}
+    <a href=(concat "http://some-enterpise.com/browse/" page.relativePath)
+      Click here to edit this page
+    </a>
+  {{/if}}
+</DocfyOutput>
+```
+
+Note: the edit url for your on-premise instance might be more complex than the example above. But the `page.relativePath` will give you the relative path to that file in your repo. 

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/lib/index.js

@@ -63,12 +63,16 @@ class DocfyBroccoli extends broccoli_plugin_1.default {
             debug('Config: ', this.config);
             const docfy = new core_1.default(this.config);
             const result = yield docfy.run(this.config.sources);
+            const snippets = {
+                components: {}
+            };
             result.content.forEach((page) => {
                 const parts = [this.outputPath, 'templates', page.meta.url];
                 if (page.meta.url[page.meta.url.length - 1] === '/') {
                     parts.push('index');
                 }
                 const fileName = `${path_1.default.join(...parts)}.hbs`;
+                // console.log(fileName, "RENDERED AS", page.rendered);
                 ensureDirectoryExistence(fileName);
                 fs_1.default.writeFileSync(fileName, page.rendered);
                 const demoComponents = page.pluginData.demoComponents;
@@ -77,11 +81,13 @@ class DocfyBroccoli extends broccoli_plugin_1.default {
                         component.chunks.forEach((chunk) => {
                             const chunkPath = path_1.default.join(this.outputPath, 'components', `${component.name.dashCase}.${chunk.ext}`);
                             ensureDirectoryExistence(chunkPath);
+                            snippets.components[`${component.name.dashCase}`] = Object.assign(Object.assign({}, (snippets.components[`${component.name.dashCase}`] || {})), { [chunk.ext]: chunk.code });
                             fs_1.default.writeFileSync(chunkPath, chunk.code);
                         });
                         if (!hasBackingJS(component.chunks)) {
                             const chunkPath = path_1.default.join(this.outputPath, 'components', `${component.name.dashCase}.js`);
                             ensureDirectoryExistence(chunkPath);
+                            snippets.components[`${component.name.dashCase}`] = Object.assign(Object.assign({}, (snippets.components[`${component.name.dashCase}`] || {})), { js: templateOnlyComponent });
                             fs_1.default.writeFileSync(chunkPath, templateOnlyComponent);
                         }
                     });
@@ -91,6 +97,9 @@ class DocfyBroccoli extends broccoli_plugin_1.default {
             const urlsJsonFile = path_1.default.join(this.outputPath, 'public', 'docfy-urls.json');
             ensureDirectoryExistence(urlsJsonFile);
             fs_1.default.writeFileSync(urlsJsonFile, JSON.stringify(result.content.map((page) => page.meta.url)));
+            const snippetsJsonFile = path_1.default.join(this.outputPath, 'public', 'docfy-snippets.json');
+            ensureDirectoryExistence(snippetsJsonFile);
+            fs_1.default.writeFileSync(snippetsJsonFile, JSON.stringify(snippets));
             result.staticAssets.forEach((asset) => {
                 const dest = path_1.default.join(this.outputPath, 'public', asset.toPath);
                 ensureDirectoryExistence(dest);

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

@@ -22,6 +22,14 @@ function createHeading(ctx) {
     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.
  */
@@ -37,6 +45,42 @@ function insertDemoNodesIntoPage(page, toInsert) {
         }
     }
 }
+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();
@@ -79,11 +123,20 @@ exports.default = (0, plugin_1.default)({
                         (0, utils_1.deleteNode)(demo.ast.children, snippet);
                     });
                 });
-                const toInsert = [createHeading(ctx)];
-                demoComponents.forEach((component) => {
-                    toInsert.push(...(0, utils_1.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 = [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);
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docfy/ember",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Ember integration with Docfy",
   "keywords": [
     "ember-addon",
@@ -30,7 +30,7 @@
     "test:ember-compatibility": "echo 'ember try:each TODO'"
   },
   "dependencies": {
-    "@docfy/core": "^0.5.0",
+    "@docfy/core": "^0.7.0",
     "broccoli-bridge": "^1.0.0",
     "broccoli-file-creator": "^2.1.1",
     "broccoli-funnel": "^3.0.8",
@@ -52,7 +52,7 @@
   },
   "devDependencies": {
     "@babel/helper-define-map": "^7.16.7",
-    "@docfy/plugin-with-prose": "^0.5.0",
+    "@docfy/plugin-with-prose": "^0.7.0",
     "@ember/optional-features": "^2.0.0",
     "@ember/test-helpers": "^2.6.0",
     "@embroider/compat": "^1.0.0",
@@ -135,5 +135,5 @@
       "prember"
     ]
   },
-  "gitHead": "660408a83302ec4dc727acc0339a506fe0316b54"
+  "gitHead": "d24cfd0a838a890c850d0030ec30856d0608267c"
 }

package/src/index.ts

@@ -60,7 +60,9 @@ class DocfyBroccoli extends Plugin {
     debug('Config: ', this.config);
     const docfy = new Docfy(this.config);
     const result = await docfy.run(this.config.sources as SourceConfig[]);
-
+    const snippets = {
+      components: {}
+    };
     result.content.forEach((page) => {
       const parts = [this.outputPath, 'templates', page.meta.url];
 
@@ -70,6 +72,7 @@ class DocfyBroccoli extends Plugin {
 
       const fileName = `${path.join(...parts)}.hbs`;
 
+      // console.log(fileName, "RENDERED AS", page.rendered);
       ensureDirectoryExistence(fileName);
       fs.writeFileSync(fileName, page.rendered);
 
@@ -83,6 +86,11 @@ class DocfyBroccoli extends Plugin {
               `${component.name.dashCase}.${chunk.ext}`
             );
             ensureDirectoryExistence(chunkPath);
+
+            snippets.components[`${component.name.dashCase}`] = {
+              ...(snippets.components[`${component.name.dashCase}`] || {}),
+              [chunk.ext]: chunk.code
+            };
             fs.writeFileSync(chunkPath, chunk.code);
           });
 
@@ -93,6 +101,10 @@ class DocfyBroccoli extends Plugin {
               `${component.name.dashCase}.js`
             );
             ensureDirectoryExistence(chunkPath);
+            snippets.components[`${component.name.dashCase}`] = {
+              ...(snippets.components[`${component.name.dashCase}`] || {}),
+              js: templateOnlyComponent
+            };
             fs.writeFileSync(chunkPath, templateOnlyComponent);
           }
         });
@@ -109,11 +121,19 @@ class DocfyBroccoli extends Plugin {
       'public',
       'docfy-urls.json'
     );
+
     ensureDirectoryExistence(urlsJsonFile);
     fs.writeFileSync(
       urlsJsonFile,
       JSON.stringify(result.content.map((page) => page.meta.url))
     );
+    const snippetsJsonFile = path.join(
+      this.outputPath,
+      'public',
+      'docfy-snippets.json'
+    );
+    ensureDirectoryExistence(snippetsJsonFile);
+    fs.writeFileSync(snippetsJsonFile, JSON.stringify(snippets));
     result.staticAssets.forEach((asset) => {
       const dest = path.join(this.outputPath, 'public', asset.toPath);
       ensureDirectoryExistence(dest);

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';
@@ -30,6 +30,20 @@ function createHeading(ctx: Context): Node {
   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.
  */
@@ -49,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();
@@ -114,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);