Add plugins functionality

Author: jamos-tay

docs/_markbind/navigation/userGuideSections.md

@@ -7,6 +7,7 @@
   * [Including Contents]({{baseUrl}}/userGuide/includingContents.html)
   * [Using Components]({{baseUrl}}/userGuide/usingComponents.html)
   * [Using Variables]({{baseUrl}}/userGuide/usingVariables.html)
+  * [Using Plugins]({{baseUrl}}/userGuide/usingPlugins.html)
   * [Page Layout]({{baseUrl}}/userGuide/pageLayout.html)
   * [Known Problems]({{baseUrl}}/userGuide/knownProblems.html)
 * Deploying a Site

docs/common/header.md

@@ -12,6 +12,7 @@
     <li><a href="{{baseUrl}}/userGuide/includingContents.html" class="dropdown-item">◦&nbsp; Including Contents</a></li>
     <li><a href="{{baseUrl}}/userGuide/usingComponents.html" class="dropdown-item">◦&nbsp; Using Components</a></li>
     <li><a href="{{baseUrl}}/userGuide/usingVariables.html" class="dropdown-item">◦&nbsp; Using Variables</a></li>
+    <li><a href="{{baseUrl}}/userGuide/usingPlugins.html" class="dropdown-item">◦&nbsp; Using Plugins</a></li>
     <li><a href="{{baseUrl}}/userGuide/pageLayout.html" class="dropdown-item">◦&nbsp; Page Layout</a></li>
     <li><a href="{{baseUrl}}/userGuide/knownProblems.html" class="dropdown-item">◦&nbsp; Known Problems</a></li>
     <li role="separator" class="dropdown-divider"></li>

docs/images/rendering.png

@@ -37,6 +37,10 @@
       "src": "userGuide/usingVariables.md",
       "title": "MarkBind: User Guide - Using Variables"
     },
+    {
+      "src": "userGuide/usingPlugins.md",
+      "title": "MarkBind: User Guide - Using Plugins"
+    },
     {
       "src": "userGuide/pageLayout.md",
       "title": "MarkBind: User Guide - Page Layout"

docs/site.json

@@ -0,0 +1,99 @@
+<frontmatter>
+  footer: userGuideFooter.md
+  siteNav: userGuideSections.md
+</frontmatter>
+
+<include src="../common/header.md" />
+
+<div class="website-content">
+
+# Using Plugins
+
+A plugin is a user defined extension that can add custom features to MarkBind. Markbind plugins are `js` scripts that are loaded and run during the page generation.
+
+### Adding Plugins
+
+Plugins are stored in the `_markbind/plugins` folder which is generated on `init`. To use a plugin, place the `js` file in the `_markbind/plugins` folder and add the following options to the site configuration:
+
+- `plugins`: An array of plugin names to use
+- `context`: An object mapping plugin name to data provided to the plugin. Each plugin can have its own custom data.
+
+For example:
+
+```
+{
+  ...
+  "plugins" : [
+    "plugin1",
+    "plugin2",
+  ],
+  "context" : {
+    "plugin1" : "Input Data",
+    "plugin2" : ["Input", "Data"]
+  }
+}
+```
+
+### Writing Plugins
+
+MarkBind plugins allow the user to mutate the page data (`html`) during the page compilation process.
+
+![Markbind Rendering]({{baseUrl}}/images/rendering.png)
+
+MarkBind provides two entry points for modifying the page:
+
+- Prerender: Called before any markbind rendering is done on the site. Markbind rendering refers to the conversion of markdown to valid HTML.
+- Postrender: Called after all markbind rendering is done on the site.
+
+These are controlled by specifying the `preRender` and `postRender` functions in the plugin `js`. Each function takes in two parameters:
+
+- `content`: The intermediate content of the page data represented as a string. 
+  -  For `preRender`, `content` will be the raw markdown of a `.md` file.
+  -  For `postRender`, `content` will be the compiled `.html` file.
+- `siteContext`: Any other data to be provided to the plugin. This can be specified in the `site.json`.
+
+Markbind will call these two functions with the respective content, and retrieve a string data that is used for the next step of the compilation process.
+
+A plugin will typically follow a format similar to this one:
+
+```js
+// myPlugin.js
+
+const cheerio = module.parent.require('cheerio');
+
+module.exports = {
+  postRender: (content, siteContext) => {
+    const $ = cheerio.load(content, { xmlMode: false });
+    // Modify the page...
+    $('#my-div').append(siteContext["post"]);
+    return $.html();
+  },
+};
+```
+
+```js
+// site.json
+
+{
+  ...
+  "plugins" : [
+    "myPlugin"
+  ],
+  "context" : {
+    "plugin1" : {
+      "post" : "<p>Hello</p>"
+    }
+  }
+}
+```
+
+```md
+// index.md
+
+...
+<div id="my-div"></div>
+```
+
+The above plugin appends a paragraph of text to a div in the `index.md`.
+
+</div>

docs/userGuide/usingPlugins.md

@@ -51,10 +51,12 @@ function Page(pageConfig) {
   this.baseUrl = pageConfig.baseUrl;
   this.baseUrlMap = pageConfig.baseUrlMap;
   this.content = pageConfig.content || '';
+  this.context = pageConfig.context;
   this.faviconUrl = pageConfig.faviconUrl;
   this.layout = pageConfig.layout;
   this.layoutsAssetPath = pageConfig.layoutsAssetPath;
   this.rootPath = pageConfig.rootPath;
+  this.plugins = pageConfig.plugins;
   this.searchable = pageConfig.searchable;
   this.src = pageConfig.src;
   this.template = pageConfig.pageTemplate;
@@ -555,13 +557,15 @@ Page.prototype.generate = function (builtFiles) {
         return this.removeFrontMatter(result);
       })
       .then(result => addContentWrapper(result))
+      .then(result => this.preRender(result))
       .then(result => this.insertSiteNav((result)))
       .then(result => this.insertFooter(result)) // Footer has to be inserted last to ensure proper formatting
       .then(result => formatFooter(result))
       .then(result => markbinder.resolveBaseUrl(result, fileConfig))
       .then(result => fs.outputFileAsync(this.tempPath, result))
       .then(() => markbinder.renderFile(this.tempPath, fileConfig))
       .then(result => this.addAnchors(result))
+      .then(result => this.postRender(result))
       .then((result) => {
         this.content = htmlBeautify(result, { indent_size: 2 });
 
@@ -594,6 +598,32 @@ Page.prototype.generate = function (builtFiles) {
   });
 };
 
+/**
+ * Entry point for plugin pre render
+ */
+Page.prototype.preRender = function (content) {
+  let preRenderedContent = content;
+  Object.keys(this.plugins).forEach((plugin) => {
+    if (this.plugins[plugin].preRender) {
+      preRenderedContent = this.plugins[plugin].preRender(preRenderedContent, this.context[plugin]);
+    }
+  });
+  return preRenderedContent;
+};
+
+/**
+ * Entry point for plugin post render
+ */
+Page.prototype.postRender = function (content) {
+  let postRenderedContent = content;
+  Object.keys(this.plugins).forEach((plugin) => {
+    if (this.plugins[plugin].postRender) {
+      postRenderedContent = this.plugins[plugin].postRender(postRenderedContent, this.context[plugin]);
+    }
+  });
+  return postRenderedContent;
+};
+
 /**
  * Adds linked layout files to page assets
  */

lib/Page.js

@@ -39,6 +39,7 @@ const GLYPHICONS_PATH = 'asset/glyphicons.csv';
 const HEAD_FOLDER_PATH = '_markbind/head';
 const INDEX_MARKDOWN_FILE = 'index.md';
 const PAGE_TEMPLATE_NAME = 'page.ejs';
+const PLUGIN_FOLDER_PATH = '_markbind/plugins';
 const SITE_CONFIG_NAME = 'site.json';
 const SITE_DATA_NAME = 'siteData.json';
 const SITE_NAV_PATH = '_markbind/navigation/site-nav.md';
@@ -123,6 +124,7 @@ function Site(rootPath, outputPath, forceReload = false, siteConfigPath = SITE_C
   this.addressablePages = [];
   this.baseUrlMap = {};
   this.forceReload = forceReload;
+  this.loadedPlugins = {};
   this.siteConfig = {};
   this.siteConfigPath = siteConfigPath;
   this.userDefinedVariablesMap = {};
@@ -184,6 +186,7 @@ Site.initSite = function (rootPath) {
   const siteNavPath = path.join(rootPath, SITE_NAV_PATH);
   const siteLayoutPath = path.join(rootPath, LAYOUT_FOLDER_PATH);
   const siteLayoutDefaultPath = path.join(siteLayoutPath, LAYOUT_DEFAULT_NAME);
+  const sitePluginPath = path.join(rootPath, PLUGIN_FOLDER_PATH);
   const userDefinedVariablesPath = path.join(rootPath, USER_VARIABLES_PATH);
   // TODO: log the generate info
   return new Promise((resolve, reject) => {
@@ -261,6 +264,13 @@ Site.initSite = function (rootPath) {
           });
         });
       })
+      .then(() => fs.accessAsync(sitePluginPath))
+      .catch(() => {
+        if (fs.existsSync(sitePluginPath)) {
+          return Promise.resolve();
+        }
+        return fs.mkdirp(sitePluginPath);
+      })
       .then(resolve)
       .catch(reject);
   });
@@ -302,8 +312,10 @@ Site.prototype.createPage = function (config) {
     baseUrl: this.siteConfig.baseUrl,
     baseUrlMap: this.baseUrlMap,
     content: '',
+    context: this.siteConfig.context || {},
     faviconUrl: config.faviconUrl,
     pageTemplate: this.pageTemplate,
+    plugins: this.loadedPlugins || {},
     rootPath: this.rootPath,
     searchable: config.searchable,
     src: config.pageSrc,
@@ -449,6 +461,7 @@ Site.prototype.generate = function (baseUrl) {
       .then(() => this.collectAddressablePages())
       .then(() => this.collectBaseUrl())
       .then(() => this.collectUserDefinedVariablesMap())
+      .then(() => this.collectPlugins())
       .then(() => this.buildAssets())
       .then(() => this.buildSourceFiles())
       .then(() => this.copyMarkBindAsset())
@@ -564,6 +577,19 @@ Site.prototype.buildAssets = function () {
   });
 };
 
+/**
+ * Load all plugins of the site
+ */
+Site.prototype.collectPlugins = function () {
+  if (!this.siteConfig.plugins) {
+    return;
+  }
+  this.siteConfig.plugins.forEach((plugin) => {
+    // eslint-disable-next-line global-require, import/no-dynamic-require
+    this.loadedPlugins[plugin] = require(path.join(this.rootPath, PLUGIN_FOLDER_PATH, `${plugin}.js`));
+  });
+};
+
 /**
  * Renders all pages specified in site configuration file to the output folder
  */

lib/Site.js

@@ -0,0 +1,10 @@
+const cheerio = module.parent.require('cheerio');
+
+module.exports = {
+  preRender: (content, siteContext) => content.replace('Prerender', `${siteContext.pre}`),
+  postRender: (content, siteContext) => {
+    const $ = cheerio.load(content, { xmlMode: false });
+    $('#test-plugins').append(`${siteContext.post}`);
+    return $.html();
+  },
+};

test/test_site/_markbind/plugins/testPlugin.js

@@ -0,0 +1,10 @@
+const cheerio = module.parent.require('cheerio');
+
+module.exports = {
+  preRender: (content, siteContext) => content.replace('Prerender', `${siteContext.pre}`),
+  postRender: (content, siteContext) => {
+    const $ = cheerio.load(content, { xmlMode: false });
+    $('#test-plugins').append(`${siteContext.post}`);
+    return $.html();
+  },
+};

test/test_site/expected/_markbind/plugins/testPlugin.js

@@ -295,6 +295,11 @@ <h2 id="panel-content-of-unexpanded-panel-should-not-appear-in-search-data">Pane
           <h2 id="panel-content-inside-unexpanded-panel-should-not-appear-in-search-data">Panel content inside unexpanded panel should not appear in search data<a class="fa fa-anchor" href="#panel-content-inside-unexpanded-panel-should-not-appear-in-search-data"></a></h2>
         </panel>
       </panel>
+      <h1 id="div-for-plugins">Div for plugins<a class="fa fa-anchor" href="#div-for-plugins"></a></h1>
+      <div id="test-plugins">
+        <p>Prerender</p>
+        <p>Postrender</p>
+      </div>
     </div>
   </div>
 </div>