• HOME
• SHOWCASE
• # Syntax Cheat Sheet

Classes, Attributes & Identifiers
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

## Classes, Attributes & Identifiers

Most markdown syntax above this section supports adding classes, attributes and identifiers using pandoc 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.

CODE:

Apply classes, attributes, identifiers to block level markdown (eg. paragraphs, headings)
by leaving a space before '{' {.text-success #attribute-example}

--- {.border-danger}

Apply the same to inline markdown (eg. bold text) by
omitting the **space**{.text-primary .bg-light header="attributes example"}
<!-- Use inspect element on the **space** word below to see the "header" attribute! -->


OUTPUT:

Apply classes, attributes, identifiers to block level markdown (eg. paragraphs, headings) by leaving a space before '{'

Apply the same to inline markdown (eg. bold text) by omitting the space

Some other types of markdown have different placements of the curly group {...}.

Unordered and Ordered lists

CODE:

* 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



OUTPUT:

• Apply to the list item itself like so
• Curly groups after newlines apply to the closest nested list
• Curly groups two lines after the last line apply to the top most list

Fenced code blocks

Refer to the above section!

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.

<span class="badge badge-primary">Primary</span>
<button type="button" class="btn btn-primary">
</button>


CODE:

Normal:
<br>Pills:


OUTPUT:

Normal: Primary Secondary Success Danger Warning Info Light Dark
Pills: Primary Secondary Success Danger Warning Info Light Dark

CODE:

Links:

Buttons:
<button type="button" class="btn btn-primary">
</button>



OUTPUT:

Buttons:

### Feature X beta

##### Feature Y stable

Blockquotes
> Blockquote, first paragraph
>
> Second paragraph
>> Nested blockquote


## Blockquotes

CODE:

Normal text
> Blockquote, first paragraph
>
> Second paragraph
>> Nested quoteblock


OUTPUT:

Normal text

Blockquote, first paragraph

Second paragraph

Nested quoteblock

Alternatively, you can use <blockquote> tags:

CODE:

Normal text
<blockquote>
Blockquote, first paragraph

Second paragraph
<blockquote>
Nested blockquote
</blockquote>
</blockquote>


OUTPUT:

Normal text

Blockquote, first paragraph

Second paragraph

Nested blockquote

Boxes
<box type="warning">
warning
</box>


## Boxes

Boxes come with different built-in types.

CODE:

<box>
default
</box>
<box type="info">
info
</box>
<box type="warning">
warning
</box>
<box type="success">
success
</box>
<box type="important">
important
</box>
<box type="wrong">
wrong
</box>
<box type="tip">
tip
</box>
<box type="definition">
definition
</box>
<box type="info" dismissible>
dismissible info
</box>

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

<box type="warning" header="You can use **markdown** here! :pizza:" dismissible>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
</box>
</box>


OUTPUT:

default info warning success important wrong tip definition dismissible info

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

You can use markdown here! 🍕

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Markbind also supports a light color scheme for boxes

CODE:

<box light>
default light
</box>
<box type="info" light>
info light
</box>
<box type="warning" light>
warning light
</box>
<box type="success" light>
success light
</box>
<box type="important" light>
important light
</box>
<box type="wrong" light>
wrong light
</box>
<box type="tip" light>
tip light
</box>
<box type="definition" light>
definition light
</box>
</box>


OUTPUT:

default light info light warning light success light important light wrong light tip light definition light

MarkBind also supports a seamless style of boxes

As light and seamless are mutually exclusive styles, light takes priority over seamless.

CODE:

<box seamless>
default seamless
</box>
<box type="info" seamless>
info seamless
</box>
<box type="warning" seamless>
warning seamless
</box>
<box type="success" seamless>
success seamless
</box>
<box type="important" seamless>
important seamless
</box>
<box type="wrong" seamless>
wrong seamless
</box>
<box type="tip" seamless>
tip seamless
</box>
<box type="definition" seamless dismissible>
dismissible definition seamless
</box>
</box>


OUTPUT:

default seamless info seamless warning seamless success seamless important seamless wrong seamless tip seamless dismissible definition seamless

You can further customize the Box's appearance.

CODE:

<box background-color="#ffca6a" border-color="grey" border-left-color="#8b5a01">
default type, styled as an orange box with a brown left border
</box>
<box type="info" color="red" icon=":rocket:">

info, with a custom markdown rocket icon and red colored text.

You can use any inline markdown in the icon property.
</box>


OUTPUT:

default type, styled as an orange box with a brown left border
🚀

info, with a custom markdown rocket icon and red colored text.

You can use any inline markdown in the icon property.

You can remove the background, icon and borders of preset styles.

CODE:

<box no-icon no-background type="success">
success box without a tick icon and backgound
</box>

<box no-border type="definition" light>
definition type box, light style without border
</box>


OUTPUT:

success box without a tick icon and backgound definition type box, light style without border

Note

Custom styles ( background-color, border-color, border-left-color, icon ) as introduced in the previous section, takes precedence over the no-background, no-border, no-icon attributes.

You can also use icons, resize them and change their color accordingly.

CODE:

<box type="success" icon=":fas-camera:">
Lorem ipsum dolor sit amet, consectetur adipiscing elit
</box>
<box type="warning" icon=":fas-camera:" icon-size="2x">
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
</box>
<box type="definition" icon=":fas-camera:" icon-size="3x">
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
</box>
<box type="info" icon=":fas-camera:" icon-color="red" icon-size="3x">
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
</box>


OUTPUT:

Lorem ipsum dolor sit amet, consectetur adipiscing elit
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Options

Name Type Default Description
background-color String null
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[S] 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.
(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.
no-border Boolean false Removes border, except if styled by border-color or border-left-color.
no-backgound Boolean false Removes background, except if styled by backgound-color option.
no-icon Boolean false Removes icon, except if icon is displayed via icon option.
Code
xml
<foo>
<bar type="name">goo</bar>
</foo>


<bar type="name" cwf="C:\Users\ZeYu\Desktop\markbind\docs\userGuide\syntax\code.mbdf">goo</bar>{.xml}


## Code

#### Themes

MarkBind can present formatted code blocks, be it fenced or inline, with either light or dark themes. The default is dark.

Refer here for configuring MarkBind to use a specific theme for the code blocks.

#### Fenced Code

MarkBind provides several features, some of which are added on top of the existing functionality of Markdown's fenced code blocks.

Features:

• Syntax coloring
• Line numbering
• Line highlighting
##### Syntax coloring

To enable syntax coloring, specify a language next to the backticks before the fenced code block.

CODE:

xml
<foo>
<bar type="name">goo</bar>
</foo>



OUTPUT:

<foo>
<bar type="name">goo</bar>
</foo>

##### Line numbering

Line numbers are provided by default. To hide line numbers, add the class no-line-numbers to the code block as below

CODE:

xml {.no-line-numbers}
<foo>
<bar type="name">goo</bar>
</foo>



OUTPUT:

<foo>
<bar type="name">goo</bar>
</foo>


You can have your line numbers start with a value other than 1 with the start-from attribute.

CODE:

js {start-from=6}
return a + b;
}



OUTPUT:

function add(a, b) {
return a + b;
}

##### Line highlighting

To highlight lines, add the attribute highlight-lines as shown below.

You can specify highlighting in many different ways, depending on how you want it to be. There are two main variants:

Text-only highlighting

To highlight only the text portion of the line, you can just use the line numbers as is.

For ranges of lines, join the two line numbers with a dash sign (-).

Whole-line highlighting

If you wish to highlight a full line (including whitespaces) or ranges of it, you can leverage MarkBind's own line-slice syntax. Line-slices are in the form of lineNumber[:], e.g. 2[:].

This variant's format is very similar to the previous, but instead use line-slices rather than line numbers.

For ranges, you only need to use line-slices on either ends.

CODE:

java {highlight-lines="1,3[:],6-8,10[:]-12"}
import java.util.List;

public class Inventory {
private List<Item> items;

public int getItemCount(){
return items.size();
}

public bool isEmpty() {
return items.isEmpty();
}

//...
}



OUTPUT:

import java.util.List;

public class Inventory {
private List<Item> items;

public int getItemCount(){
return items.size();
}

public bool isEmpty() {
return items.isEmpty();
}

//...
}


To add a heading, add the attribute heading with the heading text as the value, as shown below.

CODE:

xml {heading="Heading title"}
<foo>
<bar type="name">goo</bar>
</foo>



OUTPUT:

<foo>
<bar type="name">goo</bar>
</foo>


Headings support inline Markdown, except for Inline Code and Dim text styles.

CODE:

{heading="**Bold**, _Italic_, ___Bold and Italic___, ~~Strike through~~, ****Super Bold****, !!Underline!!, ==Highlight==, :+1: :exclamation: :x: :construction:<br>We support page breaks"}
<foo></foo>



OUTPUT:

Bold, Italic, Bold and Italic, Strike through, Super Bold, Underline, Highlight, 👍 ❗️ ❌ 🚧
We support page breaks
<foo></foo>

##### Using multiple features

You can also use multiple features together, as shown below.

CODE:

xml {highlight-lines="2" heading="Heading title"}
<foo>
<bar type="name">goo</bar>
</foo>



OUTPUT:

<foo>
<bar type="name">goo</bar>
</foo>


#### Inline Code

##### Syntax coloring

MarkBind can apply syntax-coloring on inline code too.

CODE:

Consider the xml code <bar type="name" cwf="C:\Users\ZeYu\Desktop\markbind\docs\userGuide\syntax\codeAndOutput.md">goo</bar>{.xml},<br>
or the java code public static void main(String[] args){.java}.


OUTPUT:

Consider the xml code <bar type="name">goo</bar>,
or the java code public static void main(String[] args).

Dates

{{ "2019-08-12" | date("DD.MM.YYYY", 10) }} <!-- 22.08.2019 -->

22.08.2019

## Dates

Markbind supports date formatting and simple calculations as a Nunjucks filter.

Syntax: {{ baseDate | date(format, daysToAdd) }}

20 days after 1st Jan 2020:

{{ "2020-01-01" | date("ddd, Do MMM, YYYY", 20) }} Tue, 21st Jan, 2020

The baseDate follows the format: YYYY-MM-DD

The default output format is "ddd D MMM" e.g. Fri 6 Mar

### Using variables

{% set base1 = "2020-01-01" %}
{% set format1 = "DD MM YYYY" %}
{% set format2 = "ddd Do MMM (DD/MM/YYYY)" %}

{{ base1 | date }} Wed 1 Jan

#### Custom formatting

{{ base1 | date(format1) }} 01 01 2020

{{ base1 | date(format2, 0) }} Wed 1st Jan (01/01/2020)
{{ base1 | date(format2, 10) }} Sat 11th Jan (11/01/2020)

#### Page variables

Dates can be supplied using page variables for convenience.

Inside variables.md or referencing page:

<variable name="date_pagevar">2020-03-06</variable>


{{ date_pagevar | date(format2) }} Fri 6th Mar (06/03/2020)

The output date can be formatted to suit your needs by specifying a format string as an argument to the date filter.

Default format: "ddd D MMM" e.g. Fri 6 Mar

Brief reference

Token Output
D 1
Do 1st
DD 01
M 1
MM 01
MMM Jan
MMMM January
YY 19
YYYY 2019

Full formatting reference available here.

Example

CODE:

{% set base1 = "2019-08-12" %}
{% set format1 = "DD MM YYYY" %}
{% set format2 = "ddd Do MM" %}
{{ base1 | date }} <!-- Mon 12 Aug -->
{{ base1 | date(format1) }} <!-- 12 08 2019 -->
{{ base1 | date(format1, 10) }} <!-- 22 08 2019 -->
{{ base1 | date(format2, 10) }} <!-- Thu 22/08 -->

OUTPUT:

Mon 12 Aug
12 08 2019
22 08 2019
Thu 22/08

Diagrams
<puml width=300>
@startuml
alice -> bob ++ : hello
bob -> bob ++ : self call
@enduml
</puml>


## Diagrams

You can use the PlanUML syntax to add diagrams.

Java and Graphviz must be installed to use this feature

• Java 8 or later (required to run the PlantUML JAR executable)
• Graphviz v2.38 or later (required to generate all diagrams)

CODE:

<puml width=300>
@startuml
alice -> bob ++ : hello
bob -> bob ++ : self call
bob -> bib ++  #005500 : hello
bob -> george ** : create
return done
return rc
bob -> george !! : delete
return success
@enduml
</puml>


OUTPUT:

Alternatively, a PlantUML diagram can be specified in a separate .puml file and inserted into a page using a <puml> tag.

CODE:

diagrams/sequence.puml:

@startuml
alice -> bob ++ : hello
bob -> bob ++ : self call
bob -> bib ++  #005500 : hello
bob -> george ** : create
return done
return rc
bob -> george !! : delete
return success
@enduml


in another file:

<puml src="diagrams/sequence.puml" width=300 />


OUTPUT:

The full PlantUML syntax reference can be found at plantuml.com/guide

More examples

Sequence Diagram:

Use Case Diagram:

Class Diagram:

Activity Diagram:

Component Diagram:

State Diagram:

Object Diagram:

Gantt Diagram:

Entity Relation Diagram:

Ditaa Diagram:

Archimate Diagram:

Options

Name Type Description
alt string The alternative text of the diagram.
height string The height of the diagram in pixels.
name string The name of the output file.
src string The URL of the diagram if your diagram is in another .puml file.
width string The width of the diagram in pixels.
If both width and height are specified, width takes priority over height. It is to maintain the diagram's aspect ratio.
Dropdowns
<dropdown header="Action" type="primary">
<li><a href="#dropdown" class="dropdown-item">Action</a></li>
<li><a href="#dropdown" class="dropdown-item">Another action</a></li>
<li role="separator" class="dropdown-divider"></li>
</dropdown>


You can use Dropdowns as a top level component.

CODE:

<!--Notice how header attribute supports inline MarkDown-->
<li><a href="#dropdown" class="dropdown-item">Action</a></li>
<li><a href="#dropdown" class="dropdown-item">Another action</a></li>
<li><a href="#dropdown" class="dropdown-item">Something else here</a></li>
<li role="separator" class="dropdown-divider"></li>
</dropdown>

<!-- For segmented dropdown, ignore header and add a "before" slot -->
<dropdown type="info">
<button slot="before" type="button" class="btn btn-info">Segmented</button>
<li><a href="#dropdown" class="dropdown-item">...</a></li>
</dropdown>

<!-- Right aligned list -->
<li><a href="#dropdown" class="dropdown-item">Something else here</a></li>
</dropdown>


OUTPUT:

*Action*
Action
• Action
• Another action
• Something else here
• ...
• Right aligned list
Right aligned list
• Something else here
• You can also use Dropdowns as a nested component (e.g. part of a button group).

CODE:

<!-- In a button group -->
<div class="btn-group d-flex" role="group">
<a href="#dropdown" class="btn btn-danger w-100" role="button">Left</a>
<!-- With slots you can handle some elements as native bootstrap -->
<dropdown class="w-100">
<button slot="button" type="button" class="btn btn-warning dropdown-toggle w-100">
Action
<span class="caret"></span>
</button>
<li><a href="#dropdown" class="dropdown-item">Action</a></li>
<li><a href="#dropdown" class="dropdown-item">Another action</a></li>
<li><a href="#dropdown" class="dropdown-item">Something else here</a></li>
<li role="separator" class="dropdown-divider"></li>
</ul>
</dropdown>
<a href="#dropdown" class="btn btn-success w-100" role="button">Right</a>
</div>


OUTPUT:

Options

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.
text
(deprecated)
String '' Dropdown button header text. (Supports inline MarkDown syntax)
type String default Supports: default, primary, danger, info, warning, success.

You may refer to this documentation regarding how you can use the Bootstrap buttons, and how to style them.

Embeds
@[youtube](v40b3ExbM0c)



## Embeds

There are easy ways to embed media content such as YouTube videos and PowerPoint slides.

Here are three ways of embedding YouTube videos and one example of how it will look in the page.

CODE:

@[youtube](v40b3ExbM0c)


OUTPUT:

More media blocks, embedding services and additional options can be found in Markdown-it documentation.

###### Embedding Powerpoint Slides (using the embed url from Powerpoint online)

Here is an example of embedding a PowerPoint slide deck:

CODE:

@[powerpoint](https://onedrive.live.com/embed?cid=A5AF047C4CAD67AB&resid=A5AF047C4CAD67AB%212070&authkey=&em=2)


OUTPUT:

Emoji
:+1: :exclamation: :x: :construction:


## Emoji

CODE:

:+1: :exclamation: :x: :construction:


OUTPUT:

👍 ❗️ ❌ 🚧

Footers
<footer>
</footer>

<frontmatter>
footer: commonFooter.md
</frontmatter>


## Footers

You can specify a For an example of a page footer, see the bottom of this page.page footer using a footer file.

You can save multiple footer files in the _markbind/footers folder and specify it in the <frontmatter> of the pages in which it should appear.

Example _markbind/footers/commonFooter.md:

<footer>
</footer>


In the page that you want to include the footer:

<frontmatter>
footer: commonFooter.md
</frontmatter>


Notes:

• Any inline footers will be removed by MarkBind to ensure compatibility with footer files.
• If a Layout is specified, the footer file specified in the <frontmatter> will override the footer within the Layout.
• If you wish to use a Layout but exclude its footer file, specify footer: none in the <frontmatter> of the page.
• MarkBind Components and <include> tags are not supported in footers.

Footnotes
**Normal footnotes:**
Here is a footnote reference,[^1] and another.[^longnote]

[^1]: Here is the footnote. Footnotes will appear at the bottom of the page.

[^longnote]: Here's one with multiple blocks.
Subsequent paragraphs are indented to show that they
belong to the previous footnote.


## Footnotes

CODE:

**Normal footnotes:**
Here is a footnote reference,[^1] and another.[^longnote]

[^1]: Here is the footnote. Footnotes will appear at the bottom of the page.

[^longnote]: Here's one with multiple blocks.

Subsequent paragraphs are indented to show that they
belong to the previous footnote.

**Inline footnotes:**
Here is an inline note.^[Inlines notes are easier to write, since
you don't have to pick an identifier and move down to type the
note.]


OUTPUT:

Normal footnotes: Here is a footnote reference,[1] and another.[2]

Inline footnotes: Here is an inline note.[3]

Normal footnotes won't work when used inside the attributes of markbind components!
For example, it won't work in the header attribute of panels.

Front Matter
<frontmatter>
title: Binary Search Tree
pageNav: 2
</frontmatter>


## Front Matter

You can use a Front Matter section to specify page properties such as the title and keywords of the page. To specify front matter for a page, insert a <frontmatter> tag in the following format at the beginning of the page.

<frontmatter>
property1: value1
property2: value2
</frontmatter>


Example Here, we set the page title attribute as Binary Search Tree.

<frontmatter>
title: Binary Search Tree
</frontmatter>


Should you need more expressive formatting, or encounter any issues when formatting the frontmatter, note that the frontmatter follows the yaml spec.

Page properties:

• title: The title of the page. Will be used as the <title> attribute of the HTML page generated.
• Other properties such as keywords, layout, head etc. will be explained in other places of this user guide.

Note: Page properties that are defined in site.json for a particular page will override those defined in the front matter of the page.

<header>
<div class="bg-primary display-4 text-center text-white" style="height: 200px;">
Welcome!
</div>

<frontmatter>
</frontmatter>


You can specify a Content to be placed at the top of a page.page header above your page contents and Site Navigation and

You can save multiple header files in the _markbind/headers folder and specify it in the <frontmatter> of the pages in which it should appear.

Example _markbind/headers/welcomeBanner.md:

<header>
<div class="bg-primary display-4 text-center text-white">
Welcome!
</div>


In the page that you want to include the header:

<frontmatter>
</frontmatter>


You can fix the header to be always on the top by add fixed attribute to the <header> tag of your header file:

Example _markbind/headers/header.md:

<header fixed>



Notes:

• Any inline headers will be removed by MarkBind to ensure compatibility with header files.
• If a Layout is specified, the header file specified in the <frontmatter> will override the header within the Layout.
• If you wish to use a Layout but exclude its header file, specify header: none in the <frontmatter> of the page.
• MarkBind Components and <include> tags are not supported in headers.
### Heading level 3
...


You can prepend the heading text with 1-6 # characters to indicate headings of levels 1-6.

CODE:

### Heading level 3
...


OUTPUT:

...

MarkBind auto-generates anchors for all headings.
If the heading text is Foo Bar (Goo), the ID of the generated anchor will be foo-bar-goo (all lower case, special characters ommitted, joined by -).

Horizontal Rules
*****
-----
______________


## Horizontal Rules

Use three or more asterisks (***), dashes (---), or underscores (___) to indicate a horizontal line.

CODE:

*****
-----
______________


OUTPUT:

Icons

:glyphicon-hand-right: :fab-github: :fas-home:

## Icons

Acknowledgement: Font Awesome icons are provided by Font Awesome under their free license, Glyphicons are provided by Glyphicons via Bootstrap 3, and Octicons are copyright of GitHub.

MarkBind supports using Font Icons provided by Font Awesome, Glyphicons and GitHub's Octicons.

The advantage of font icons over emojis is font icons can be styled to fit your needs. e.g.,

• emoji: Don't judge the 📖 by it's cover! 👎
• font icons: Don't judge the by it's cover!

The syntax for icons has changed, and the earlier {{ prefix_name }} syntax has been deprecated.
Please use the new :prefix-name: syntax instead.

###### Using Font Awesome Icons
1. Decide which icon you want to use from the list of available icons.

2. Construct the MarkBind name for the selected icon by adding the type prefix. Note: Font Awesome has three different styles for their icons, each with their own type prefix. Here is an example from each type:

• Solid (prefix: fas-) e.g., (actual name file-code, MarkBind name fas-file-code)
• Regular (prefix: far-) e.g., (actual name file-code, MarkBind name far-file-code)
• Brands (prefix: fab-): e.g., (actual name github-alt, MarkBind name fab-github-alt)
3. Insert MarkBind name for the icon enclosed within colons to get the icon in your page.
Create a **branch**:fas-code-branch: now! → Create a branch now!

###### Using Glyphicons
1. Decide which icon you want to use from list of provided glyphicons.
2. Insert the name for the icon enclosed within colons to get the icon in your page.
Move to the right!:glyphicon-hand-right: → Move to the right!

###### Using Octicons
1. Decide which icon you want to use from list of available Octicons.
2. Insert the name for the icon enclosed within colons to get the icon in your page.
Merge a **pull request** :octicon-git-pull-request: → Merge a pull request
3. You may also append ~class-name to the end of the octicon name to add class="class-name" property to your Octicon (e.g. :octicon-git-pull-request~icon-large-red: will generate an Octicon of class icon-large-red). You may then add corresponding CSS to {root}/_markbind/layouts/{layout-name}/styles.css to customize the style of your Octicon.
4. If your background is dark, you may use :octiconlight-*: to render the icon as white.
Images
![alt text here](https://markbind.org/images/logo-lightbackground.png "title here")


## Images

CODE:

![](https://markbind.org/images/logo-lightbackground.png)


OUTPUT:

Includes
<include src="foo.md#bar" boilerplate inline trim>
<variable name="x">5</variable>
</include>


## Includes

MarkBind has a powerful <include> mechanism which allows you to create documents by combining other content fragments.

You can use <include> tag to include another markdown or HTML document into the current document.

Example Including text from a tip2.md in another file.

Tip 1. ...
<include src="tips/tip2.md" />
Tip 3. ...


You can <include> a fragment of a file by specifying the #fragment-id at the end of the src attribute value, provided the fragment is wrapped in a <div>/<span>/<seg> tag with the matching id.

Example Including a fragment from a file:

Some text
<include src="docs/tips.md#tip-1" />
Some other text


docs/tips.md:

...
<div id="tip-1" />
Tip 1. ...
...
</div>
Tip 2. ...


When setting the id of a fragment, be careful not to clash with heading anchor IDs auto-generated by MarkBind. For example, if you have a heading ## Some Useful Tips, MarkBind will auto-generate an ID some-useful-tips for that heading.

The <include> tag works for any MarBind source file including the font matter section but it may not work in some special files such as the _markbind/variables.md.

Attributes:

• src: specify the source file path.
• inline (optional): make the included result an inline element. (wrapped in <span> tag). e.g.,
The title is <include src="../docs/summary.md#title" inline /> while ...

• optional (optional): include the file/fragment only if it exists i.e., there will be no error message if the file/fragment does not exist. e.g.,
<include src="UserStories.md" optional />

• trim (optional): remove leading and trailing whitespace and newlines from the document before including.
<include src="UserStories.md#epic" trim />


The <include> mechanism can be used inside any MarkBind source file (even inside the front matter section) but it will not work inside some special files such as the _markbind/variables.md.

##### <include> Inside an Included File

Although the src attribute of an <include> is given relative to the current directory, it is converted to an absolute value before the i.e., the file containing the <include>host file is included from another file.

Example Suppose you have a MarkBind project with the following file structure.

c:/mySite/
├── bookFiles/
|      ├── book.md
|      ├── chapter1.md
|      └── chapter2.md
└── reviewFiles/
└── review.md


The book.md:

# My Book
<include src="chapter1.md" />
<include src="chapter2.md" />


The review.md:

# My Review
<include src="../bookFiles/book.md" />
...


The content of the chapter1.md and chapter2.md will be included in the review.md (via <include src="../bookFiles/book.md" />) although chapter1.md and chapter2.md are not in reviewFiles directory. i.e., <include src="chapter1.md" /> will be interpreted as <include src="c:/mySite/bookFiles/chapter1.md" />

In other words, <include> interprets the reused code relative to the original location of the file, not the location in which it is reused.

##### Specifying Variables in an <include>

It is possible to include variables in an <include>.

Example Specifying title and author variables in an <include> tag:

<include src="article.md">
<variable name="title">My Title</variable>
<variable name="author">John Doe</variable>
</include>


In article.md:

# {{ title }}<br>
Author: {{ author }}


These variables work the same way as variables in _markbind/variables.md, except that they only apply to the included file. They allow the included file to be reused as a template, for different source files using different variable values.

You can also specify include variables within the <include> tag itself by adding a var- prefix.

Example Specifying title and author variables inline:

<include src="article.md" var-title="My Title" var-author="John Doe" />


If the same variable is defined in a chain of <include>s (e.g. a.md includes b.md includes c.md...), variables defined in the top-most <include> will take precedence. Global variables (_markbind/variables.md) will take precedence over any <include> variables.

### Using Boilerplate Files

If you find duplicating a code that needs to stay relative to the directory in which it usedboilerplate code fragment in multiple places of your code base, you can use a boilerplate file to avoid such duplication. Note that you cannot use a normal <include> in this case because the code included using a normal <include> stays relative to the original location while boilerplate code needs to be interpreted relative to the location it is being used.

Example Suppose you have a MarkBind project with the following file structure.

c:/mySite/
├── chapter1/
|      ├── chapter.md
|      ├── text.md
|      └── exercises.md
├── chapter2/
|      ├── chapter.md
|      ├── text.md
|      └── exercises.md
└── book.md


The book.md:

# My Book
<include src="chapter1/chapter.md" />
<include src="chapter2/chapter.md" />


The chapter1/chapter.md:

## Text
<include src="text.md" />
## Exercises
<include src="exercises.md" />


The chapter2/chapter.md:

## Text
<include src="text.md" />
## Exercises
<include src="exercises.md" />


As you can see, both chapter.md files are exactly the same. If we were to use only one of the chapter.md files and <include> it twice in the book.md, we'll end up with the same chapter content duplicated twice, which is not what we want. In other words, chapter.md contains boilerplate code that needs to be interpreted relative to where it is applied, once relative to chapter1 directory and once relative to chapter2 directory.

To use a code fragment as a boilerplate file,

1. Put the code in a file inside the _markbind/boilerplates directory.
2. <include> the file as if a copy of it exists in any directory you want it to applied, but add the boilerplate attribute to the <include> tag.

Example Here's how you can use a boilerplate file to avoid duplicating the chapter.md:

c:/mySite/
├── _markbind/boilerplates/
|      └── chapter.md
├── chapter1/
|      ├── text.md
|      └── exercises.md
├── chapter2/
|      ├── text.md
|      └── exercises.md
└── book.md


The book.md:

# My Book
<include src="chapter1/chapter.md" boilerplate />
<include src="chapter2/chapter.md" boilerplate />


The _markbind/boilerplates/chapter.md:

## Text
<include src="text.md" />
## Exercises
<include src="exercises.md" />


Consider the line <include src="chapter1/chapter.md" boilerplate />. Note how you can use src="chapter1/chapter.md" there is no such file. MarkBind will use the chapter.md file /_markbind/boilerplates/ but interpret it as if the file exist in chapter1 directory (i.e., interpret the chapter1.md code relative to the chapter1 directory.

Similarly, <include src="chapter2/chapter.md" boilerplate /> interprets the chapter.md relative to the chapter2 directory.

If you have many boilerplate files, you can organize them into directories inside the _markbind directory. When using such boilerplate files, you need to replace boilerplate attribute with boilerplate="<path to file relative to _markbind/boilerplates>".

Example Suppose the chapter.md is places in a book directory:

c:/mySite/
└── _markbind/boilerplates/
└── book/
└── chapter.md



It needs to be used as follows:

<include src="chapter1/chapter.md" boilerplate="book/chapter.md" />
<include src="chapter2/chapter.md" boilerplate="book/chapter.md" />

Keywords
<span class="keyword d-none">regress</span>


## Keywords

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.

Example

#### Developer Testing
<span class="keyword d-none">regress</span>
<span class="keyword d-none">regression testing</span>

This is good for catching <span class="keyword">regressions</span>.


Developer Testing

This is good for catching regressions.

You can also set additional keywords to be indexed for an entire page using the keywords attribute inside the <frontmatter> of that page.

Example

<frontmatter>
keywords: regress, regression testing, regressions
</frontmatter>
...

Line Breaks
This is the second sentence.<br>
This should be on a new line.


## Line Breaks

The preferred way to indicate line breaks is to use a <br> tag.

CODE:

This is the second sentence.<br>
This should be on a new line.
This will not be in a new line.


OUTPUT:

This is the second sentence.
This should be on a new line. This will not be in a new line.

MarkBind home is at [here](https://markbind.org).

MarkBind home is at [here][1].

[1]: https://markbind.org


Basic style:

CODE:

MarkBind home is at [here](https://markbind.org).


OUTPUT:

MarkBind home is at here.

Reference style links (i.e., specify the URL in a separate place):

CODE:

MarkBind home is at [here][1].

[1]: https://markbind.org


OUTPUT:

MarkBind home is at here.

Lists
1. Item 1
1. Sub item 1.1
1. Sub item 1.2
* Item 2
* item 2.1
- [ ] Item 3
- [x] Item 4
- ( ) Item 5


## Lists

Unordered lists:

CODE:

* Item 1
* Sub item 1.1
* Sub item 1.2<br>
Second line
* Sub item 1.2.1
* Item 2
* Item 3


OUTPUT:

• Item 1
• Sub item 1.1
• Sub item 1.2
Second line
• Sub item 1.2.1
• Item 2
• Item 3

Ordered lists:

CODE:

1. Item 1
1. Sub item 1.1
1. Sub item 1.2
1. Item 2
1. Item 3


OUTPUT:

1. Item 1
1. Sub item 1.1
2. Sub item 1.2
2. Item 2
3. Item 3
You can also start an ordered list at a particular number by changing the first number
Example

CODE:

10. Item 1
1. Sub item 1.1
1. Sub item 1.2
1. Item 2


OUTPUT:

1. Item 1
2. Sub item 1.1
3. Sub item 1.2
4. Item 2
!

CODE:

- [ ] Item 1
- [ ] Sub item 1.1
- [x] Sub item 1.2
- [x] Item 2
- [ ] Item 3


OUTPUT:

• Item 1
• Sub item 1.1
• Sub item 1.2
• Item 2
• Item 3

CODE:

- ( ) Item 1
- ( ) Item 2
- (x) Item 3


OUTPUT:

Math Formulae

Solve the following simultaneous equations:

$3x + y = 11$ (1)

$\frac{2x}{3} + \frac{2y}{3} = 8$ (2)

Euler's equation $$e^{i\pi}+1=0$$ is a beautiful equation.



## Math Formulae

Markbind supports typesetting TeX math equations. KaTeX is used as a fast math renderer.

Insert inline equations by enclosing them in round brackets $$...$$.

Insert display equations by enclosing them in square brackets $...$.

Insert numbered display equations by enclosing the equation square brackets and the equation number in curly brackets $...$ (1).

CODE:

Solve the following simultaneous equations:

$3x + y = 11$ (1)

$\frac{2x}{3} + \frac{2y}{3} = 8$ (2)

Euler's equation $$e^{i\pi}+1=0$$ is a beautiful equation.


OUTPUT:

Solve the following simultaneous equations:

$3x + y = 11$(1)
$\frac{2x}{3} + \frac{2y}{3} = 8$(2)

Euler's equation $e^{i\pi}+1=0$ is a beautiful equation.

If your equation requires special Nunjucks tags like {{ or }},use a raw-endraw block:

{% raw %}$$e^{{\frac{1}{3}} + 1}$${% endraw %}


Modals
Click <trigger trigger="click" for="modal:unused">here</trigger> to open a modal.
Modal content
</modal>


## Modals

Modals are to be used together with the Trigger component for activation.

CODE:

More about <trigger for="modal:loremipsum">trigger</trigger>.
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
</modal>
<br>
This is the same <trigger for="modal:loremipsum">trigger</trigger> as last one.

<trigger for="modal:centered">This is a trigger for a centered modal</trigger>.

Centered
</modal>

<trigger for="modal:ok-text">This is a trigger for a modal with a custom OK button</trigger>.

<modal header="OK button visible!" id="modal:ok-text" ok-text="Custom OK">
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
</modal>


OUTPUT:

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
This is the same trigger as last one.

This is a trigger for a centered modal.

Centered 🚀
Centered

This is a trigger for a modal with a custom OK button.

OK button visible!
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Triggers

Trigger provides more flexibility in triggering contextual overlay via Tooltip, Popover or Modal.

You could embed a Trigger within the text, and define the Tooltip, Popover or Modal at a separate location, which allows for a cleaner authoring flow.

Specify the id attribute on the Tooltip, Popover or Modal component, and use the same id in the for attribute of the Trigger to allow the Trigger to invoke the specific overlay elements. Additionally, multiple Triggers could share the same overlay by providing them with the same id.

Trigger's trigger attribute (which defaults to hover) is independent of the target's.

Options

Name Type Default Description
trigger String hover How the overlay view is triggered.
Supports: click, focus, hover.
for String null The id for the overlay view to be shown.
placement String auto How to position the Popover or Tooltip.
Supports: auto, top, left, right, bottom.

Options

Name type Default Description
title
(deprecated)
String '' Header of the Modal component. Supports inline markdown text.
footer
modal-footer
(deprecated)
Slot 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 to activate the Modal by id.large
small Boolean false Creates a small Modal.
large Boolean false Creates a large Modal.
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.

Nav Bars
<navbar type="primary">
<!-- Brand as slot -->
<a slot="brand" href="/" title="Home" class="navbar-brand">MarkBind</a>
<!-- You can use dropdown component -->
<li><a href="#navbar" class="dropdown-item">Option</a></li>
</dropdown>
<!-- For right positioning use slot -->
<li slot="right">
</li>
</navbar>


Navbar allows visitors of your website to navigate through pages easily.

Navbars support link highlighting; link highlighting can be customised by specifying rules.

• Define default-highlight-on in <navbar> to specify fallback highlight rules.
• Define data-highlight in <a> tags with the class nav-link or dropdown-item to specify individual highlight rules.

Note: Navbars should be placed within a header file to ensure that they are correctly positioned at the top of the page, above the site navigation and page navigation menus.

CODE:

<navbar type="primary">
<!-- Brand as slot -->
<a slot="brand" href="/" title="Home" class="navbar-brand">MarkBind</a>
<!-- You can use dropdown component -->
<li><a href="#navbar" class="dropdown-item">Option</a></li>
</dropdown>
<!-- For right positioning use slot -->
<li slot="right">
</li>
</navbar>

<navbar type="dark">
<!-- Brand as slot -->
<a slot="brand" href="/" title="Home" class="navbar-brand">MarkBind</a>
<!-- You can use dropdown component -->
<li><a href="#navbar" class="dropdown-item">Option</a></li>
</dropdown>
<!-- For right positioning use slot -->
<li slot="right">
</li>
</navbar>

<navbar type="light">
<!-- Brand as slot -->
<a slot="brand" href="/" title="Home" class="navbar-brand">MarkBind</a>
<!-- You can use dropdown component -->
<li><a href="#navbar" class="dropdown-item">Option</a></li>
</dropdown>
<!-- For right positioning use slot -->
<li slot="right">
</li>
</navbar>


OUTPUT:

Options

Name Type Default Description
type String primary Supports: primary, dark, light, none.
default-highlight-on String sibling-or-child Supports: sibling-or-child, sibling, child, exact, none. Specifies link highlight rules for navbars.

If you wish to further customize your navbar beyond the primary, dark, and light theme colors, specify the type="none" attribute and insert your own custom styles or use built-in background styles via the add-class attribute.

Built-in background styles
For instance, Bootstrap supports .bg-danger, bg-info, bg-primary, bg-success, bg-warning as background colors. In {your-site}/_markbind/headers/header.md, you can change <navbar type="dark/primary/light"> to <navbar type="none" add-class="bg-warning/danger/info/primary/success"> to apply Bootstrap background styles.

<header fixed>
<navbar type="dark">
<a slot="brand" href="/index.html" title="Home" class="navbar-brand"><img src="/images/logo-darkbackground.png" height="20"></a>
<div tags="environment--ug"><li><a highlight-on="sibling-or-child" href="/userGuide/index.html" class="nav-link">USER GUIDE</a></li></div>
<div tags="environment--dg"><li><a highlight-on="sibling-or-child" href="/devGuide/index.html" class="nav-link">DEVELOPER GUIDE</a></li></div>
<li>
</li>
<li slot="right">
<form class="navbar-form">
</form>
</li>
</navbar>



Highlight Options

Name Description
child Highlights link if URL in address bar is a child of the link. E.g foo/bar is a child of foo.
sibling Highlights link if URL in address bar is a sibling of the link. E.g foo/bar and foo/bear are siblings.
sibling-or-child Highlights link if URL in address bar is a sibling or child of the link.
exact Highlights link if URL in address bar exactly matches link.
none No highlighting.

_markbind/head/myCustomLinks.md:

<head-top>
<script src="/js/myCustomScript.js"></script>
<link rel="stylesheet" href="/css/main.css">
<link rel="stylesheet" href="/css/extra.css">

 <frontmatter>
</frontmatter>


MarkBind allows you to insert code into the <head> section of the generated HTML page, for example, to add links to custom JavaScript or CSS files.

Steps:

1. Put the code you want to insert into the <head> into a file inside the _markbind/head directory.
2. Specify the file as an attribute named head in the <frontmatter> of the page.

Example Suppose you want to insert the code below into the <head> of a page, and you have saved the code as _markbind/head/myCustomLinks.md:

<script src="/js/myCustomScript.js"></script>


To specify that you want to insert myCustomLinks.md into the <head> of myPage.html, update the front matter of the myPage.md as follows:

<frontmatter>
</frontmatter>
...


All content is inserted at the bottom of the <head> tag by default. You can use the optional <head-top> tag to specify content that should be inserted at the top of the <head> tag instead.

Example Here's how you can force the line <script ... > ... </script> to be inserted at the top of the <head> section.

<head-top>
<script src="/js/myCustomScript.js"></script>


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.

Example

<frontmatter>
</frontmatter>


If you wish to use a Layout but exclude its head file, specify head: none in the <frontmatter> of the page.

Page Layouts
<frontmatter>
layout: chapterLayout
</frontmatter>


## Page Layouts

A layout is a set of page-tweaks that can be applied to a page (or group of pages) in one go.

A layout consists of the following files:

1. A header (filename: header.md)
2. A footer (filename: footer.md)
3. Tweaks to the <head> (head.md)
4. A site navigation menu (navigation.md)
5. An expressive layout template to embed your content (page.md)
6. Custom styles (styles.css)
7. Custom scripts (scripts.js)

A layout is represented by a sub-directory in the _markbind/layouts/ containing the files listed above. The name of the layout is same as the name of the sub-directory.

To apply the layout, specify it as an attribute named layout in the <frontmatter> of each page, or in the site.json.

Example Suppose you have a layout named chapterLayout.

<root>/_markbind/layouts/
└── chapterLayout/
├── footer.md
├── page.md
├── styles.css
└── scripts.js


You can apply it to the chapter.md by setting its <frontmatter> as follows:

<frontmatter>
layout: chapterLayout
</frontmatter>
...


You can apply it to all chapter.md files by adding this entry to the site.json.

{
"glob": "**/chapter.md",
"layout": "chapterLayout"
}


The layout specified in the site.json overrides the one specified in the <frontmatter>.

Any files specified in <frontmatter> overrides the corresponding file in the layout applied.

Example Suppose a file has the following:

<frontmatter>
layout: chapterLayout
</frontmatter>
...


In this case myHead.md will override the chapterLayout/head.md.

The layout named default (if any) is automatically applied to every single page. When you init a MarkBind site, MarkBind also generates an empty default layout.

#### Using Expressive Layout Templates

In the page.md file of your layouts, it should come with the following reserved variable:

{{ MAIN_CONTENT_BODY }}

which injects the actual page content in every page. This allows you to build layouts in different ways.

Example Adding statistics formula to the bottom of every page

#### Main content of your page


  {{ MAIN_CONTENT_BODY }}
<panel header="Statistics Formula for the class" type="primary">
<img src="path_to_your_formula.png" />
</panel>


Here's how the above content would appear:

index.html

Statistics Formula for the class

<frontmatter>
pageNav: 2
</frontmatter>


A Page Navigation Menu (pageNav for short) is a fixed menu on the right edge of your page contents. You can use a pageNav to show a list of the current page's headings.

1. Specify your pageNav within the <frontmatter> of a page with The value default will use headingIndexingLevel within site.json."default" or a HTML defines six levels of headings, numbered from
1 to 6.
heading level
.
2. (Optional) You may also specify a page navigation title within <frontmatter> that will be placed at the top of the page navigation menu.

Example In the page that you want to have page navigation:

<frontmatter>
pageNav: 2
</frontmatter>


The example above will create a page navigation containing only heading levels of 1 and 2.

A pageNav has a fixed width of 300 pixels for its contents. It is responsive by design and will be completely hidden when the screen size is smaller than 1300 pixels.

Panels
<panel header="primary type panel" type="primary" >
...
</panel>


## Panels

Panel is a flexible container that supports collapsing and expanding its content. It is expandable by default.

CODE:

<panel header="This is your header for a Panel, click me to expand!">
Lorem ipsum ...
</panel>


OUTPUT:

Lorem ipsum ...

With minimized attribute, panel is minimized into an inline block element. The alt attribute is for you to specify the minimized block header.

CODE:

<panel header="How to cultivate a tomato plant at home" alt="Tomatoes" minimized>
Lorem ipsum ...
</panel>


OUTPUT:

How to cultivate a tomato plant at home

Tomatoes

Lorem ipsum ...

With expanded attribute, you can set the panels to be expanded when loaded in.

CODE:

<panel header="Have your readers click less to see the Panel's contents" expanded>
Lorem ipsum ...
</panel>


OUTPUT:

Lorem ipsum ...

Panel provides many types that change its appearance.

CODE:

<panel header="**light type panel (DEFAULT)**" type="light" minimized>
...
</panel>
<panel header="**dark type panel**" type="dark" minimized>
...
</panel>
<panel header="**primary type panel**" type="primary" minimized>
...
</panel>
<panel header="**secondary type panel**" type="secondary" minimized>
...
</panel>
<panel header="**info type panel**" type="info" minimized>
...
</panel>
<panel header="**danger type panel**" type="danger" minimized>
...
</panel>
<panel header="**warning type panel**" type="warning" minimized>
...
</panel>
<panel header="**success type panel**" type="success" minimized>
...
</panel>
<panel header="**seamless type panel**" type="seamless" minimized>
...
</panel>
<panel header="**minimal type panel**" type="minimal" minimized>
...
</panel>


OUTPUT:

light type panel (DEFAULT)

...

dark type panel

...

primary type panel

...

secondary type panel

...

info type panel

...

danger type panel

...

warning type panel

...

success type panel

...

seamless type panel

...

minimal type panel

...

Show/Hide buttons using no-switch or no-close.

CODE:

<panel header="This panel does not have a switch button" no-switch>
...
</panel>
<panel header="This panel does not have a close button" no-close>
...
</panel>
<panel header="This panel does not have either buttons" no-close no-switch>
...
</panel>


OUTPUT:

This panel does not have a switch button

...

This panel does not have a close button

...

This panel does not have either buttons

...

Use markdown in the header (only inline level markdown are supported).

CODE:

<panel header="**Bold text** :rocket: ![](https://markbind.org/images/logo-lightbackground.png =x20)" type="seamless">
...
</panel>


OUTPUT:

Bold text 🚀

...

If src attribute is provided, the panel will take content from the src specified and add it to the Panel body.

CODE:

<panel header="Content loaded in from 'src'" src="extra/loadContent.html#fragment" minimized></panel>


OUTPUT:

If popup-url attribute is provided, a popup button will be shown. If clicked, it opens the specified url in a new window.

CODE:

<panel header="Try clicking on my pop-up button" popup-url="/userGuide/syntax/extra/loadContent.html">
This panel has a popup.
</panel>


OUTPUT:

Try clicking on my pop-up button

This panel has a popup.

If preload attribute is provided, the panel body will load the HTML when the page renders instead of after being expanded.

CODE:

<panel header="Right click and inspect my HTML before expanding me!" src="extra/loadContent.html#fragment" preload>
<p>You should be able to find this text before expanding the Panel.</p>
</panel>


OUTPUT:

Right click and inspect my HTML before expanding me!

You should be able to find this text before expanding the Panel.

You can nest Panels or other components within a Panel.

CODE:

<panel header="Parent Panel">
<tip-box type="success">
I'm a nested tip-box
</tip-box>
<panel header="Level 3 Nested Panel" type="minimal">
minimal-type panel
</panel>
</panel>
</panel>
<panel header="Level 1 Nested Panel" type="info">
Some Text
</panel>
</panel>


OUTPUT:

Parent Panel

Level 1 Nested Panel

Level 2 Nested Panel

I'm a nested tip-box

Level 3 Nested Panel

minimal-type panel

Level 1 Nested Panel

Some Text

Options

Name Type Default Description
header[S] 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.
minimized Boolean false Whether Panel is minimized.
no-close Boolean false Whether to show the close button.
no-switch Boolean false Whether to show the expand switch.
bottom-switch Boolean true Whether to show an expand switch at the bottom of the panel. Independent of no-switch.
popup-url String The url that the popup window will navigate to. The url can be absolute or relative.
preload Boolean false Whether the content is loaded immediately from src.
src String The url to the remote page to be loaded as the content of the panel.
type String light The type or color scheme of the panel (single).
Supports: light, dark, primary, secondary, info, success, warning, danger, seamless, minimal.
Paragraphs
This is the first paragraph.

This is another paragraph. This is the second sentence.


## Paragraphs

Use one or more empty lines to separate paragraphs.

CODE:

This is the first paragraph.

This is another paragraph. This is the second sentence.


OUTPUT:

This is the first paragraph.

This is another paragraph. This is the second sentence.

Pictures
<pic src="https://markbind.org/images/logo-lightbackground.png" width="300" alt="Logo">
MarkBind Logo
</pic>


## Pictures

A pic component allows you to add captions below the image.

CODE:

<pic src="https://markbind.org/images/logo-lightbackground.png" width="300" alt="Logo">
MarkBind Logo
</pic>


OUTPUT:

MarkBind Logo

Options

Name Type Default Description
alt string This must be specified.
The alternative text of the image.
height string The height of the image in pixels.
src string This must be specified.
The URL of the image.
width string The width of the image in pixels.
If both width and height are specified, width takes priority over height. It is to maintain the image's aspect ratio.
Popovers
Hover over the <trigger for="pop:context-target">keyword</trigger> to see the popover.

<div slot="content">

description :+1:

</div>
</popover>


## Popovers

CODE:

<popover effect="fade" content="Lorem ipsum dolor sit amet" placement="top">
<button class="btn btn-secondary">Popover on top</button>
</popover>
<popover effect="fade" content="Lorem ipsum dolor sit amet" placement="left">
<button class="btn btn-secondary">Popover on left</button>
</popover>
<popover effect="fade" content="Lorem ipsum dolor sit amet" placement="right">
<button class="btn btn-secondary">Popover on right</button>
</popover>
<popover effect="fade" content="Lorem ipsum dolor sit amet" placement="bottom">
<button class="btn btn-secondary">Popover on bottom</button>
</popover>
<hr>
<button class="btn btn-secondary">Popover on top</button>
</popover>
<button class="btn btn-secondary">Popover on left</button>
</popover>
<button class="btn btn-secondary">Popover on right</button>
</popover>
<button class="btn btn-secondary">Popover on bottom</button>
</popover>
<hr />
<h4 class="no-index">Trigger</h4>
<p>
<button class="btn btn-secondary">Mouseenter</button>
</popover>
</p>
<h4 class="no-index">Markdown</h4>
<p>
<button class="btn btn-secondary">Hover</button>
</popover>
</p>
<h4 class="no-index">Content using slot</h4>
<div slot="content">
This is a long content...
</div>
<button class="btn btn-secondary">Hover</button>
</popover>
<br />
<br />
<h4 class="no-index">Wrap Text</h4>
<popover header="false" content="Nice!">What do you say</popover>


OUTPUT:

Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet

#### Content using slot

This is a long content...

#### Wrap Text

falseNice!What do you say

Using trigger for Popover:

CODE:

More about <trigger for="pop:trigger_id">trigger</trigger>.
<popover id="pop:trigger_id" content="This popover is triggered by a trigger"></popover>
<br>
This is the same <trigger for="pop:trigger_id">trigger</trigger> as last one.


OUTPUT:

More about trigger. This popover is triggered by a trigger
This is the same trigger as last one.

Triggers

Trigger provides more flexibility in triggering contextual overlay via Tooltip, Popover or Modal.

You could embed a Trigger within the text, and define the Tooltip, Popover or Modal at a separate location, which allows for a cleaner authoring flow.

Specify the id attribute on the Tooltip, Popover or Modal component, and use the same id in the for attribute of the Trigger to allow the Trigger to invoke the specific overlay elements. Additionally, multiple Triggers could share the same overlay by providing them with the same id.

Trigger's trigger attribute (which defaults to hover) is independent of the target's.

Options

Name Type Default Description
trigger String hover How the overlay view is triggered.
Supports: click, focus, hover.
for String null The id for the overlay view to be shown.
placement String auto How to position the Popover or Tooltip.
Supports: auto, top, left, right, bottom.

Options

Name Type Default Description
trigger String hover How the Popover is triggered.
Supports: click, focus, hover.
title
(deprecated)
String '' Popover header, supports inline markdown text.
content String '' Popover content, supports inline markdown text.
placement String top How to position the Popover.
Supports: top, left, right, bottom.
Questions and Quizzes
MCQ and Checkbox questions
<!-- use type="checkbox" for checkbox questions -->
<question type="mcq" header="Which of these **contradicts** the heuristics recommended when creating test cases with multiple inputs?">
<!-- Insert the reason for the option using the reason attribute -->
<q-option reason="This is **correct**. We need to figure out if a positive test case works!">
Each valid test input should appear at least once in a test case that doesn’t have any invalid inputs.
</q-option>
<q-option>
It is ok to combine valid values for different inputs.
</q-option>
<q-option>
No more than one invalid test input should be in a given test case.
</q-option>
<!-- Use the 'correct' attribute to indicate an option as correct. -->
<q-option correct>
All invalid test inputs must be tested together.
<!-- Optionally, you may use a reason slot instead of a reason attribute. -->
<div slot="reason">
If you test all invalid test inputs together, you will not know if each one of the invalid inputs are handled
correctly by the SUT.
This is because most SUTs return an error message upon encountering the first invalid input.
</div>
</q-option>
<div slot="hint">
How do you figure out which inputs are wrong? (or correct)
</div>
</question>

Text questions
<question type="text" header="Which country did the Hawaiian pizza originate from?"
keywords="hawaii" threshold="0.5" answer="It originated from Hawaii!">
<div slot="hint">

Watch some pizza commercials! :tv:

:pizza: :pizza: :pizza: :pizza: :pizza: :pizza: :pizza: :pizza: :pizza: :pizza: :pizza: :pizza:
</div>
</question>

Quiz
<quiz>
<question type="mcq">...</question>
<question type="checkbox">...</question>
<question type="text">...</question>
</quiz>


## Questions and Quizzes

Question and quiz components provide an easy way to test readers on the relevant content topic in the page.

#### Introduction

Question components (<question>) can be one of the following types: MCQ, Checkbox or Text.

In all cases, content directly inserted in between <question>...</question> will be inserted into the question body.

You can also insert markdown into the header or hint box, by using the header and hint attributes respectively. Click the hint button below to see how the hint box turns out!

CODE:

<!-- Insert markdown into the header and hint using the respective attributes -->
<question type="checkbox" header="Which of the following is correct?" hint="Think out of the box! :fas-box:">

<!-- Anything you place directly under a question not in a slot is inserted into the question body! -->
</small>
</pic>

<!-- Several hidden checkbox q-option components explained later -->
</question>


OUTPUT:

Think out of the box!

Which of the following is correct?

Multiply the numbers on the left together and add the leftmost number!

96

Under normal circumstances, this would be correct.

19

Simply add the running sum of the results as well!

40
811

If you require more expressive formatting for your header or hint markup, you can use the <div slot="header"> and <div slot="hint"> slots. Expand the panel below to see an example!

Header and Hint example with slots

CODE:

<question type="checkbox" header="Which of the following is true?" hint="Think out of the box! :fas-box:">

Which of the following is correct?

Challenge: Try to get all the answers on your first try! :star: :star:
</div>

<pic src="/images/math-question.jpg" alt="math question image" height="200" class="d-block mx-auto">

</small>
</pic>

<!-- Several hidden checkbox q-option components explained later -->

<!-- Hint slot -->
<div slot="hint">

Think out of the box! :fas-box:

Need another hint? <tooltip content="Two of the answers are correct!">Hover over me!</tooltip> :fas-mouse-pointer:
</div>
</question>


OUTPUT:

Which of the following is correct?

Challenge: Try to get all the answers on your first try! ⭐️ ⭐️

Multiply the numbers on the left together and add the leftmost number!

96

Under normal circumstances, this would be correct.

19

Simply add the running sum of the results as well!

40
811

Think out of the box!

Need another hint? Two of the answers are correct!Hover over me!

Placing the question into the header is entirely optional. You may also wish to include the question directly in the question body, omitting the header entirely.

Options and Slots common to all question types

Name Type Default Description
type String '' The type of question. Supports mcq, checkbox or text.
header[S] String '' The markup to insert into the question header. The header is omitted if this is not provided.
hint[S] String '' The content to display in the hint box.

#### MCQ and Checkbox Questions

MCQ and checkbox questions are indicated with the type="mcq" or type="checkbox" attribute.

In both instances, you can include the possible answers using the <q-option> component, placed anywhere inside the if you wish, you could place it in the header mentioned above as well!question. To indicate the correct option(s), add the <q-option correct> attribute.

Optionally, you can provide the reason for the particular option using the <q-option reason="..."> attribute, or the <div slot="reason"> slot for more expressive formatting, similar to the hint and header options and slots.

MCQ Questions

CODE:

<question type="mcq" header="Which of these **contradicts** the heuristics recommended when creating test cases with multiple inputs?">
<!-- Insert the reason for the option using the reason attribute -->
<q-option reason="This is **correct**. We need to figure out if a positive test case works!">
Each valid test input should appear at least once in a test case that doesn’t have any invalid inputs.
</q-option>
<q-option>
It is ok to combine valid values for different inputs.
</q-option>
<q-option>
No more than one invalid test input should be in a given test case.
</q-option>
<!-- Use the 'correct' attribute to indicate an option as correct. -->
<q-option correct>
All invalid test inputs must be tested together.
<!-- Optionally, you may use a reason slot instead of a reason attribute. -->
<div slot="reason">
If you test all invalid test inputs together, you will not know if each one of the invalid inputs are handled
correctly by the SUT.
This is because most SUTs return an error message upon encountering the first invalid input.
</div>
</q-option>
<div slot="hint">
How do you figure out which inputs are wrong? (or correct)
</div>
</question>


OUTPUT:

Which of these contradicts the heuristics recommended when creating test cases with multiple inputs?

This is correct. We need to figure out if a positive test case works!

Each valid test input should appear at least once in a test case that doesn’t have any invalid inputs.
It is ok to combine valid values for different inputs. No more than one invalid test input should be in a given test case. All invalid test inputs must be tested together.
If you test all invalid test inputs together, you will not know if each one of the invalid inputs are handled correctly by the SUT. This is because most SUTs return an error message upon encountering the first invalid input.
How do you figure out which inputs are wrong? (or correct)

MCQ questions can have multiple correct options!

Checkbox Questions

CODE:

<question type="checkbox" hint="Use your calculator! :fas-calculator:">

##### Which of the following is true?

<br>
<q-option reason="lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum">
1 + 1 = 11
</q-option>
<q-option reason="Division by zero is **undefined**!">
1 / 0 = infinity
</q-option>
<q-option correct>
11 / 11 = 1
</q-option>
</question>


OUTPUT:

##### Which of the following is true?

lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum

1 + 1 = 11

Division by zero is undefined!

1 / 0 = infinity
11 / 11 = 1

q-option Options and Slots

Name Type Default Description
correct Boolean false Whether this option (placed under either a MCQ or checkbox question) is correct. You may have multiple correct answers in either case.
reason[S] String '' The explanation markup to display for the option once the answer is checked.

#### Text Questions

Text questions are specified with the type="text" attribute.

Unlike MCQ and checkbox questions, answer checking is performed by providing keywords to check for in the user's answer through the keywords attribute. If no keywords are provided, the answer will always be marked as correct when placed in quizzes.

Keywords are validated by simply looking for the keyword as a pattern in the user's answer! This works well for some When does validation work?cases

When the keywords specified are rather long (eg. requirements), it reduces the chance that this keyword can be mistakenly validated.

In contrast, something short and common like take which can easily be part of another word (eg. mis-take-nly) would be mistakenly validated.
and not others.

You can provide your answer in the answer attribute, or similarly, the <div slot="answer"> slot for more expressive formatting.

CODE:

<question type="text" header="Which country did the Hawaiian pizza originate from?"
keywords="hawaii" threshold="0.5" answer="It originated from Hawaii!">
<div slot="hint">

Watch some pizza commercials! :tv:

:pizza: :pizza: :pizza: :pizza: :pizza: :pizza: :pizza: :pizza: :pizza: :pizza: :pizza: :pizza:
</div>
</question>


OUTPUT:

It originated from Hawaii!

Which country did the Hawaiian pizza originate from?

Watch some pizza commercials! 📺

🍕 🍕 🍕 🍕 🍕 🍕 🍕 🍕 🍕 🍕 🍕 🍕

Since the validation is imperfect, the minimum proportion of keywords that need to be matched can also be changed using the threshold attribute.

If you don't want to validate the answer at all, you may also omit the keywords attribute entirely. Doing so also always marks the question as correct inside quizzes.

Text Question specific Options and Slots

Name Type Default Description
keywords String '' Comma delimited string of keywords or phrases to match the user's answer against.
threshold Number 0.5 Minimum proportion of keywords that have to be matched in the user's answer for the answer to be marked as correct.
answer[S] String '' The answer or explanation to display when the user clicks the check button.

Deprecation notes

• The old has-input attributes translate to type="text", but will be deprecated in a future version.
• <question>s without a type (or an unrecognised one) will always be marked correct when placed in quizzes.

#### Quizzes

You can also build a series of questions out of multiple <question> components.

Simply place the <question> components you want to include into the <quiz> component! No extra configuration is needed.

CODE:

<quiz>
<question type="mcq">...</question>
<question type="checkbox">...</question>
<question type="text">...</question>
</quiz>


OUTPUT:

Which of these contradicts the heuristics recommended when creating test cases with multiple inputs?

This is correct. We need to figure out if a positive test case works!

Each valid test input should appear at least once in a test case that doesn’t have any invalid inputs.
It is ok to combine valid values for different inputs. No more than one invalid test input should be in a given test case. All invalid test inputs must be tested together.
If you test all invalid test inputs together, you will not know if each one of the invalid inputs are handled correctly by the SUT. This is because most SUTs return an error message upon encountering the first invalid input.
How do you figure out which inputs are wrong? (or correct)

##### Which of the following is true?

lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum

1 + 1 = 11

Division by zero is undefined!

1 / 0 = infinity
11 / 11 = 1

It originated from Hawaii!

Which country did the Hawaiian pizza originate from?

Watch some pizza commercials! 📺

🍕 🍕 🍕 🍕 🍕 🍕 🍕 🍕 🍕 🍕 🍕 🍕

Quiz Options and Slots

Name Type Default Description
intro String '' Quiz intro markup above the question count.
intro Slot Click start to begin Quiz intro markup. Overrides the intro attribute if both are present.
Search Bars
<searchbar :data="searchData" placeholder="Search" :on-hit="searchCallback" menu-align-right></searchbar>

<li slot="right">
<form class="navbar-form">
<searchbar :data="searchData" placeholder="Search" :on-hit="searchCallback"></searchbar>
</form>
</li>


## Search Bars

The searchbar component allows users to search all headings within any page on the site.

CODE:

<searchbar :data="searchData" placeholder="Search" :on-hit="searchCallback"></searchbar>
<searchbar :data="searchData" placeholder="Search (Right-aligned dropdown)" :on-hit="searchCallback" menu-align-right></searchbar>


To use the searchbar within a navbar, add the following markup to your file. The searchbar can be positioned using the slot attribute for the list. The following markup adds a searchbar to the right side of the navbar with appropriate styling.

<li slot="right">
<form class="navbar-form">
<searchbar :data="searchData" placeholder="Search" :on-hit="searchCallback"></searchbar>
</form>
</li>


OUTPUT:

Enter a search term (eg. 'search bar') to see the search result dropdown.

Options

Name Type Default Description
algolia Boolean false Whether the searchbar should be connected to Algolia DocSearch.
data Array The local data source for suggestions. Expected to be a primitive array. To use MarkBind's search functionality, set this value to "searchData".
menu-align-right Boolean false Whether the search bar's dropdown list will be right-aligned.
on-hit Function A callback function when you click or hit return on an item. To use MarkBind's search functionality, set this value to "searchCallback".
placeholder String '' The placeholder text shown when no keywords are entered in the search bar.

Note: If you are using MarkBind's search functionality, then enableSearch must be set to true in site.json.

Related topic: User Guide: Making the Site Searchable.

# Site Map
* [:house: Home](/index.html)
* Docs :expanded:
* [User Guide](/ug.html)
* [Dev Guide](/dg.html)
* [Search](/search.html)

<frontmatter>
siteNav: mySiteNav.md
</frontmatter>
...


A Site Navigation Menu (siteNav for short) is a fixed menu on the left edge of a page, that can be used to show a road map of the main pages of your site.

1. Format your siteNav as an unordered Markdown list and save it inside the _markbind/navigation directory.
2. Specify the file as the value of the siteNav attribute in the <frontmatter> of the page.

Example Here is an example siteNav code saved in _markbind/navigation/mySiteNav.md file:

* [:house: Home](/index.html)
* ---
* Docs
* [User Guide](/ug.html)
* [Dev Guide](/dg.html)
* [Search](/search.html)
* [Contact](/contact.html)


Here's how another page can make use of the above siteNav:

<frontmatter>
siteNav: mySiteNav.md
</frontmatter>
...


And here's how the above siteNav would appear:

MarkBind has styles nested lists with additional padding and smaller text sizes up to 4 nesting levels. Beyond that, you'd have to include your own styles!

More than one siteNav file can be in _markbind/navigation/ directory but a page may not have more than one siteNav.

A siteNav has a fixed width of 300 pixels for its contents. A siteNav is responsive in that it will collapse to a menu button when the screen width is smaller than 992 pixels. It will then be completely hidden when the screen size is smaller than 576 pixels.

If you wish to use a Layout but exclude its navigation file, specify siteNav: none in the <frontmatter> of the page.

#### Expanding menu items by default

You can append the :expanded: to a a menu item with sub menu-itemsparent menu item to make it expand by default. In the example above, * Docs :expanded: will make the menu item Docs expand by default.

A parent menu item that is also linked will not be collapsible e.g., the Search menu item in the above example.

#### Additional content in site navs

You may have additional HTML and Markdown content in a the file containing the code for a site navigation menu, e.g., mySiteNav.md in the example abovesiteNav file, in which case the code for the siteNav should be enclosed in a <navigation> tag. There should only be one <navigation> tag in the file.

Example To include a heading for the site nav,

# Site Map

* [:house: Home](/index.html)
* ---
* Docs
...


You can also include additional content between navigation items, such as horizontal dividers. Just be sure to include it as a list item as well!

Example Inserting a horizontal divider:

* [:house: Home](/index.html)
* ---
* Docs
...

Tables
Animal | Trainable?| Price | Remarks
:----- | :-------: | ----: | ----
Ants   | no        | 5     |
Bees   | no        | 20    |
Cats|yes|100|


## Tables

CODE:

Animal | Trainable?| Price | Remarks
:----- | :-------: | ----: | ----
Ants   | no        | 5     |
Bees   | no        | 20    |
Cats|yes|100|


OUTPUT:

Animal Trainable? Price Remarks
Ants no 5
Bees no 20
Cats yes 100
• Colons (:) in the 2nd line are optional and they indicates whether to left/center/right-align the values in that column.
• There is no need to align pipe symbols to be on a vertical line; it's just for aesthetic purposes only.

Tabs
<tabs>
Content of the first tab
</tab>
Contents of the second tab
</tab>
</tab>
Some stuff about the moon ...
</tab>
</tab-group>
</tabs>


## Tabs

CODE:

<tabs>
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla ullamcorper ultrices lobortis.
</tab>
<tab header="Disabled second tab :x:" disabled>
</tab>
</tab>
</tab>
</tab-group>
<tab-group header="Disabled fourth tab group" disabled>
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla ullamcorper ultrices lobortis.
</tab>
</tab-group>
</tabs>


OUTPUT:

First tab
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla ullamcorper ultrices lobortis.
Disabled second tab ❌
Third tab group 🌌
Stars ⭐️
Disabled Moon 🌑
Disabled fourth tab group
Hidden tab
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla ullamcorper ultrices lobortis.

Options

tabs:

Name Type Default Description
active Number 0 Active Tab index (0-based)

tab:

Name Type Default Description
header String null Tab title.
disabled Boolean false Whether Tab is clickable and can be activated.

tab-group:

Name Type Default Description
header String null Tab Group title.
disabled Boolean false Whether Tab Group is clickable and can be activated.
Tags
<p tags="language--java advanced">System.out.println("Hello world");</p>
<p tags="language--C# basic">Console.WriteLine("Hello world");</p>

<frontmatter>
title: "Hello World"
tags: ["language--java"]
</frontmatter>


### Plugin: Tags

With this plugin you can use tags to selectively filter content when building a site.

#### Toggling alternative contents

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.

Example Attaching tags to elements:

# Print 'Hello world'

<p tags="language--java">System.out.println("Hello world");</p>
<p tags="language--C#">Console.WriteLine("Hello world");</p>
<p tags="language--python">print("Hello world")</p>


You need to specify the tags to include in the pluginsContext, under tags:

{
...
"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.

Example Attaching multiple tags to an element:

# For loops

<p tags="language--java language--C#">for (int i = 0; i < 5; i++) { ... }</p>


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.

Example Specifying tags in front matter:

<frontmatter>
title: "Hello World"
tags: ["language--java"]
</frontmatter>


Tags in site.json will be merged with the ones in the front matter, and are processed after front matter tags. See Hiding Tags for more information.

You can use a * in a tag name to match elements more generally. A * in a tag will match any number of characters at its position.

Example Using general tags:

<frontmatter>
title: "Hello World"
tags: ["language--*"]
</frontmatter>

<p tags="language--java">System.out.println("Hello world");</p>
<p tags="language--C#">Console.WriteLine("Hello world");</p>
<p tags="language--python">print("Hello world")</p>


All 3 <p>s will be shown.

#### Hiding Tags

Using - at the start of a tag hides all tags matching the expression. This is helpful for disabling a group of tags and enabling a particular tag.

Example Using general tags:

<frontmatter>
title: "Hello World"
tags: ["language--java"]
</frontmatter>

<p tags="language--java">System.out.println("Hello world");</p>
<p tags="language--C#">Console.WriteLine("Hello world");</p>
<p tags="language--python">print("Hello world")</p>

site.json
{
...
"plugins" : [
"filterTags"
],
"pluginsContext" : {
"filterTags" : {
"tags": ["-language--*", "language--C#"]
}
}
}


language--java is overridden by -language--*, so only language--C# is shown.

This only works because tags are processed left to right, so all language--* tags are hidden before language--C#. Tags in site.json are processed after tags in <frontmatter>.

Text Styles
**Bold**, _Italic_, ___Bold and Italic___, Inline Code
~~Strike through~~, ****Super Bold****, !!Underline!!, ==Highlight==, %%Dim%%, Super^script^, Sub~script~


## Text Styles

Markdown text styles:

CODE:

**Bold**, _Italic_, ___Bold and Italic___, Inline Code


OUTPUT:

Bold, Italic, Bold and Italic, Inline Code

CODE:

~~Strike through~~


OUTPUT:

Strike through

CODE:

****Super Bold****, !!Underline!!, ==Highlight==, %%Dim%%, Super^script^, Sub~script~


OUTPUT:

Super Bold, Underline, Highlight, Dim, Superscript, Subscript

Alternative syntax: https://www.markdownguide.org/basic-syntax#emphasis

Thumbnails
<thumb circle src="https://markbind.org/images/logo-lightbackground.png" size="100"/>


## Thumbnails

A thumbnail component allows you to insert thumbnails using text, images, or icons.

CODE:

<thumbnail circle src="../../images/deer.jpg" size="100"/>
<thumbnail circle text=":book:" background="#dff5ff" size="100"/>
<thumbnail circle text="___CS___" background="#333" font-color="white" size="100"/>
<thumbnail circle text=":fas-book:" font-color="darkgreen" border="3px solid darkgreen" size="100"/>

<thumbnail src="../../images/deer.jpg" size="100"/>
<thumbnail text=":book:" background="#dff5ff" size="100"/>
<thumbnail text="___CS___" background="#333" font-color="white" size="100"/>
<thumbnail text=":fas-book:" font-color="darkgreen" border="3px solid darkgreen" size="100"/>


OUTPUT:

📖 CS

📖 CS

Options

Name Type Default Description
alt string This must be specified if src is specified
The alternative text of the image.
background string Specifies the background color.
Accepts any valid CSS background property
border string Specifies the border thickness, type, and color.
Accepts any valid CSS border property
circle boolean false If this option is enabled, the thumbnail will be circle shaped instead of square
font-color string The color of the text, affects normal text and icons (but not emojis)
font-size string Text size, defaults to half of size, affects text, icons and emojis
size string 100 The size of the thumbnail in pixels
src string The URL of the image.
text string The text to use in the thumbnail, icons, emojis and markdown are supported here

If both text and src are specified, src will take higher priority.

Tooltips
Hover <tooltip content="An explanation, **supports simple Markdown**">here</tooltip> to see a tooltip.


## Tooltips

CODE:

<tooltip content="Lorem ipsum dolor sit amet" placement="top">
<button class="btn btn-secondary">Popover on top</button>
</tooltip>
<tooltip content="Lorem ipsum dolor sit amet" placement="left">
<button class="btn btn-secondary">Popover on left</button>
</tooltip>
<tooltip content="Lorem ipsum dolor sit amet" placement="right">
<button class="btn btn-secondary">Popover on right</button>
</tooltip>
<tooltip content="Lorem ipsum dolor sit amet" placement="bottom">
<button class="btn btn-secondary">Popover on bottom</button>
</tooltip>
<hr />
Trigger
<p>
<tooltip content="Lorem ipsum dolor sit amet" placement="top" trigger="click">
<button class="btn btn-secondary">Click</button>
</tooltip>
<br />
<br />
<tooltip content="Lorem ipsum dolor sit amet" placement="top" trigger="focus">
<input placeholder="Focus"></input>
</tooltip>
</p>

**Markdown**:
<tooltip content="*Hello* **World**">
<a href="">Hover me</a>
</tooltip>
<br />

**Free Text**:
<tooltip content="coupling is the degree of interdependence between software modules; a measure of how closely connected two routines or modules are; the strength of the relationships between modules."><i>coupling</i></tooltip>


OUTPUT:

Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet
Trigger

Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet

Markdown: Hello World Hover me

Free Text: coupling is the degree of interdependence between software modules; a measure of how closely connected two routines or modules are; the strength of the relationships between modules.coupling

Using trigger for Tooltip:

CODE:

More about <trigger for="tt:trigger_id">trigger</trigger>.
<tooltip id="tt:trigger_id" content="This tooltip triggered by a trigger"></tooltip>
<br>
This is the same <trigger for="tt:trigger_id">trigger</trigger> as last one.


OUTPUT:

More about trigger. This tooltip triggered by a trigger
This is the same trigger as last one.

Triggers

Trigger provides more flexibility in triggering contextual overlay via Tooltip, Popover or Modal.

You could embed a Trigger within the text, and define the Tooltip, Popover or Modal at a separate location, which allows for a cleaner authoring flow.

Specify the id attribute on the Tooltip, Popover or Modal component, and use the same id in the for attribute of the Trigger to allow the Trigger to invoke the specific overlay elements. Additionally, multiple Triggers could share the same overlay by providing them with the same id.

Trigger's trigger attribute (which defaults to hover) is independent of the target's.

Options

Name Type Default Description
trigger String hover How the overlay view is triggered.
Supports: click, focus, hover.
for String null The id for the overlay view to be shown.
placement String auto How to position the Popover or Tooltip.
Supports: auto, top, left, right, bottom.

Options

Name Type Default Description
trigger String hover How the tooltip is triggered.
Supports: click, focus, hover.
content String '' Text content of the tooltip.
placement String top How to position the tooltip.
Supports: top, left, right, bottom.

Variables

Global variables:

_markbind/variables.md:

<variable name="year">2018</span>


The year was {{ year }}.

Page variables:
<variable name="full_name">John Doe</variable>

The name was {{ full_name }}.

## Variables

MarkBind variables are ideal for reusing small bits of code in multiple places; you can define a variable to represent the code bit in question and reuse it anywhere in the site by referring the variable instead of duplicating the code bit.

### Global Variables

Global variables are to be defined in the _markbind/variables.md file. Each variable must have an name and the value can be any MarkBind-compliant code fragment. The name should not contain - and .. For example, search-option and search.options are not allowed.

The variables declared here are available from anywhere in the code base.

Example Here's how you can define two variables year and options:

<variable name="year">2018</variable>

<variable name="options">
* yes
* no
* maybe
</variable>


To include a variable value in your code, give the variable id enclosed in double curly braces.

Example The year was {{ year }}. The year was 2018.

#### Default values for variables

You can also specify a default value for a variable, which is displayed when the variable is not specified in variables.md and by any of the includes of the page. This is done by adding or defaultValue within the curly braces.

Example My name is {{ name or "Anonymous" }}. My name is Anonymous.

#### Built-in Global Variables

MarkBind also provides a number of built-in variables.

Variable Notes Example Output
baseUrl Represents the root directory of the site on the server, as configured in your site configuration file.
If baseUrl is specified as userGuide/:

<img src="{{baseUrl}}/images/logo.png" />
<img src="userGuide/images/logo.png" />
timestamp The time stamp that indicates when the page was generated.

The default values of "timeZone" and "locale" are "UTC" and "en-GB" respectively.
The following example showcases the use of the "Asia/Singapore" time zone.

Page generated at: {{timestamp}}
Page generated at: Fri, Mar 19, 2021, 2:24:17 PM UTC
MarkBind The MarkBind version in use, linked to the MarkBind website. Page generated by: {{MarkBind}} Page generated by: MarkBind 2.18.1

### Page Variables

You can also declare variables for use within a single page. These variables work exactly the same as regular variables, except that their values only apply to the page they are declared in. This can be done by using the <variable> tag.

Example Declaring page variables: <variable name="full_name">John Doe</variable>

Example Using page variables: My name is {{ full_name }}. This is {{ full_name }}'s site.

These variables will not be applied to <include> files. Additionally, global variables (_markbind/variables.md) will take precedence over any page variables. See also: Specifying Variables in an <include>.

### Importing Variables

You can access page variables from another page by importing them.

Example Importing specific variables from person.md into coverpage.md:

In person.md,

<variable name="address">123 Sun Avenue</variable>
<variable name="name">Mark</variable>
<variable name="phone">123456789</variable>


and in coverpage.md,

<import address name from="person.md"/>


will allow you to access the variables as per normal: {{address}}, {{name}}, {{phone}}.

When importing all variables, you should attach a namespace to the imported variables using an as attributes.

Example Importing all variables with namespaces:

In coverpage.md,

<import from="page.md" as="details"/>

Detail How to access
address {{details.address}}
name {{details.name}}
phone {{details.phone}}

This way, all variables in page.md are accessible via {{details.<variable_name>}}.

Mixing namespaces with variable names

You can also mix the two syntaxes for importing page variables, though it is not recommended:

<import address name from="page.md" as="details"/>


This may seem like it will import only address and name from page.md and storing them in the namespace details.

However, this is a combination of both syntaxes above, and thus this will allow you to:

• access address and name (but NOT phone) with {{address}} and {{name}}
• access address, name, and phone with {{details.address}}, {{details.name}}, and {{details.phone}}

Precedence of imported variables

Note that global variables (_markbind/variables.md) and page variables will take precedence over any imported variables.

This also applies for namespaces for instance, in the earlier example, details is treated as the variable name and is subject to the same rules as other variables, such as global variables taking precedence, and later declarations overriding previous ones:

<import from="title.md" as="book"/>
<import from="index.md" as="book"/>


In this case, all the variables in title.md are not accessible, as they are overwritten with the variables from index.md.

#### Importing variables from other external file formats

You can also source variables from external files using MarkBind's {% ext varName = "filepathToFile" %} Nunjucks extension. This is useful if you have external datasets you want to display in your site!

To do so, assign a root variable name (varName) to the file path from the similar to how you assign filepaths for other Nunjucks tagsroot directory of the site. You may then access the file's variables using dot varName.xx or array varName[i] syntax, depending on the file's contents.

Example

CODE:

Displaying a student scoreboard stored as JSON
{% ext studentScoreboard = "userGuide/syntax/extra/scoreboard.json" %}

Student Number | Score | Rank
:----- | :-------: | ----
{% for student in studentScoreboard.students -%}
{{ student.number }} | {{ student.score }} | {{ student.rank }}
{% endfor %}

<small>Last updated at {{ studentScoreboard.lastUpdated }}</small>


Json file used in example

Json File
{
"lastUpdated": "21 November, 2020",
"students": [
{
"number": "A1234567X",
"score": 87,
"rank": 1
},
{
"number": "A1234123U",
"score": 60,
"rank": 3
},
{
"number": "A9876543L",
"score": 76,
"rank": 2
}
]
}


OUTPUT:

Student Number Score Rank
A1234567X 87 / 100 1
A1234123U 60 / 100 3
A9876543L 76 / 100 2

Last updated at 21 November, 2020

Only .json files are supported for now.

##### Old syntax (deprecated)

You could also have your variables defined in a JSON file to define multiple variables in a more concise manner.

Example globally scoped variables variables.md:

<variable from="PATH_TO_VARIABLE.json" />


variables.json:

{
"variable1": "This is the first variable",
"variable2": "This is the second variable"
}


Variables defined in a .json file will be scoped according to where it is being referenced. Json variables referenced in variables.md would be globally scoped like other global variables in that file.

Example locally scoped variables in index.md:

<variable from="PATH_TO_VARIABLE.json" />


In this case, json variables referenced within index.md would be a page variable accessible within the page index.md.

### Tips and Tricks for variables

##### Referring to other variables in variables

This variable uses a built-in variable:
<variable name="time">{{ timestamp }}</variable>

Here, the second variable will be assigned the contents of the first variable.
<variable name="first">This is the first variable.</variable>
<variable name="second">{{ first }}</variable>

This will not work, as the fourth variable is declared below the line that refers to it.
<variable name="third">{{ fourth }}</variable>
<variable name="fourth">This is the fourth variable.</variable>

##### Variables can contain malformed html

MarkBind uses a patched version of the excellent htmlparser2 that allows <variable> tags to contain any content - even incomplete or malformed html!

Example You can use this to build html from incomplete html code snippets:

<variable name="front_center"><div style="text-align: center;"></variable>
<variable name="front_right"><div style="text-align: right;"></variable>
<variable name="back"></div></variable>


And to use it:

Example {{ front_center | safe }} centered {{ back | safe }}

centered

Example {{ front_right | safe }} right aligned {{ back | safe }}

right aligned

Remember to also use the safe nunjucks filter when rendering your variables as raw html!

1. Here is the footnote. Footnotes will appear at the bottom of the page.

2. Here's one with multiple blocks.

Subsequent paragraphs are indented to show that they belong to the previous footnote.

3. Inlines notes are easier to write, since you don't have to pick an identifier and move down to type the note.

Here is the footnote. Footnotes will appear at the bottom of the page.

Here's one with multiple blocks.

Subsequent paragraphs are indented to show that they belong to the previous footnote.

Inlines notes are easier to write, since you don't have to pick an identifier and move down to type the note.