From d0046754faf46ee891bdf7813f8dc73c1339cd05 Mon Sep 17 00:00:00 2001 From: Ze Yu Date: Fri, 31 Jul 2020 14:48:08 +0800 Subject: [PATCH 1/9] Add user guide slots section as modals --- docs/userGuide/components/advanced.md | 119 +++++++++----------------- docs/userGuide/syntax/boxes.mbdf | 6 +- docs/userGuide/syntax/dropdowns.mbdf | 4 +- docs/userGuide/syntax/modals.mbdf | 5 +- docs/userGuide/syntax/panels.mbdf | 4 +- docs/userGuide/syntax/popovers.mbdf | 6 +- docs/userGuide/syntax/questions.mbdf | 14 ++- 7 files changed, 64 insertions(+), 94 deletions(-) diff --git a/docs/userGuide/components/advanced.md b/docs/userGuide/components/advanced.md index 8e9a248577..1def9bdf02 100644 --- a/docs/userGuide/components/advanced.md +++ b/docs/userGuide/components/advanced.md @@ -1,81 +1,66 @@ ## Advanced Tips and Tricks -### Rich formatting in headings/titles +^\[S\]^ +Slot -Using the normal syntax, you are only able to use markdown formatting on headings. If you would like more styling options, you can define an element within the component that acts as your heading. This is done by adding a `slot` attribute with the correct name to that element. +### Richer formatting of attributes using slots - - Example
- -

- - R - A - I - N - B - O - W - -

- As shown in this panel, using the header slot allows you to customize the Panel's header using HTML. - - +
- - Example
- Click here to show Modal. - - -
- BIG header -
- Modal allows you to style both header and footer individually, with style classes and inline styles. -
- Tiny footer -
- - +Most component attributes allow a richer form of formatting using slots, denoted by an attribute^\[S\]^ superscript in the respective components' tables. +In other cases, when the option is of type "Slot", only the slot option is available. - -Markup +You can define such a slot within the component by adding a `slot="attribute name"` attribute to any element within the slot. -```html +{{ icon_example }} + + +

- R - A - I - N - B - O - W + R + A + I + N + B + O + W

- As shown in this panel, using the header slot allows you to customize the Panel's header using HTML. + As shown in this panel, using the header slot + allows you to customize the Panel's header using HTML. + +html + +
+ + + + + +**Other examples of slots in use** + +{{ icon_example }} Custom modal header + + Click here to show Modal. -
+
BIG header
Modal allows you to style both header and footer individually, with style classes and inline styles. -
+
Tiny footer
-``` - -
+ +html + -**Box Slot Options:** - -Slot name | Default class | ---- | --- | -icon | depends on box's `type` attribute | {{ icon_example }} Override the default icon for a certain type of box. @@ -120,31 +105,7 @@ icon | depends on box's `type` attribute | use thumbnail as the icon -**Panel Slot Options:** -Slot name | Default class | Notes ---- | --- | --- -header | `card-title` | Aligning text to the center of the panel is not possible, as the header element does not take up the entire container. - -**Modal Slot Options:** -When using slots for Modals, you need to add a single blank line before each `` tag, in order for the customization to render correctly. - -Slot name | Default class | Notes ---- | --- | --- -header
`modal-header`
(deprecated) | `modal-title` | -footer
`modal-footer`
(deprecated) | `modal-footer` | Specifying `modal-footer` will override the `ok-text` attribute, and the OK button will not render. - -**Popover Slot Options:** -Slot name | Default class ---- | --- | --- -header
`title`
(deprecated) | `popover-header` -content | `popover-body` - -**Dropdown Slot Options:** -Slot name | Default class ---- | --- -header | `dropdown-toggle` - -### Inserting custom classes into components +### Inserting custom classes into components {.mt-4 .mb-3} Every component documented in our user guide allows you to insert your own defined CSS classes. This is done by adding the `add-class` attribute to a component along with the desired class names. diff --git a/docs/userGuide/syntax/boxes.mbdf b/docs/userGuide/syntax/boxes.mbdf index 6158c77ac6..919a55e376 100644 --- a/docs/userGuide/syntax/boxes.mbdf +++ b/docs/userGuide/syntax/boxes.mbdf @@ -1,3 +1,5 @@ + + ## Boxes **Boxes come with different built-in types.** @@ -183,10 +185,10 @@ border-color | `String` | `null` | border-left-color | `String` | `null` | Overrides border-color for the left border. color | `String` | `null` | Color of the text. dismissible | `Boolean` | `false` | Adds a button to close the box to the top right corner. -icon | `String` | `null` | Inline MarkDown text of the icon displayed on the left. +icon{{slot_info_trigger}} | `String` | `null` | Inline MarkDown text of the icon displayed on the left. icon-size | `String` | `null` | Resizes the icon. Supports integer-scaling of the icon dimensions e.g. `2x`, `3x`, `4x`, etc. icon-color | `String` | `null` | Color of the icon. -header
heading
(deprecated) | `String` | `null` | Markdown text of the box header. +header{{slot_info_trigger}}
heading
(deprecated) | `String` | `null` | Markdown text of the box header. type | `String` | `''` | Supports: `info`, `warning`, `success`, `important`, `wrong`, `tip`, `definition`, or empty for default. light | `Boolean` | `false` | Uses a light color scheme for the box. seamless | `Boolean` | `false` | Uses a seamless style for the box. If `light` is specified, this style will not be activated. diff --git a/docs/userGuide/syntax/dropdowns.mbdf b/docs/userGuide/syntax/dropdowns.mbdf index a0292900d9..4eafe6f2e7 100644 --- a/docs/userGuide/syntax/dropdowns.mbdf +++ b/docs/userGuide/syntax/dropdowns.mbdf @@ -1,3 +1,5 @@ + + ## Dropdowns **You can use Dropdowns as a top level component.** @@ -60,7 +62,7 @@ Name | Type | Default | Description --- | --- | --- | --- disabled | `Boolean` | `false` | Whether Dropdown can be opened. menu-align-right | `Boolean` | `false` | Whether the dropdown list will be right-aligned. -header
text
(deprecated) | `String` | `''` | Dropdown button header text. (Supports inline MarkDown syntax) +header{{slot_info_trigger}}
text
(deprecated) | `String` | `''` | Dropdown button header text. (Supports inline MarkDown syntax) type | `String` | `default` | Supports: `default`, `primary`, `danger`, `info`, `warning`, `success`.
diff --git a/docs/userGuide/syntax/modals.mbdf b/docs/userGuide/syntax/modals.mbdf index 29cf1ab2c9..97cfc41c53 100644 --- a/docs/userGuide/syntax/modals.mbdf +++ b/docs/userGuide/syntax/modals.mbdf @@ -1,3 +1,5 @@ + + ## Modals **Modals are to be used together with the [Trigger](#trigger) component for activation.** @@ -39,7 +41,8 @@ This is the same trigger as last one. ****Options**** Name | type | Default | Description --- | --- | --- | --- -header
title
(deprecated) | `String` | `''` | Header of the Modal component. Supports inline markdown text. +header{{slot_info_trigger}}
title
(deprecated) | `String` | `''` | Header of the Modal component. Supports inline markdown text. +footer
modal-footer
(deprecated) | {{slot_type_info_trigger}} | empty | Specifying this will override the `ok-text` attribute, and the OK button will not render. ok-text | `String` | `''` | Text for the OK button. effect | `String` | `zoom` | Supports: `zoom`, `fade`. id | `String` | | Used by [Trigger](#trigger) to activate the Modal by id.large | `Boolean` | `false` | Creates a [large Modal](https://getbootstrap.com/docs/4.0/components/modal/#optional-sizes). diff --git a/docs/userGuide/syntax/panels.mbdf b/docs/userGuide/syntax/panels.mbdf index 6a1011ca17..d3226b09d5 100644 --- a/docs/userGuide/syntax/panels.mbdf +++ b/docs/userGuide/syntax/panels.mbdf @@ -1,3 +1,5 @@ + + ## Panels **Panel is a flexible container that supports collapsing and expanding its content. It is expandable by default.** @@ -157,7 +159,7 @@ ****Options**** Name | Type | Default | Description --- | --- | --- | --- -header | `String` | `''` | The clickable text on the Panel's header. Supports MarkDown text. +header{{slot_info_trigger}} | `String` | `''` | The clickable text on the Panel's header. Supports MarkDown text. alt | `String` | Panel header | The clickable text on the minimised Panel. Supports MarkDown text. expandable | `Boolean`| `true` | Whether Panel is expandable. expanded | `Boolean` | `false` | Whether Panel is expanded or collapsed when loaded in. diff --git a/docs/userGuide/syntax/popovers.mbdf b/docs/userGuide/syntax/popovers.mbdf index 1de232700f..8ceb3b2dd5 100644 --- a/docs/userGuide/syntax/popovers.mbdf +++ b/docs/userGuide/syntax/popovers.mbdf @@ -1,3 +1,5 @@ + + ## Popovers @@ -77,8 +79,8 @@ This is the same trigger as last one. Name | Type | Default | Description ---- | ---- | ------- | ------ trigger | `String` | `hover` | How the Popover is triggered.
Supports: `click`, `focus`, `hover`. -header
title
(deprecated) | `String` | `''` | Popover header, supports inline markdown text. -content | `String` | `''` | Popover content, supports inline markdown text. +header{{slot_icon_trigger}}
title
(deprecated) | `String` | `''` | Popover header, supports inline markdown text. +content{{slot_icon_trigger}} | `String` | `''` | Popover content, supports inline markdown text. placement | `String` | `top` | How to position the Popover.
Supports: `top`, `left`, `right`, `bottom`. diff --git a/docs/userGuide/syntax/questions.mbdf b/docs/userGuide/syntax/questions.mbdf index c6e152c9d5..0dc4261c57 100644 --- a/docs/userGuide/syntax/questions.mbdf +++ b/docs/userGuide/syntax/questions.mbdf @@ -1,3 +1,5 @@ + + ## Questions and Quizzes Question and quiz components provide an easy way to test readers on the relevant content topic in the page. {.mt-3} @@ -134,10 +136,8 @@ Placing the question into the header is entirely optional. You may also wish to Name | Type | Default | Description --- | --- | --- | --- type | `String` | `''` | The type of question. Supports `mcq`, `checkbox` or `text`. -header | `String` | `''` | The markup to insert into the question header. The header is omitted if this is not provided. -header | Slot | empty | Functions similar to the `header` option, and overrides it if both are present. -hint | `String` | `''` | The content to display in the hint box. -hint | Slot | empty | Functions similar to the `hint` option, and overrides it if both are present. +header{{slot_info_trigger}} | `String` | `''` | The markup to insert into the question header. The header is omitted if this is not provided. +hint{{slot_info_trigger}} | `String` | `''` | The content to display in the hint box. #### MCQ and Checkbox Questions {.mt-4 .mb-3} @@ -210,8 +210,7 @@ Optionally, you can provide the reason for the particular option using the ` From 5ff43af2380be42bf1da3f767c7cc651a35d7b0e Mon Sep 17 00:00:00 2001 From: Ze Yu Date: Fri, 31 Jul 2020 14:48:56 +0800 Subject: [PATCH 2/9] Document missing large option for modals --- docs/userGuide/syntax/modals.mbdf | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/userGuide/syntax/modals.mbdf b/docs/userGuide/syntax/modals.mbdf index 97cfc41c53..8faaaf193c 100644 --- a/docs/userGuide/syntax/modals.mbdf +++ b/docs/userGuide/syntax/modals.mbdf @@ -47,6 +47,7 @@ ok-text | `String` | `''` | Text for the OK button. effect | `String` | `zoom` | Supports: `zoom`, `fade`. id | `String` | | Used by [Trigger](#trigger) to activate the Modal by id.large | `Boolean` | `false` | Creates a [large Modal](https://getbootstrap.com/docs/4.0/components/modal/#optional-sizes). small | `Boolean` | `false` | Creates a [small Modal](https://getbootstrap.com/docs/4.0/components/modal/#optional-sizes). +large | `Boolean` | `false` | Creates a [large Modal](https://getbootstrap.com/docs/4.0/components/modal/#optional-sizes). center | `Boolean` | `false` | Vertically centers the modal (in addition to the horizontal centering by default). backdrop | `Boolean` | `true` | Enables closing the Modal by clicking on the backdrop. From 5719118e89c61d2046502999b9ba6d54ff5b6111 Mon Sep 17 00:00:00 2001 From: Ze Yu Date: Fri, 31 Jul 2020 16:32:13 +0800 Subject: [PATCH 3/9] Tidy up formattingContents user guide page - Add section on markdown attributes (attributes.mbdf) - Fix a minor spelling error in formattingContents.md - Add missing newline at eof (images.mbdf, tables.mbdf) - Add relative link example using markdown (links.mbdf) - Add starting list number trick example (lists.mbdf) --- docs/userGuide/formattingContents.md | 2 +- docs/userGuide/fullSyntaxReference.md | 1 + docs/userGuide/syntax/attributes.mbdf | 66 +++++++++++++++++++++++++++ docs/userGuide/syntax/images.mbdf | 2 +- docs/userGuide/syntax/links.mbdf | 29 ++++++------ docs/userGuide/syntax/lists.mbdf | 28 +++++++++++- docs/userGuide/syntax/tables.mbdf | 2 +- 7 files changed, 112 insertions(+), 18 deletions(-) create mode 100644 docs/userGuide/syntax/attributes.mbdf diff --git a/docs/userGuide/formattingContents.md b/docs/userGuide/formattingContents.md index 227168feb2..428ea38214 100644 --- a/docs/userGuide/formattingContents.md +++ b/docs/userGuide/formattingContents.md @@ -15,7 +15,7 @@ -**MarkBind supports a wide collection of Markdown-like basic content formatting syntax** such as text stying, tables, lists, images, links, etc. +**MarkBind supports a wide collection of Markdown-like basic content formatting syntax** such as text styling, tables, lists, images, links, etc. diff --git a/docs/userGuide/fullSyntaxReference.md b/docs/userGuide/fullSyntaxReference.md index 838c53c981..8e91f92d76 100644 --- a/docs/userGuide/fullSyntaxReference.md +++ b/docs/userGuide/fullSyntaxReference.md @@ -17,6 +17,7 @@ links : ['Links', ['basic', 'reader-facing']], footnotes: ['Footnotes', ['basic', 'reader-facing']], images : ['Images', ['basic', 'reader-facing']], + attributes: ['Classes, Attributes & Identifiers', ['basic', 'reader-facing']], tables : ['Tables', ['basic', 'reader-facing']], emoji : ['Emoji', ['basic', 'reader-facing']], icons : ['Icons', ['basic', 'reader-facing']], diff --git a/docs/userGuide/syntax/attributes.mbdf b/docs/userGuide/syntax/attributes.mbdf new file mode 100644 index 0000000000..07009bf937 --- /dev/null +++ b/docs/userGuide/syntax/attributes.mbdf @@ -0,0 +1,66 @@ +## Classes, Attributes & Identifiers + +Most markdown syntax above this section supports adding classes, attributes and identifiers +using [pandoc](https://pandoc.org/MANUAL.html) syntax without the need for a wrapper html element. + +The syntax is `{.class-name attribute="value" attribute=value #id}`, which is placed at different locations depending +on the type of markdown. + + +markdown + +Apply classes, attributes, identifiers to block level markdown (eg. paragraphs, headings) +by leaving a space before '{' {.text-success #attribute-example} + +#### heading {.text-info} + +--- {.border-danger} + +Apply the same to inline markdown (eg. bold text) by +omitting the **space**{.text-primary .bg-light header="attributes example"} + + + + +Some other types of markdown have **different placements** of the curly group `{...}`. {.mb-4} + +****Unordered and Ordered lists**** + + +markdown + +* Apply to the list item itself like so {.text-success #list-item-id} + * Curly groups after newlines apply to the closest nested list {.text-danger} +{.bg-light} +* Curly groups two lines after the last line apply to the top most list + +{.alert-info} + + + +****Fenced code blocks**** + +Refer to the above [section](../formattingContents.html#line-numbering)! + +For a more detailed guide, see: https://www.npmjs.com/package/markdown-it-attrs + + +Formatting features listed above this section support this syntax for attributes, classes and identifiers. +Those below this section do not. + + + + + +``` +add a space before '{' for block level markdown {.class-name attribute="value" attribute=value #id} + +don't add a space for **inline**{.text-danger} markdown +``` +For a more detailed guide, see: https://www.npmjs.com/package/markdown-it-attrs + + + + + + diff --git a/docs/userGuide/syntax/images.mbdf b/docs/userGuide/syntax/images.mbdf index fc70cacbc9..65b0ea496f 100644 --- a/docs/userGuide/syntax/images.mbdf +++ b/docs/userGuide/syntax/images.mbdf @@ -21,4 +21,4 @@ ![alt text here](https://markbind.org/images/logo-lightbackground.png "title here") - \ No newline at end of file + diff --git a/docs/userGuide/syntax/links.mbdf b/docs/userGuide/syntax/links.mbdf index fc4dfb7275..2687a5c9a5 100644 --- a/docs/userGuide/syntax/links.mbdf +++ b/docs/userGuide/syntax/links.mbdf @@ -30,10 +30,10 @@ MarkBind home is at [here][1]. Links to files of the generated site (e.g., an HTML page or an image file) can be specified either as relative paths or absolute paths. -Absolute paths: +****Absolute paths****
-Links should start with {% raw %}`{{ baseUrl }}`{% endraw %} (which represents the root directory of the project). +Links should start with {% raw %}`{{ baseUrl }}`{% endraw %} (which represents the root directory of the site). {{ icon_example }} Here's how to specify a link to (1) a page, and (2) an image, using the {% raw %}`{{ baseUrl }}`: @@ -47,14 +47,14 @@ To ensure that links in the _markbind/ folder work correctly across {% endraw %}
-Relative paths: +****Relative paths****
{{ icon_example }} Assuming that we have the following folder structure: ``` -c:/course/ - ├── textbook/ +C:\course\ + ├── textbook\ | ├── subsite.md | ├── image.png | └── site.json @@ -65,20 +65,21 @@ c:/course/ Within `textbook/subsite.md`, we can refer to the image using: ```html + +![](image.png) ``` Within `index.md`, we can also display the image using ```html -``` -or by including `subsite.md`: -```html - + +![](textbook/image.png) ``` - - Relative links to resources (e.g. images, hrefs) should be valid relative to the original, included file. In other words, the links should be accessible when traversing starting from the location of the included file. -
- In the example above, image.png is in the same directory as subsite.md. When using relative references, the correct path is image.png and not textbook/image.png. + + + Relative links to resources (e.g. images, hrefs) should be valid **relative to the file where the link is defined**. + + In the example above, `image.png` is in the same directory as `subsite.md`. Thus, the correct path is `image.png` and not `textbook/image.png`.
@@ -98,4 +99,4 @@ MarkBind home is at [here][1]. MarkBind home is at [here](https://markbind.org). - \ No newline at end of file + diff --git a/docs/userGuide/syntax/lists.mbdf b/docs/userGuide/syntax/lists.mbdf index 33a495cabf..38eecb0d19 100644 --- a/docs/userGuide/syntax/lists.mbdf +++ b/docs/userGuide/syntax/lists.mbdf @@ -29,6 +29,32 @@ + +You can also start an ordered list at a particular number by changing the + +first number + +! + + More info on above list types: https://www.markdownguide.org/basic-syntax#lists ****Task lists**** (from GFMD): @@ -82,4 +108,4 @@ - [ ] Item 3 - [x] Item 4 - ( ) Item 5 - \ No newline at end of file + diff --git a/docs/userGuide/syntax/tables.mbdf b/docs/userGuide/syntax/tables.mbdf index 22a24eb483..3bb51056f7 100644 --- a/docs/userGuide/syntax/tables.mbdf +++ b/docs/userGuide/syntax/tables.mbdf @@ -34,4 +34,4 @@ Animal | Trainable?| Price | Remarks Ants | no | 5 | Bees | no | 20 | Cats|yes|100| - \ No newline at end of file + From c8efeb0ff89906ad3eb775cb9d29771aeb7bb57b Mon Sep 17 00:00:00 2001 From: Ze Yu Date: Tue, 28 Jul 2020 21:43:51 +0800 Subject: [PATCH 4/9] Add missing keywords to keywords.mbdf --- docs/userGuide/syntax/keywords.mbdf | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/userGuide/syntax/keywords.mbdf b/docs/userGuide/syntax/keywords.mbdf index 3a17561a55..3ef4d2492b 100644 --- a/docs/userGuide/syntax/keywords.mbdf +++ b/docs/userGuide/syntax/keywords.mbdf @@ -1,4 +1,6 @@ ## Keywords +regress +regression testing **You can also specify additional keywords to be indexed under a heading** by tagging the words with the `keyword` class. Those keywords will be linked to the heading immediately above it. If you want to index a keyword without rendering it in the page, add `d-none` as a class. From 5d498593a7ae347846b320fe22c2fb9b4e9d4cd5 Mon Sep 17 00:00:00 2001 From: Ze Yu Date: Tue, 28 Jul 2020 21:53:12 +0800 Subject: [PATCH 5/9] Add yaml spec note to frontmatter --- docs/userGuide/syntax/frontmatter.mbdf | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/userGuide/syntax/frontmatter.mbdf b/docs/userGuide/syntax/frontmatter.mbdf index fa64711372..b4191a6330 100644 --- a/docs/userGuide/syntax/frontmatter.mbdf +++ b/docs/userGuide/syntax/frontmatter.mbdf @@ -18,6 +18,11 @@ ```
+ + +Should you need more expressive formatting, or encounter any issues when formatting the frontmatter, note that the frontmatter follows the [yaml](https://yaml.org/refcard.html) spec. + + **Page properties:** * **`title`**: The title of the page. Will be used as the `` attribute of the HTML page generated. From e0aaf9b0ec764c5f2e15e963c73bc26fb7bbb150 Mon Sep 17 00:00:00 2001 From: Ze Yu <angzeyu@gmail.com> Date: Fri, 31 Jul 2020 14:52:30 +0800 Subject: [PATCH 6/9] Move writing plugins to developer guide --- docs/_markbind/layouts/devGuide/navigation.md | 1 + docs/devGuide/writingPlugins.md | 171 ++++++++++++++++++ docs/userGuide/usingPlugins.md | 163 +---------------- 3 files changed, 174 insertions(+), 161 deletions(-) create mode 100644 docs/devGuide/writingPlugins.md diff --git a/docs/_markbind/layouts/devGuide/navigation.md b/docs/_markbind/layouts/devGuide/navigation.md index 2cf7cae2a4..449f330023 100644 --- a/docs/_markbind/layouts/devGuide/navigation.md +++ b/docs/_markbind/layouts/devGuide/navigation.md @@ -6,6 +6,7 @@ * [Setting up]({{baseUrl}}/devGuide/settingUp.html) * [Workflow]({{baseUrl}}/devGuide/workflow.html) * [Design]({{baseUrl}}/devGuide/design.html) +* [Writing Plugins]({{baseUrl}}/devGuide/writingPlugins.html) * [Project management]({{baseUrl}}/devGuide/projectManagement.html) * Appendices :expanded: * [Style guides]({{baseUrl}}/devGuide/styleGuides.html) diff --git a/docs/devGuide/writingPlugins.md b/docs/devGuide/writingPlugins.md new file mode 100644 index 0000000000..dab6b367b4 --- /dev/null +++ b/docs/devGuide/writingPlugins.md @@ -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 Rendering]({{baseUrl}}/images/rendering.png) + +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> diff --git a/docs/userGuide/usingPlugins.md b/docs/userGuide/usingPlugins.md index 6351bad094..504647aee8 100644 --- a/docs/userGuide/usingPlugins.md +++ b/docs/userGuide/usingPlugins.md @@ -73,169 +73,10 @@ Only run plugins from sources that you trust. Do not run the plugin if the sourc Plugins come as `.js` files. To install an external plugin, simply put it in the `_markbind/plugins` folder. To use the plugin, update the `site.json` file the same way you did for built-in plugins. -### Writing Plugins -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. - -#### Rendering - -![MarkBind Rendering]({{baseUrl}}/images/rendering.png) - -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> +## Writing Plugins +You may also write your own plugins! Refer [here]({{baseUrl}}/devdocs/devGuide/writingPlugins.html) for the available interfaces to do so. {% from "njk/common.njk" import previous_next %} {{ previous_next('settingSiteProperties', 'makingTheSiteSearchable') }} From 61831cf5a419e08dd7e85080b3e6b49b4f7bfaaf Mon Sep 17 00:00:00 2001 From: Ze Yu <angzeyu@gmail.com> Date: Tue, 28 Jul 2020 22:41:10 +0800 Subject: [PATCH 7/9] Remove unsupported option from tooltip example --- docs/userGuide/syntax/tooltips.mbdf | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/userGuide/syntax/tooltips.mbdf b/docs/userGuide/syntax/tooltips.mbdf index b0d1673d14..72ac54dec0 100644 --- a/docs/userGuide/syntax/tooltips.mbdf +++ b/docs/userGuide/syntax/tooltips.mbdf @@ -18,18 +18,18 @@ <hr /> Trigger <p> - <tooltip effect="scale" content="Lorem ipsum dolor sit amet" placement="top" trigger="click"> + <tooltip content="Lorem ipsum dolor sit amet" placement="top" trigger="click"> <button class="btn btn-secondary">Click</button> </tooltip> <br /> <br /> - <tooltip effect="scale" content="Lorem ipsum dolor sit amet" placement="top" trigger="focus"> + <tooltip content="Lorem ipsum dolor sit amet" placement="top" trigger="focus"> <input placeholder="Focus"></input> </tooltip> </p> **Markdown**: -<tooltip effect="scale" content="*Hello* **World**"> +<tooltip content="*Hello* **World**"> <a href="">Hover me</a> </tooltip> <br /> From 86281f672dd532b4dc35d96f34bf06e68b5c4b1b Mon Sep 17 00:00:00 2001 From: Ze Yu <angzeyu@gmail.com> Date: Tue, 28 Jul 2020 22:42:47 +0800 Subject: [PATCH 8/9] Expand cliCommands.md panels by default --- docs/userGuide/cliCommands.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/userGuide/cliCommands.md b/docs/userGuide/cliCommands.md index cc30ca2aaa..c9345d9c07 100644 --- a/docs/userGuide/cliCommands.md +++ b/docs/userGuide/cliCommands.md @@ -39,7 +39,7 @@ Usage: markbind <command> Root directory. Default is the current directory.<br> {{ icon_example }} `./myWebsite` -<panel header="**Options** :fas-cogs:" type="minimal"> +<panel header="**Options** :fas-cogs:" type="minimal" expanded> **Options** :fas-cogs: @@ -76,7 +76,7 @@ Usage: markbind <command> Root directory. The default is the directory where this command was executed.<br> {{ icon_example }} `./myWebsite` -<panel header="**Options** :fas-cogs:" type="minimal"> +<panel header="**Options** :fas-cogs:" type="minimal" expanded> **Options** :fas-cogs: @@ -135,7 +135,7 @@ The caveat is that not building all pages during the initial process, or not reb Read source files from the `[root]` directory and put the generated files in the specified `[output]` directory<br> {{ icon_example }} `./myWebsite ../myOutDir` -<panel header="**Options** :fas-cogs:" type="minimal"> +<panel header="**Options** :fas-cogs:" type="minimal" expanded> **Options** :fas-cogs: @@ -165,7 +165,7 @@ The caveat is that not building all pages during the initial process, or not reb **Description:** Deploys the site to the repo's Github pages by pushing everything in the generated site (default dir: `_site`) to the `gh-pages` branch of the current git working directory's remote repo. -<panel header="**Options** :fas-cogs:" type="minimal"> +<panel header="**Options** :fas-cogs:" type="minimal" expanded> **Options** :fas-cogs: From d46e80d24e14a963b868da3a011193297c999249 Mon Sep 17 00:00:00 2001 From: Ze Yu <angzeyu@gmail.com> Date: Tue, 28 Jul 2020 22:50:47 +0800 Subject: [PATCH 9/9] Remove js/css mention from pageHead.mbdf --- docs/userGuide/syntax/pageHead.mbdf | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/userGuide/syntax/pageHead.mbdf b/docs/userGuide/syntax/pageHead.mbdf index 8975115082..6355c147d6 100644 --- a/docs/userGuide/syntax/pageHead.mbdf +++ b/docs/userGuide/syntax/pageHead.mbdf @@ -43,14 +43,13 @@ To specify that you want to insert `myCustomLinks.md` into the `<head>` of `myPa </div> **Multiple head files can be included** within a page by providing a comma separated list. They will be added to the `<head>` in the order in which they are listed. -**You may specify raw `.js` or `.css` files** as your head file if you wish to do so. <div class="indented"> {{ icon_example }} ```html <frontmatter> - head: customStyles.md, extraScripts.md, extra.css, other.js + head: customStyles.md, extraScripts.md </frontmatter> ``` </div>