+
+# 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. MarkBind allows plugins to modify a page's content during the page generation process.
+
+
+
+**WARNING:** Plugins are executable programs that can be written by anyone. This means that they might contain malicious code that may damage your computer.
+
+Only run plugins from sources that you trust. Do not run the plugin if the source/origin of the plugin cannot be ascertained.
+
+
+### Adding Plugins
+
+Plugins are stored in the `_markbind/plugins` folder which is generated on `init`. To use a plugin, place the `js` source of the plugin in the `_markbind/plugins` folder and add the following options to `site.json`:
+
+- `plugins`: An array of plugin names to use.
+- `pluginsContext`: A mapping of plugin names to parameters passed to each individual plugin. It is recommended to use key-value pairs for consistency.
+
+For example:
+
+```js
+{
+ ...
+ "plugins": [
+ "plugin1",
+ "plugin2",
+ ],
+ "pluginsContext": {
+ "plugin1": {
+ "input": "Input for Plugin 1"
+ },
+ "plugin2": {
+ "data": "Data for Plugin 2"
+ },
+ }
+}
+```
+
+### Writing Plugins
+
+
+
+MarkBind provides two entry points for modifying the page, pre-render and post-render. These are controlled by implementing the `preRender()` and `postRender()` functions in the plugin:
+
+- `preRender(content, pluginContext, frontMatter)`: Called before MarkBind renders the source from Markdown to HTML.
+ - `content`: The raw Markdown of any Markdown file (`.md`, `.mbd`, etc.).
+ - `pluginContext`: User provided parameters for the plugin. This can be specified in the `site.json`.
+ - `frontMatter`: The frontMatter of the page being processed, in case any frontMatter data is required.
+- `postRender(content, pluginContext, frontMatter)`: Called after the HTML is rendered, before writing it to a file.
+ - `content`: The rendered HTML.
+ - `pluginContext`: User provided parameters for the plugin. This can be specified in the `site.json`.
+ - `frontMatter`: The frontMatter of the page being processed, in case any frontMatter data is required.
+
+MarkBind will call these functions with the respective content, and retrieve a string data that is used for the next step of the page generation process.
+
+An example of a plugin is shown below. The plugin shows two ways of appending a paragraph of text to a specific `div` in the Markdown files:
+
+```js
+// myPlugin.js
+
+const cheerio = module.parent.require('cheerio');
+
+module.exports = {
+ preRender: (content, pluginContext, frontMatter) => content.replace('[Pre-render Placeholder]', `${pluginContext.pre}`),
+ postRender: (content, pluginContext, frontMatter) => {
+ const $ = cheerio.load(content, { xmlMode: false });
+ // Modify the page...
+ $('#my-div').append(pluginContext.post);
+ return $.html();
+ },
+};
+```
+
+```js
+// site.json
+
+{
+ ...
+ "plugins": [
+ "myPlugin"
+ ],
+ "pluginsContext": {
+ "myPlugin": {
+ "pre": "
Hello
",
+ "post": "
Goodbye
"
+ }
+ }
+}
+```
+
+```md
+// index.md
+
+...
+
+[Pre-render Placeholder]
+
+```
+
+### Built-in plugins
+
+MarkBind has a set of built-in plugins that can be used immediately without installation.
+
+#### `filterTags`: Toggling alternative contents in a page
+
+You can use tags to selectively filter HTML elements when building a site.
+
+Tags are specified by the `tags` attribute, **and can be attached to any HTML element**. During rendering, only elements that match tags specified in the `site.json` files will be rendered.
+
+
+
+{{ icon_example }} Attaching tags to elements:
+```html
+# Print 'Hello world'
+
+
System.out.println("Hello world");
+
Console.WriteLine("Hello world");
+
print("Hello world")
+```
+
+You need to specify the tags to include in the `pluginsContext`, under `tags`:
+
+```json
+{
+ ...
+ "plugins" : [
+ "filterTags"
+ ],
+ "pluginsContext" : {
+ "filterTags" : {
+ "tags": ["language--java"]
+ }
+ }
+}
+```
+
+All other tagged elements will be filtered out. In this case, only the element with the `language--java` tag will be rendered. This is helpful when creating multiple versions of a page without having to maintain separate copies.
+
+
+
+If the `filterTags` plugin is not enabled in `site.json`, all tagged elements will be rendered.
+
+**You can also use multiple tags in a single HTML element. Specify each tag in the `tags` attribute** separated by a space. An element will be rendered if **any of the tags** matches the one in `site.json`.
+
+
+
+{{ icon_example }} Attaching multiple tags to an element:
+```html
+# For loops
+
+
for (int i = 0; i < 5; i++) { ... }
+```
+
+As long as the `language--java` or `language--C#` tag is specified, the code snippet will be rendered.
+
+
+
+Alternatively, you can specify tags to render for a page in the front matter.
+
+
+
+{{ icon_example }} Specifying tags in front matter:
+```html
+
+ title: "Hello World"
+ tags: ["language--java"]
+
+```
+
+
+Tags in `site.json` will take precedence over the ones in the front matter.
+
+
Pane
Panel content inside unexpanded panel should not appear in search data
+ Test plugin in markbind/plugins
+
+
Markbind Plugin Pre-render
+
Node Modules Plugin Post-render
+
+ Markbind Plugin Pre-render Placeholder
+
diff --git a/test/functional/test_site/site.json b/test/functional/test_site/site.json
index 6b2ac10771..65e1584f3f 100644
--- a/test/functional/test_site/site.json
+++ b/test/functional/test_site/site.json
@@ -59,6 +59,18 @@
"deploy": {
"message": "Site Update."
},
- "tags" : ["tag--shown", "tag--shown-2"],
- "headingIndexingLevel": 4
+ "headingIndexingLevel": 4,
+ "plugins" : [
+ "testMarkbindPlugin",
+ "filterTags"
+ ],
+ "pluginsContext" : {
+ "testMarkbindPlugin" : {
+ "pre": "\n\n# Markbind Plugin Pre-render",
+ "post": "