Feature: Add support for copying assets and replace img src with the …

…proper path in @webdoc/default-template (#170)

* Feature: Add support for copying assets and replace img src with the proper path in @webdoc/default-template

* Fix lint

packages/webdoc-cli/src/config.js

@@ -33,6 +33,7 @@ type ConfigSchema = {
     import?: string[],
   },
   template: {
+    assets: Array<string>,
     alias: {
       [string]: string;
     },
@@ -96,6 +97,7 @@ const defaultConfig: ConfigSchema = {
     template: "@webdoc/default-template",
   },
   template: {
+    assets: [],
     alias: {},
     appBar: {
       items: {},

packages/webdoc-default-template/helper/renderer-plugins/preprocess.js

@@ -0,0 +1,15 @@
+const path = require("path");
+
+// Regex for matching <img> element with a capturing group for src attribute
+const IMG_REGEX = /(<img [^<]*src=")([-\]_.~!*'();:@&=+$,/?%#[A-z0-9]*)("[^<]*>)/g;
+
+exports.preprocessMarkupPlugin = ({
+  assetsDir,
+}) => function preprocessMarkup(
+  markup /*: string */,
+) /*: string */ {
+  return markup.replace(IMG_REGEX,
+    function(_, prefix /*: string */, src /*: string */, suffix /*: string */) {
+      return `${prefix}/${path.join(assetsDir, String(src).trim())}${suffix}`;
+    });
+};

packages/webdoc-default-template/publish.js

@@ -15,7 +15,8 @@ const {
   Sitemap,
   TemplateRenderer,
   TemplatePipeline,
-  TemplateTagsResolver, RepositoryPlugin,
+  TemplateTagsResolver,
+  RepositoryPlugin,
 } = require("@webdoc/template-library");
 const {linker, prepareLinker} = require("./helper/linker");
 const _ = require("lodash");
@@ -24,7 +25,7 @@ const _ = require("lodash");
 const {indexSorterPlugin} = require("./helper/renderer-plugins/index-sorter");
 const {signaturePlugin} = require("./helper/renderer-plugins/signature");
 const {categoryFilterPlugin} = require("./helper/renderer-plugins/category-filter");
-
+const {preprocessMarkupPlugin} = require("./helper/renderer-plugins/preprocess");
 /*::
 import type {
   Doc,
@@ -74,6 +75,7 @@ exports.publish = async function publish(options /*: PublishOptions */) {
 
   const docTree = options.documentTree;
   const outDir = path.normalize(options.config.opts.destination);
+  const assetsDir = path.join(outDir, "./assets");
   const index = config.template.readme ? linker.createURI("index") : null;
   const indexRelative = index ? index.replace(`/${linker.siteRoot}/`, "") : null;
 
@@ -123,6 +125,9 @@ exports.publish = async function publish(options /*: PublishOptions */) {
     .installPlugin("categoryFilter", categoryFilterPlugin)
     .installPlugin("relations", RelationsPlugin)
     .installPlugin("hljs", hljs)
+    .installPlugin("preprocess", preprocessMarkupPlugin({
+      assetsDir: path.relative(outDir, assetsDir),
+    }))
     .setGlobalTemplateData({
       appBar: {
         items: appBarItems,
@@ -158,7 +163,7 @@ exports.publish = async function publish(options /*: PublishOptions */) {
     idToDoc.set(doc.id, doc);
   });
 
-  await outStaticFiles(outDir, config);
+  await outStaticFiles(outDir, assetsDir, config);
   await Promise.all([
     outSource(outDir, pipeline, options.config, source, options.cmdLine.mainThread || false),
     outExplorerData(outDir, crawlData),
@@ -174,6 +179,7 @@ exports.publish = async function publish(options /*: PublishOptions */) {
 // Copy the contents of ./static to the output directory
 async function outStaticFiles(
   outDir /*: string */,
+  assetsDir /*: string */,
   config /*: ConfigSchema */,
 ) /*: Promise<void> */ {
   if (config.template.variant !== "plain") {
@@ -214,6 +220,20 @@ async function outStaticFiles(
 
       config.template.stylesheets = resolved;
 
+      return Promise.all(copyPromises);
+    })(),
+    (() => {
+      const assets = typeof config.template.assets === "string" ?
+        [config.template.assets] : config.template.assets;
+      const copyPromises = [];
+
+      for (const asset of assets) {
+        copyPromises.push(fse.copy(
+          path.join(process.cwd(), asset),
+          assetsDir,
+        ));
+      }
+
       return Promise.all(copyPromises);
     })(),
   ]);

packages/webdoc-default-template/tmpl/components/content/text.tmpl

@@ -0,0 +1,5 @@
+<?js
+  if (typeof obj !== 'string') return;
+  const text = this.plugins.preprocess(obj);
+?>
+<?js= text ?>

packages/webdoc-default-template/tmpl/components/member/index.tmpl

@@ -57,8 +57,8 @@ const modifiers = [
     <?js } ?>
   </section>
 
-  <div class="member__brief"><?js= doc.brief ?></div>
-  <div class="member__description"><?js= doc.description ?></div>
+  <div class="member__brief"><?js= this.partial("components/content/text.tmpl", doc.brief) ?></div>
+  <div class="member__description"><?js= this.partial("components/content/text.tmpl", doc.description) ?></div>
 
   <?js for (const example of examples) { ?>
     <?js= this.partial("components/content/example.tmpl", example.code) ?>

packages/webdoc-default-template/tmpl/components/member/params.tmpl

@@ -55,7 +55,7 @@ params.forEach((param) => {
         <?js if (hasDefault) {?><td class="member-parameter__default">
           <?js if (typeof param.default !== 'undefined') { ?><?js= this.htmlText(param.default) ?><?js } ?>
         </td><?js } ?>
-        <td class="member-parameter__description"><?js= param.description ?></td>
+        <td class="member-parameter__description"><?js= this.partial("components/content/text.tmpl", param.description) ?></td>
       </tr><?js }); ?>
     </tbody>
   </table>

packages/webdoc-default-template/tmpl/components/member/returns.tmpl

@@ -18,7 +18,9 @@ const returns = obj || [];
         <td class="member-return__type">
           <?js if (returnElement.dataType) { ?><?js= this.linkTo(returnElement.dataType) ?><?js } ?>
         </td>
-        <td class="member-return__description"><?js if (returnElement.description) { ?><?js= returnElement.description ?><?js } ?></td>
+        <td class="member-return__description"><?js if (returnElement.description) { ?>
+          <?js= this.partial("components/content/text.tmpl", returnElement.description) ?><?js } ?>
+        </td>
       </tr><?js }); ?>
     </tbody>
   </table>

packages/webdoc-default-template/tmpl/document.tmpl

@@ -38,8 +38,8 @@
 
     <?js= this.partial("components/signature.tmpl", doc) ?>
 
-    <div class="document__brief"><?js= doc.brief ?></div>
-    <div class="document__description"><?js= doc.description ?></div>
+    <div class="document__brief"><?js= this.partial("components/content/text.tmpl", doc.brief) ?></div>
+    <div class="document__description"><?js= this.partial("components/content/text.tmpl", doc.description) ?></div>
 
     <?js for (const example of doc.examples ?? []) { ?>
       <?js= this.partial("components/content/example.tmpl", example.code) ?>