-
Notifications
You must be signed in to change notification settings - Fork 141
Misc doc updates #1294
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Misc doc updates #1294
Changes from all commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
d004675
Add user guide slots section as modals
ang-zeyu 5ff43af
Document missing large option for modals
ang-zeyu 5719118
Tidy up formattingContents user guide page
ang-zeyu c8efeb0
Add missing keywords to keywords.mbdf
ang-zeyu 5d49859
Add yaml spec note to frontmatter
ang-zeyu e0aaf9b
Move writing plugins to developer guide
ang-zeyu 61831cf
Remove unsupported option from tooltip example
ang-zeyu 86281f6
Expand cliCommands.md panels by default
ang-zeyu d46e80d
Remove js/css mention from pageHead.mbdf
ang-zeyu File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,171 @@ | ||
| <variable name="title">Writing Plugins</variable> | ||
| <frontmatter> | ||
| title: "{{ title }}" | ||
| layout: devGuide | ||
| pageNav: default | ||
| </frontmatter> | ||
|
|
||
| # {{ title }} | ||
|
|
||
| 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, amongst other things. | ||
|
|
||
| This page details the available interfaces you may use to write plugins. | ||
|
|
||
| ## Rendering | ||
|
|
||
|  | ||
|
|
||
| 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": "<p>Hello</p>", | ||
| "post": "<p>Goodbye</p>" | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ```md | ||
| // index.md | ||
|
|
||
| ... | ||
| <div id="my-div"> | ||
| [Pre-render Placeholder] | ||
| </div> | ||
| ``` | ||
|
|
||
| ## Assets | ||
|
|
||
| Plugins can implement the methods `getLinks` and `getScripts` to add additional assets to the page. | ||
|
|
||
| - `getLinks(content, pluginContext, frontMatter, utils)`: Called to get link elements to be added to the head of the page. | ||
| - `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. | ||
| - `utils`: Object containing the following utility functions | ||
| - `buildStylesheet(href)`: Builds a stylesheet link element with the specified `href`. | ||
| - Should return an array of strings containing link elements to be added. | ||
| - `getScripts(content, pluginContext, frontMatter, utils)`: Called to get script elements to be added after the body of the page. | ||
| - `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. | ||
| - `utils`: Object containing the following utility functions | ||
| - `buildScript(src)`: Builds a script element with the specified `src`. | ||
| - Should return an array of strings containing script elements to be added. | ||
|
|
||
| <box type="success" header="Local assets"> | ||
| <md> | ||
| You can set an absolute or relative file path as the `src` or `href` attribute in your `<script>` or `<link>` tags. | ||
| MarkBind will copy these assets into the output directory and change the `src` or `href` attributes automatically! | ||
| </md> | ||
| </box> | ||
|
|
||
| An example of a plugin which adds links and scripts to the page: | ||
|
|
||
| ```js | ||
| // myPlugin.js | ||
|
|
||
| module.exports = { | ||
| getLinks: (content, pluginContext, frontMatter, utils) => [utils.buildStylesheet('STYLESHEET_LINK')], | ||
| getScripts: (content, pluginContext, frontMatter, utils) => | ||
| [utils.buildScript('SCRIPT_LINK'), '<script>alert("hello")</script>'], | ||
| }; | ||
|
|
||
| ``` | ||
|
|
||
| This will add the following link and script elements to the page: | ||
| - `<link rel="stylesheet" href="STYLESHEET_LINK">` | ||
| - `<script src="SCRIPT_LINK"></script>` | ||
| - `<script>alert("hello")</script>` | ||
|
|
||
| ## Live reload | ||
|
|
||
| By default, MarkBind treats `.html`, `.md`, `.mbd`, and `.mbdf` as source files, and will rebuild any | ||
| pages changed when serving the page. | ||
|
|
||
| During the `preRender` and `postRender` stages however, plugins may do custom processing using some other | ||
| source file types, as parsed from the raw Markdown, typically requiring rebuilding the site. | ||
|
|
||
| Hence, to add custom source files to watch, you can implement the `getSources()` method. | ||
|
|
||
| `getSources(content, pluginContext, frontMatter)`: Called _before_ a Markdown file's `preRender` function is called. | ||
| - `content`: The raw Markdown of the current 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. | ||
|
|
||
| It should return an object, consisting of _at least one of the following fields_: | ||
| - `tagMap`: An array consisting of `['tag name', 'source attribute name']` key value pairs. | ||
| - MarkBind will automatically search for matching tags with the source attributes, and watch them. | ||
| - For relative file paths, _if the tag is part of some included content_ ( eg. `<include />` tags ), it will be resolved against the included page. Otherwise, it is resolved against the page being processed. | ||
| - `sources`: An array of source file paths to watch, where relative file paths are resolved only against the page being processed. | ||
| - You can also directly return an array of source file paths to watch. ( ie. the `sources` field ) ___(deprecated)___ | ||
|
|
||
| Example usage of `getSources` from the PlantUML plugin, which allows insertion of PlantUML diagrams using `<puml src="..." >` tags. | ||
| This allows files specified by the `src` attributes of `<puml>` tags to be watched: | ||
|
|
||
| ```js | ||
| { | ||
| ... | ||
| getSources: () => ({ | ||
| tagMap: [['puml', 'src']], | ||
| }) | ||
| } | ||
| ``` | ||
|
|
||
| ## Special tags | ||
|
|
||
| By default, content in html tags are parsed as html and markdown. | ||
|
|
||
| However, you might want to create a plugin that has certain special tags containing conflicting syntax | ||
| you do not wish to be parsed as html or markdown. | ||
|
|
||
| You can implement the `getSpecialTags` method to blacklist the content in these special tags from parsing, | ||
| removing such potential conflicts. | ||
|
|
||
| - `getSpecialTags(pluginContext)`: Called during initial site generation to blacklist special tags. | ||
| - `pluginContext`: User provided parameters for the plugin. This can be specified in the `site.json`. | ||
| - Should return an array of string tag names to be blacklisted, with each tag name being at least 2 characters long. | ||
|
|
||
| <box type="important"> | ||
|
|
||
| Note however, that variable interpolation syntax {% raw %}`{{ variable_name }}`{% endraw %} will act as per normal. | ||
| Meaning, the user would still be able to use variables in your special tags! | ||
| </box> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Writing plugins is not just for devs. Even regular users are supposedly can write plugins. Give at least a link from the UG as well.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Added. I think the main content should stay in the devguide though, since the large majority of users won't be writing such plugins.