Load makdrown partials with @load (#197)

* feat: introduced load tag to load external markdown file

fixtures/examples/class-with-load.js

@@ -0,0 +1,17 @@
+/**
+ * Class with load feature
+ *
+ * @load ./docs/description.md
+ */
+class ClassWithLoad {
+  /**
+   * Save method
+   *
+   * @load ./docs/save.md
+   */
+  save() {
+
+  }
+}
+
+export default ClassWithLoad

jsdoc.json

@@ -3,13 +3,17 @@
         "allowUnknownTags": "all"
     },
     "source": {
-        "include": ["fixtures/typescript"],
+        "include": [
+            "fixtures/typescript",
+            "fixtures/examples"
+        ],
         "includePattern": "\\.(jsx|js|ts|tsx)$"
     },
     "plugins": [
         "plugins/markdown",
         "category",
         "component",
+        "load",
         "typescript"
     ],
     "opts": {

lib/load/fill-component-preview.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fillComponentPreview = void 0;
+const regex = /^```reactComponent[\r\n]+(.*?)[\r\n]+```$/gms;
+const fillComponentPreview = (text, mdParser) => {
+    let number = 0;
+    const components = {};
+    const result = text.replace(regex, (match, group) => {
+        const uniqId = ['BetterDocsPreviewComponent', number += 1].join('');
+        components[uniqId] = `
+      <div id="${uniqId}"></div>
+
+      <script>
+        ReactDOM.render(ReactWrapper({
+          example: ${JSON.stringify(group)},
+          uniqId: ${JSON.stringify(uniqId)},
+        }), document.getElementById('${uniqId}'));
+      </script>
+    `;
+        return uniqId;
+    });
+    let markdown = mdParser(result);
+    Object.keys(components).forEach((componentId) => {
+        markdown = markdown.replace(componentId, components[componentId]);
+    });
+    return markdown;
+};
+exports.fillComponentPreview = fillComponentPreview;

lib/load/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.load = void 0;
+/* eslint-disable @typescript-eslint/no-var-requires */
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const fill_component_preview_1 = require("./fill-component-preview");
+const { getParser } = require('../../node_modules/jsdoc/lib/jsdoc/util/markdown');
+const markdownParser = getParser();
+const mdParser = (content) => {
+    const text = markdownParser(content);
+    return text;
+};
+const load = (loadTag, docletFilePath) => {
+    const filename = loadTag.value;
+    const filePath = path_1.default.join(docletFilePath, filename);
+    const body = fs_1.default.readFileSync(filePath, 'utf-8');
+    return (0, fill_component_preview_1.fillComponentPreview)(body, mdParser);
+};
+exports.load = load;

load.js

@@ -0,0 +1,20 @@
+/* eslint-disable no-param-reassign */
+const { load } = require('./lib/load')
+
+exports.defineTags = (dictionary) => {
+  dictionary.defineTag('load', {
+    /**
+     * @param {import('./src/jsdoc.type').DocLet} doclet
+     * @param {import('./src/jsdoc.type').JSDocTag} tag
+     */
+    onTagged: (doclet, tag) => {
+      const text = load(tag, doclet.meta.path)
+
+      if (doclet.classdesc) {
+        doclet.classdesc = [doclet.classdesc, text].join('\n')
+      } else if (doclet.description) {
+        doclet.description = [doclet.description, text].join('\n')
+      }
+    },
+  })
+}