MarkBind source files can be as simple as basic Markdown, but you can also use a mix of several popular syntax schemes (, Bootstrap, Nunjucks, etc. as well as MarkBind's own custom syntax) to create more dynamic content that you cannot normally get from a typical markdown-to-html site generator.
The example paragraph below has the following dynamic elements: a tooltip, a popover, and a modal. Hover/click on the underlined words to see each.
In , a binary tree is a tree data structure in which each node has at most two children, which are referred to as the left child and the right child. Primitive data types on the other hand ...
More examples of generating dynamic content
Everything you need for text-heavy websites, built-in.
MarkBind is highly optimized for creating text-heavy websitese.g., eLearning websites, online instruction manuals, project documentation etc. Anything that you might need for creating such websites are built-in, sparing you the hassle of finding/installing/searching plugins that you need.
Here are some examples:
Icons can improve the readability of a text-heavy document. MarkBind comes with a wide selection of icons and emoji. With MarkBind's search feature, you can allow readers to search for keywords in your site. MarkBind allows you to add site/page navigation menus, headers, footers easily.
More control to the reader, without duplicating code.
A MarkBind website can be a buffet of content, as opposed to a set menu: a site can have optional contents that the reader can access at her discretion, and the same content can be organized in multiple ways so that the reader can choose the one that fits the need. To cater (pun intended) for creating such buffet style websites, MarkBind has reuse mechanisms for presenting the same content in multiple ways without duplicating the source file.
For example, MarkBind has a powerful include mechanism that allows content fragments (i.e., a file or part of a file) to be reused at multiple places in the website. In the example below, both the modal and the expandable panel reuse the same content originating from a single source file.
In CS, a binary tree is a tree data structure in which each node has at most two children, which are referred to as the left child and the right child. Primitive data types on the other hand ...
Some example primitive data types
Easy to set up, modify, deploy, integrate.
Installing MarkBind takes just one command. Creating a new MarkBind site too takes just one command. With MarkBind's live preview feature, you can see how your site will look like as you modify the source file. Deploying the site to a server can be as simple as one command too.
Most component attributes allow a richer form of formatting using slots, denoted by an attribute[S] superscript in the respective components' tables.
In other cases, when the option is of type "Slot", only the slot option is available.
You can define such a slot within the component by adding a slot="slot_name" attribute to any element within the slot.
Example
CODE:
<panelexpanded>
@@ -43,7 +43,7 @@
As shown in this panel, using the header slot
allows you to customize the Panel's header using HTML.
</panel>
-
+
@@ -59,10 +59,10 @@
-
OUTPUT:
RAINBOW
+
OUTPUT:
RAINBOW
As shown in this panel, using the header slot
allows you to customize the Panel's header using HTML.
-
Other examples of slots in use
Example Custom modal header
CODE:
<triggerfor="modal:tip-example"trigger="click">Click here to show Modal.</trigger>
+
Other examples of slots in use
Example Custom modal header
CODE:
<triggerfor="modal:tip-example"trigger="click">Click here to show Modal.</trigger><modalid="modal:tip-example"><spanslot="header"class="modal-title text-center">
@@ -73,7 +73,7 @@
<spanstyle="font-size:10pt">Tiny <spanstyle="color:green;">footer</span></span></span></modal>
-
+
@@ -89,11 +89,11 @@
-
OUTPUT:
Click here to show Modal.
Example Override the default icon for a certain type of box.
<boxtype="info">
+
OUTPUT:
Click here to show Modal.
Example Override the default icon for a certain type of box.
<boxtype="info"><spanslot="icon"class="text-danger"><md>:fas-home:</md></span> info
</box>
-
+
@@ -109,13 +109,13 @@
-
+
info
Example Use pictures (or even gifs) as the icon for a box.
<boxtype="info"seamless><imgslot="icon"src="https://icons8.com/vue-static/landings/animated-icons/icons/cloud/cloud.gif"></img> some very useful info
</box>
-
<boxtype="info"light><thumbnailcircleslot="icon"text=":book:"background="#dff5ff"size="50"/> use thumbnail as the icon
</box>
-
+
@@ -153,31 +153,31 @@
-
π
+
π
use thumbnail as the icon
Inserting custom classes into components
Every component documented in our user guide allows you to insert your own defined CSS classes.
-This is done by adding the add-class attribute to a component along with the desired class names.
Example
+This is done by adding the add-class attribute to a component along with the desired class names.
Example
Easily apply Bootstrap classes without using a wrapper!
-
Markup
<boxtype="info"add-class="lead font-italic text-center">
- Easily apply Bootstrap classes without using a wrapper!
-</box>
-
-
+
Markup
<boxtype="info"add-class="lead font-italic text-center">
+ Easily apply Bootstrap classes without using a wrapper!
+</box>
+
+
-
-
+
+
+ 5.453125 4.089844 L 13.453125 4.089844 Z M 13.453125 13.636719 " data-v-0eabf1c4>
The image components here provide convenient syntax & styling abstractions on top of raw HTML and Markdown images.
-Diagrams, in the form of inline PlantUML components are also supported.
Pictures
A pic component allows you to add captions below the image.
CODE:
<picsrc="https://markbind.org/images/logo-lightbackground.png"width="300"alt="Logo">
+Diagrams, in the form of inline PlantUML components are also supported.
Pictures
A pic component allows you to add captions below the image.
CODE:
<picsrc="https://markbind.org/images/logo-lightbackground.png"width="300"alt="Logo"lazy> MarkBind Logo
</pic>
-
+
@@ -47,12 +47,12 @@
-
OUTPUT:
+
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. The URL can be specified as absolute or relative references. More info in: Intra-Site Links
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.
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. The URL can be specified as absolute or relative references. More info in: Intra-Site Links
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.
lazy
boolean
false
The <pic> component lazy loads if this attribute is specified. Either the height or width should be specified to avoid layout shifts while lazy loading images.
<picsrc="https://markbind.org/images/logo-lightbackground.png"width="300"alt="Logo"lazy> MarkBind Logo
</pic>
-
+
@@ -68,10 +68,10 @@
-
+
MarkBind Logo
Annotations
An annotate component allows you to easily annotate over any images.
Annotate wrappers (<annotate>) are used in conjunction with Annotate
-Points (<a-point>).
<annotate>: Annotate wrappers are used to hold the image and set its width and height.
<a-point>: Annotate points define the position, text and style of each point within the image. Insert them between the Annotate wrappers.
The x and y coordinates of each Annotate Point are relative to the image and are written in percentage of total width or height.
<annotate>: Annotate wrappers are used to hold the image and set its width and height.
<a-point>: Annotate points define the position, text and style of each point within the image. Insert them between the Annotate wrappers.
The x and y coordinates of each Annotate Point are relative to the image and are written in percentage of total width or height.
CODE:
<annotatesrc="../../images/annotateSampleImage.png"width="500"alt="Sample Image"lazy><!-- Minimal Point --><a-pointx="25%"y="25%"content="This point is 25% from the left and 25% from the top" /><!-- Customize Point Size (default size is 40px) -->
@@ -93,7 +93,7 @@
<spanclass="badge bg-primary">Badge label</span></a-point></annotate>
-
+
@@ -109,12 +109,12 @@
-
OUTPUT:
Use markdown in the header, label and content
Annotate Points supports markdown in the header, label and content.
<annotate src="../../images/annotateSampleImage.png" width="500" alt="Sample Image">
<a-point x="75%" y="50%" content="This point is 75% from the left and 50% from the top">
<span class="badge bg-primary">Badge label</span>
</a-point>
@@ -144,7 +144,7 @@
<div style="opacity: 90%; color: red">Custom</div>
</a-point>
</annotate>
-
+
@@ -160,7 +160,7 @@
-
OUTPUT:
Using triggers and positions for Annotate Point
Similar to popovers, Annotate Points also support different types of triggers and positions
+
OUTPUT:
Using triggers and positions for Annotate Point
Similar to popovers, Annotate Points also support different types of triggers and positions
for users with different needs.
CODE:
<annotatesrc="../../images/annotateSampleImage.png"width="500"alt="Sample Image"><!-- Default Trigger (click)--><a-pointx="33%"y="33%"content="Lorem ipsum dolor sit amet" />
@@ -173,7 +173,7 @@
<!-- Both trigger and popover placement hover focus --><a-pointx="50%"y="66%"content="Popover on the bottom"placement="bottom"trigger="hover focus"/></annotate>
-
+
@@ -189,7 +189,7 @@
-
OUTPUT:
Displaying content as legends in Annotate Point
<a-point> allows users to display its content inside a popover or as a legend below the diagram or both. However, the label attribute must be specified in <a-point> in order to display the content below the image.
<a-point> allows users to display its content inside a popover or as a legend below the diagram or both. However, the label attribute must be specified in <a-point> in order to display the content below the image.
CODE:
<annotatesrc="../../images/annotateSampleImage.png"width="500"alt="Sample Image"><!-- Default Legend (popover only)--><a-pointx="25%"y="50%"content="There is only text when you click me"label="1"/><!-- Set Legend to bottom only (no popover) -->
@@ -197,7 +197,7 @@
<!-- Set Legend to both --><a-pointx="75%"y="50%"content="There is text at both locations"label="3"legend="both"header="Headers are displayed at both positions"/></annotate>
-
+
@@ -213,7 +213,7 @@
-
OUTPUT:
+
OUTPUT:
:
Clicking on this does nothing
:
@@ -223,7 +223,7 @@
<a-pointx="45%"y="50%"content="UML uses a hollow diamond to indicate an aggregation."label="3"header="Aggregation"color="blue"legend="both"/><a-pointx="64.5%"y="50%"content="Association labels describe the meaning of the association."label="4"header="Association labels"color="yellow"legend="both"/></annotate>
-
+
@@ -239,7 +239,7 @@
-
OUTPUT:
+
OUTPUT:
:
You can use a triangle and a solid line (not to be confused with an arrow) to indicate class inheritance.
:
@@ -252,7 +252,7 @@
<a-pointx="65%"y="50%"content="This is the period during which the method is being executed"header="Activation Bar"opacity="0.3"size="50"color="yellow"/><a-pointx="14%"y="85%"content="Return control and possibly some return value"header="Return Value"opacity="0.2"size="30"color="blue"/></annotate>
-
+
@@ -268,12 +268,12 @@
-
OUTPUT:
<a-point> Options
Name
Type
Default
Description
x
String
This must be specified. The x-coordinate of the point. Supports range of values from 0% to 100%.
y
String
This must be specified. The y-coordinate of the point. Supports range of values from 0% to 100%.
content
String
''
Annotate Point content. The annotation content will be omitted if this is not provided.
header
String
''
Annotate Point header. The header will be omitted if this is not provided.
trigger
String
click
Popover trigger type. Supports: click, focus, hover, or any space-separated combination of these.
placement
String
top
Position of the Popover. Supports: top, left, right, bottom.
label
String
''
The label shown on the point itself. The label will be omitted if this is not provided. Note that labels should not be too long as they might overflow out of the point.
size
String
'40'
The size of the point in pixels. Does not work with customised shapes
color
String
'green'
The color of the point. Supports any color in the CSS color format. E.g. red, #ffffff, rgb(66, 135, 245), etc. Does not work with customised shapes
opacity
String
'0.3'
The opacity of the point. Supports range of values from 0 to 1. Does not work with customised shapes
fontSize
String
'14'
The font size of the label. Supports any pixel size smaller than size of the point.
textColor
String
'black'
The color of the label. Supports any color in the CSS color format. E.g. red, #ffffff, rgb(66, 135, 245), etc.
legend
String
'popover'
The position of the Annotate Point content and header. Supports: popover, bottom, both.
<annotate> Options
This is effectively the same as the options used for the picture component.
Name
Type
Default
Description
alt
string
This must be specified. The alternative text of the image.
src
string
This must be specified. The URL of the image. The URL can be specified as absolute or relative references. More info in: Intra-Site Links
height
string
''
The height of the image in pixels.
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.
This must be specified. The x-coordinate of the point. Supports range of values from 0% to 100%.
y
String
This must be specified. The y-coordinate of the point. Supports range of values from 0% to 100%.
content
String
''
Annotate Point content. The annotation content will be omitted if this is not provided.
header
String
''
Annotate Point header. The header will be omitted if this is not provided.
trigger
String
click
Popover trigger type. Supports: click, focus, hover, or any space-separated combination of these.
placement
String
top
Position of the Popover. Supports: top, left, right, bottom.
label
String
''
The label shown on the point itself. The label will be omitted if this is not provided. Note that labels should not be too long as they might overflow out of the point.
size
String
'40'
The size of the point in pixels. Does not work with customised shapes
color
String
'green'
The color of the point. Supports any color in the CSS color format. E.g. red, #ffffff, rgb(66, 135, 245), etc. Does not work with customised shapes
opacity
String
'0.3'
The opacity of the point. Supports range of values from 0 to 1. Does not work with customised shapes
fontSize
String
'14'
The font size of the label. Supports any pixel size smaller than size of the point.
textColor
String
'black'
The color of the label. Supports any color in the CSS color format. E.g. red, #ffffff, rgb(66, 135, 245), etc.
legend
String
'popover'
The position of the Annotate Point content and header. Supports: popover, bottom, both.
<annotate> Options
This is effectively the same as the options used for the picture component.
Name
Type
Default
Description
alt
string
This must be specified. The alternative text of the image.
src
string
This must be specified. The URL of the image. The URL can be specified as absolute or relative references. More info in: Intra-Site Links
height
string
''
The height of the image in pixels.
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.
lazy
boolean
false
The <annotate> component lazy loads if this attribute is specified. Either the height or width should be specified to avoid layout shifts while lazy loading images.
<annotate src="../../images/annotateSampleImage.png" width="500" alt="Sample Image">
<a-point x="25%" y="25%" content="Lorem ipsum dolor sit amet" />
<a-point x="50%" y="25%" content="Lorem ipsum dolor sit amet" label="1a"/>
<a-point x="50%" y="25%" content="Lorem ipsum dolor sit amet" label="1b" legend="both"/>
</annotate>
-
+
@@ -289,7 +289,7 @@
-
Thumbnails
A thumbnail component allows you to insert thumbnails using text, images, or icons.
A warning will be displayed if you are using a non-Windows platform and don't have Graphviz installed. To disable this warning, you may modify your site.json like this.
An alternative layout engine, Smetana, is integrated into PlantUML and can be used to generate diagrams without a Graphviz installation. However, as the Smetana engine is a work in progress, certain layouts may not render correctly.
Example: Installing the above dependencies in GitHub Actions
A warning will be displayed if you are using a non-Windows platform and don't have Graphviz installed. To disable this warning, you may modify your site.json like this.
An alternative layout engine, Smetana, is integrated into PlantUML and can be used to generate diagrams without a Graphviz installation. However, as the Smetana engine is a work in progress, certain layouts may not render correctly.
Example: Installing the above dependencies in GitHub Actions
CODE:
<puml width="300">
@startuml
alice -> bob ++ : hello
bob -> bob ++ : self call
@@ -344,7 +344,7 @@
return success
@enduml
</puml>
-
+
@@ -360,7 +360,7 @@
-
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
+
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
@@ -370,7 +370,7 @@
bob -> george !! : delete
return success
@enduml
-
+
@@ -387,7 +387,7 @@
in another file:
<pumlsrc="diagrams/sequence.puml"width=300 />
-
+
@@ -403,13 +403,13 @@
-
OUTPUT:
The full PlantUML syntax reference can be found at plantuml.com/guide
More examples
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. Avoid using the same name for different diagrams to prevent overwriting.
src
string
The URL of the diagram if your diagram is in another .puml file. The URL can be specified as absolute or relative references. More info in: Intra-Site Links
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.
<puml width=300>
+
OUTPUT:
The full PlantUML syntax reference can be found at plantuml.com/guide
More examples
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. Avoid using the same name for different diagrams to prevent overwriting.
src
string
The URL of the diagram if your diagram is in another .puml file. The URL can be specified as absolute or relative references. More info in: Intra-Site Links
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.
<puml width=300>
@startuml
alice -> bob ++ : hello
bob -> bob ++ : self call
@enduml
</puml>
-
+
@@ -425,7 +425,7 @@
-
Sequence Diagram:
Use Case Diagram:
Class Diagram:
Activity Diagram:
Component Diagram:
State Diagram:
Object Diagram:
Gantt Diagram:
Entity Relation Diagram:
Ditaa Diagram:
Archimate Diagram:
Tree
A tree component allows you to generate tree-like visualisations, suitable for displaying folder structure.
Use indentation (2 spaces) to indicate the level of nesting.
CODE:
<tree>
+
Sequence Diagram:
Use Case Diagram:
Class Diagram:
Activity Diagram:
Component Diagram:
State Diagram:
Object Diagram:
Gantt Diagram:
Entity Relation Diagram:
Ditaa Diagram:
Archimate Diagram:
Tree
A tree component allows you to generate tree-like visualisations, suitable for displaying folder structure.
Use indentation (2 spaces) to indicate the level of nesting.
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:
<navbartype="primary">
+
Navbars
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.
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 via the add-class attribute. You can use built-in background styles or insert your own defined CSS classes.
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 via the add-class attribute. You can use built-in background styles or insert your own defined CSS classes.
The navbar component also provides access to MarkBind's site navigation and page navigation menu components if used in the page's layout. No additional setup is required!
If you are viewing the documentation on a larger device, resize the window to see what it looks like.
Alternatively, if you want to display in these navigation menus, the navbar is also able to "pull in" any container element with a HTML id of "site-nav" or "page-nav". You may refer to the layouts section for an example.
The navbar component auto-detects if the MarkBind's navigation components or your element containers has any .
-If absent, the navigation buttons to open the menus are automatically hidden.
Mobile navigation menu button placement
If you wish to alter the button placement on the navbar, you may use the <site-nav-button /> and <page-nav-button /> components in the lower-navbar slot.
By default, if the lower-navbar slot is not specified, the site and page navigation buttons are simply placed as such.
The navbar component also provides access to MarkBind's site navigation and page navigation menu components if used in the page's layout. No additional setup is required!
If you are viewing the documentation on a larger device, resize the window to see what it looks like.
Alternatively, if you want to display in these navigation menus, the navbar is also able to "pull in" any container element with a HTML id of "site-nav" or "page-nav". You may refer to the layouts section for an example.
The navbar component auto-detects if the MarkBind's navigation components or your element containers has any .
+If absent, the navigation buttons to open the menus are automatically hidden.
Mobile navigation menu button placement
If you wish to alter the button placement on the navbar, you may use the <site-nav-button /> and <page-nav-button /> components in the lower-navbar slot.
By default, if the lower-navbar slot is not specified, the site and page navigation buttons are simply placed as such.
<navbar><!-- Any normal navbar items --><aslot="brand"href="/"title="Home"class="navbar-brand">MarkBind</a><li><ahref="/userGuide/components/navigation.html#navbars"class="nav-link">Highlighted Link</a></li>
@@ -352,7 +352,7 @@
<page-nav-button /></div></navbar>
-
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.
Expanding menu items by default
You can append the :expanded: to a to make it expand by default. In the example above, * Authoring Contents :expanded: makes the menu item Authoring Contents expand by default.
Page Navigation Menus
print page nav as table of content
A Page Navigation Menu (pageNav for short) a list of the current page's headings. Page navigation menus are only available for use in layouts.
Adding a pageNav
Specify the smallest heading level you want to be included within the <frontmatter> of a page with or a .
(Optional) You may also specify a page navigation title within <frontmatter> that will be placed at the top of the page navigation menu.
Position the page navigation menu within your layout using the <page-nav /> component.
(Optional) To make pageNav accessible on smaller screens, you can use the <page-nav-button /> component in the navbar.
(Optional) To make pageNav available on print, you can position the page navigation menu on individual pages with the <page-nav-print /> component.
Additional details on printing pageNav
You can specify the location of the page navigation menu on print by using either of the following syntaxes:
<page-nav-print />
<page-nav-print></page-nav-print>
This is useful if you want to include a custom title (or any other content) before the page navigation menu. For example, <page-nav-print>Table of Contents</page-nav-print>
You can specify multiple <page-nav-print /> components in a page and they do not have to be at the top of the page. They also do not appear when viewed on a browser.
Example
-In the page that you want to have page navigation printed (i.e. to serve as a table of content when viewed on PDFs), use the <page-nav-print /> component to position the pageNav like so:
<frontmatter>
- pageNav: 2
- pageNavTitle: "Chapters of This Page"
-</frontmatter>
-
-<page-nav-print />
-
-# Overview
-Content of the page...
-
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.
Expanding menu items by default
You can append the :expanded: to a to make it expand by default. In the example above, * Authoring Contents :expanded: makes the menu item Authoring Contents expand by default.
-
-
+
+
+ 5.453125 4.089844 L 13.453125 4.089844 Z M 13.453125 13.636719 ">
-
To view the pageNav on print, open the print preview of the page using the browser's print function.
If you are using Chrome, you can right-click on the page and select "Print" to open the print preview.
-You can try it out by going to our CLI Commands page and printing it.
Example
-In the page that you want to have page navigation, you may show only <h1> and <h2> headings in the pageNav, and set a custom pageNav title like so:
<frontmatter>
- pageNav: 2
- pageNavTitle: "Chapters of This Page"
-</frontmatter>
-
-
+
Page Navigation Menus
print page nav as table of content
A Page Navigation Menu (pageNav for short) displays a list of the current page's headings. Page navigation menus are typically configured in layouts, but can also be utilized in individual pages.
Adding a pageNav
Specify the smallest heading level you want to be included within the <frontmatter> of a page with or a .
(Optional) You may also specify a page navigation title within <frontmatter> that will be placed at the top of the page navigation menu.
Position the page navigation menu within your layout using the <page-nav /> component.
(Optional) To make pageNav accessible on smaller screens, you can use the <page-nav-button /> component in the navbar.
(Optional) To make pageNav available on print, you can position the page navigation menu on individual pages with the <page-nav-print /> component.
Additional details on printing pageNav
You can specify the location of the page navigation menu on print by using either of the following syntaxes:
<page-nav-print />
<page-nav-print></page-nav-print>
This is useful if you want to include a custom title (or any other content) before the page navigation menu. For example, <page-nav-print>Table of Contents</page-nav-print>
You can specify multiple <page-nav-print /> components in a page and they do not have to be at the top of the page. They also do not appear when viewed on a browser.
Example
+In the page that you want to have page navigation printed (i.e. to serve as a table of content when viewed on PDFs), use the <page-nav-print /> component to position the pageNav like so:
<frontmatter>
+ pageNav: 2
+ pageNavTitle: "Chapters of This Page"
+</frontmatter>
+
+<page-nav-print />
+
+# Overview
+Content of the page...
+
+
-
-
+
+
+ 5.453125 4.089844 L 13.453125 4.089844 Z M 13.453125 13.636719 " data-v-3602e6fc>
-
Then, in your layout file, use the <page-nav /> component to position the pageNav.
ExampleExample usage of the <page-nav /> component
You can see an example of a Page Navigation Bar on the right side of this page.
Scroll To Top Button
The scroll-top-button component allows users to move to the top of the page.
Adding a scroll-top-button
Add <scroll-top-button></scroll-top-button> to layout file.
Options
Name
Type
Default
Description
icon[S]
String
:fas-arrow-circle-up:
Inline MarkDown text of the icon displayed on the left.
icon-size
String
lg
Resizes the icon. Supports integer-scaling of the icon dimensions e.g. 2x, 3x, 4x, etc.
bottom
String
2%
Distance from bottom edge of page.
right
String
2%
Distance from right edge of page.
<scroll-top-button
+
To view the pageNav on print, open the print preview of the page using the browser's print function.
If you are using Chrome, you can right-click on the page and select "Print" to open the print preview.
+You can try it out by going to our CLI Commands page and printing it.
You can see an example of a Page Navigation Bar on the right side of this page.
Scroll To Top Button
The scroll-top-button component allows users to move to the top of the page.
Adding a scroll-top-button
Add <scroll-top-button></scroll-top-button> to layout file.
Options
Name
Type
Default
Description
icon[S]
String
:fas-arrow-circle-up:
Inline MarkDown text of the icon displayed on the left.
icon-size
String
lg
Resizes the icon. Supports integer-scaling of the icon dimensions e.g. 2x, 3x, 4x, etc.
This page lists some other components that may be useful in creating education websites. For now, there are only question and quiz components.
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, Fill-in-the-Blanks, 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:
Header and Hint syntax
<!-- Insert markdown into the header and hint using the respective attributes --><questiontype="checkbox"header="Which of the following is correct?"hint="Think out of the box! :fas-box:">
@@ -37,7 +37,7 @@
<!-- Several hidden checkbox q-option components explained later --></question>
-
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
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, blanks, 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 . 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:
<questiontype="mcq"header="Which of these **contradicts** the heuristics recommended when creating test cases with multiple inputs?">
+
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
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, blanks, 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 . 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:
<questiontype="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-optionreason="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.
@@ -90,7 +90,7 @@
How do you figure out which inputs are wrong? (or correct)
</div></question>
-
+
@@ -106,22 +106,22 @@
-
OUTPUT:
Which of these contradicts the heuristics recommended when creating test cases with multiple inputs?
+
OUTPUT:
Which of these contradicts the heuristics recommended when creating test cases with multiple inputs?
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.
-
MCQ questions can have multiple correct options!
Checkbox Questions
CODE:
<questiontype="checkbox"hint="Use your calculator! :fas-calculator:">
+
MCQ questions can have multiple correct options!
Checkbox Questions
CODE:
<questiontype="checkbox"hint="Use your calculator! :fas-calculator:">
- ##### Which of the following is true?
+ ###### Which of the following is true?
<br><q-optionreason="lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum">
@@ -134,7 +134,7 @@
11 / 11 = 1
</q-option></question>
-
+
@@ -150,28 +150,28 @@
-
OUTPUT:
Which of the following is true?
OUTPUT:
Which of the following is true?
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.
Fill-in-the-Blanks Questions
Fill-in-the-blanks questions are specified with the type="blanks" attribute.
Unlike MCQ and checkbox questions, answer checking is performed for each blank by providing keywords to check for in the user's answer through the keywords attribute in each q-option.
-If no keywords are provided, the answer for that blank will always be marked as correct.
Keywords are validated by checking if the keyword matches the user's answer exactly (ignoring letter casing).
+If no keywords are provided, the answer for that blank will always be marked as correct.
Keywords are validated by checking if the keyword matches the user's answer exactly (ignoring letter casing).
This works well for some
and not others.
CODE:
<questiontype="blanks"hint="Google it!">
- ##### German sociologist __________ called the process of simultaneously analyzing the behavior of individuals and the society that shapes that behavior __________.
+ ###### German sociologist __________ called the process of simultaneously analyzing the behavior of individuals and the society that shapes that behavior __________.
<q-optionkeywords="Norbert Elias, Elias"reason="That's his name!"></q-option><q-optionkeywords="figuration"></q-option></question>
-
+
@@ -187,20 +187,20 @@
-
OUTPUT:
German sociologist __________ called the process of simultaneously analyzing the behavior of individuals and the society that shapes that behavior __________.
OUTPUT:
German sociologist __________ called the process of simultaneously analyzing the behavior of individuals and the society that shapes that behavior __________.
By default, if the question has yet to be answered correctly, intermediate results will be shown beside each blank. You can specify a no-intermediate-result attribute to avoid this behvaiour (i.e. hide the result of each blank upon incorrect attempts).
Since the validation is imperfect, the minimum proportion of correct blanks needed for the entire question to be marked as correct can also be changed using the threshold attribute.
If you don't want to validate the answer at all, you may set the threshold attribute to 0. Doing so always marks the entire question correct, and users will be able to see all intended answers.
CODE:
<questiontype="blanks"hint="What properties would you want these database transactions to have?"threshold=0.75no-intermediate-result>
+
By default, if the question has yet to be answered correctly, intermediate results will be shown beside each blank. You can specify a no-intermediate-result attribute to avoid this behvaiour (i.e. hide the result of each blank upon incorrect attempts).
Since the validation is imperfect, the minimum proportion of correct blanks needed for the entire question to be marked as correct can also be changed using the threshold attribute.
If you don't want to validate the answer at all, you may set the threshold attribute to 0. Doing so always marks the entire question correct, and users will be able to see all intended answers.
CODE:
<questiontype="blanks"hint="What properties would you want these database transactions to have?"threshold=0.75no-intermediate-result>
- ##### In computer science, ACID is a set of properties of database transactions intended to guarantee data validity despite errors, power failures, and other mishaps. These properties are: A for __________, C for __________, I for __________, and D for __________.
+ ###### In computer science, ACID is a set of properties of database transactions intended to guarantee data validity despite errors, power failures, and other mishaps. These properties are: A for __________, C for __________, I for __________, and D for __________.
<q-optionkeywords="Atomicity, Atomic"reason="Meaning: either all occurs or nothing occurs"></q-option><q-optionkeywords="Consistency, Consistent"></q-option><q-optionkeywords="Isolation, Isolated"></q-option><q-optionkeywords="Durability, Durable"></q-option></question>
-
+
@@ -216,12 +216,12 @@
-
OUTPUT:
In computer science, ACID is a set of properties of database transactions intended to guarantee data validity despite errors, power failures, and other mishaps. These properties are: A for __________, C for __________, I for __________, and D for __________.
OUTPUT:
In computer science, ACID is a set of properties of database transactions intended to guarantee data validity despite errors, power failures, and other mishaps. These properties are: A for __________, C for __________, I for __________, and D for __________.
Fill-in-the-Blanks Question specific Options and Slots
Name
Type
Default
Description
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.
no-intermediate-result
Boolean
False
Hides the result of each blank after an incorrect attempt.
q-option Options and Slots
Name
Type
Default
Description
keywords
String
''
Comma delimited string of keywords or phrases to match the user's answer against.
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!
+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
and not others.
You can provide your answer in the answer attribute, or similarly, the <div slot="answer"> slot for more expressive formatting.
CODE:
<questiontype="text"header="Which country did the Hawaiian pizza originate from?"
@@ -233,7 +233,7 @@
:pizza: :pizza: :pizza: :pizza: :pizza: :pizza: :pizza: :pizza: :pizza: :pizza: :pizza: :pizza:
</div></question>
-
+
@@ -249,17 +249,17 @@
-
OUTPUT:
Which country did the Hawaiian pizza originate from?
OUTPUT:
Which country did the Hawaiian pizza originate from?
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.
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>
+
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.
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.
Quiz intro markup. Overrides the intro attribute if both are present.
MCQ and Checkbox questions
<!-- use type="checkbox" for checkbox questions -->
+
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.
MCQ and Checkbox questions
<!-- use type="checkbox" for checkbox questions --><questiontype="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 -->
@@ -307,7 +307,7 @@
</div></question>
-
+
@@ -326,13 +326,13 @@
Fill-in-the-Blanks questions
<questiontype="blanks"hint="Google it!">
- ##### German sociologist __________ called the process of simultaneously analyzing the behavior of individuals and the society that shapes that behavior __________.
+ ###### German sociologist __________ called the process of simultaneously analyzing the behavior of individuals and the society that shapes that behavior __________.
<q-optionkeywords="Norbert Elias, Elias"reason="That's his name!"></q-option><q-optionkeywords="figuration"></q-option></question>
-
The components in this page can be used to easily create various forms of pop-ups that are activated on some user action (e.g., hovering over some text). This may be useful for showing additional information related to some specific area or span of content.
Tooltips
CODE:
<tooltipcontent="Lorem ipsum dolor sit amet"placement="top"><buttonclass="btn btn-secondary">Tooltip on top</button>
@@ -62,7 +62,7 @@
**Free Text**:
<tooltipcontent="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>
-
+
@@ -78,13 +78,13 @@
-
OUTPUT:
Trigger
Markdown:
-
Free Text:
+
OUTPUT:
Trigger
Markdown:
+
Free Text:
Using trigger for Tooltip:
CODE:
More about <triggerfor="tt:trigger_id">trigger</trigger>.
<tooltipid="tt:trigger_id"content="This tooltip triggered by a trigger"></tooltip><br>This is the same <triggerfor="tt:trigger_id">trigger</trigger> as last one.
-
+
@@ -100,10 +100,10 @@
-
OUTPUT:
More about trigger.
-
-This is the same trigger as last one.
More about triggers
Options
Name
Type
Default
Description
trigger
String
hover focus
How the tooltip is triggered. Supports: click, focus, hover, or any space-separated combination of these.
content
String
''
Text content of the tooltip.
placement
String
top
How to position the tooltip. Supports: top, left, right, bottom.
Hover <tooltipcontent="An explanation, **supports simple Markdown**">here</tooltip> to see a tooltip.
-
+
OUTPUT:
More about trigger.
+
+This is the same trigger as last one.
More about triggers
Options
Name
Type
Default
Description
trigger
String
hover focus
How the tooltip is triggered. Supports: click, focus, hover, or any space-separated combination of these.
content
String
''
Text content of the tooltip.
placement
String
top
How to position the tooltip. Supports: top, left, right, bottom.
Hover <tooltipcontent="An explanation, **supports simple Markdown**">here</tooltip> to see a tooltip.
+
@@ -182,7 +182,7 @@
<div><popoverheader="false"content="Nice!">What do you say</popover></div>
-
+
@@ -198,11 +198,11 @@
-
OUTPUT:
Header
Trigger
Markdown
Content using slot
Content using src
Wrap Text
Using trigger for Popover:
CODE:
More about <triggerfor="pop:trigger_id">trigger</trigger>.
+
OUTPUT:
Header
Trigger
Markdown
Content using slot
Content using src
Wrap Text
Using trigger for Popover:
CODE:
More about <triggerfor="pop:trigger_id">trigger</trigger>.
<popoverid="pop:trigger_id"content="This popover is triggered by a trigger"></popover><br>This is the same <triggerfor="pop:trigger_id">trigger</trigger> as last one.
-
+
@@ -218,10 +218,10 @@
-
OUTPUT:
More about trigger.
-
-This is the same trigger as last one.
More about triggers
Options
Name
Type
Default
Description
trigger
String
hover focus
How the Popover is triggered. Supports: click, focus, hover, or any space-separated combination of these.
header[S]
String
''
Popover header, supports MarkDown text.
content[S]
String
''
Popover content, supports MarkDown text.
src
String
The URL to the remote page to be loaded as the content of the popover. Both .md and .html are accepted.
placement
String
top
How to position the Popover. Supports: top, left, right, bottom.
MarkBind supports the src attribute, content attribute and content slot for popovers.
-Usually, only one of these would be used at a time.
If multiple of these are used, MarkBind will prioritise in the following order:
content slot
content attribute
src attribute
Hover over the <triggerfor="pop:context-target">keyword</trigger> to see the popover.
+
OUTPUT:
More about trigger.
+
+This is the same trigger as last one.
More about triggers
Options
Name
Type
Default
Description
trigger
String
hover focus
How the Popover is triggered. Supports: click, focus, hover, or any space-separated combination of these.
header[S]
String
''
Popover header, supports MarkDown text.
content[S]
String
''
Popover content, supports MarkDown text.
src
String
The URL to the remote page to be loaded as the content of the popover. Both .md and .html are accepted.
placement
String
top
How to position the Popover. Supports: top, left, right, bottom.
MarkBind supports the src attribute, content attribute and content slot for popovers.
+Usually, only one of these would be used at a time.
If multiple of these are used, MarkBind will prioritise in the following order:
content slot
content attribute
src attribute
Hover over the <triggerfor="pop:context-target">keyword</trigger> to see the popover.
<popoverid="pop:context-target"header="Popover header"placement="top"><divslot="content">
@@ -230,7 +230,7 @@
</div></popover>
-
+
@@ -270,7 +270,7 @@
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>
-
+
@@ -286,13 +286,13 @@
-
OUTPUT:
More about trigger.
+
OUTPUT:
More about trigger.
This is the same trigger as last one.
-
This is a trigger for a centered modal.
This is a trigger for a modal with a custom OK button.
More about triggers
Options
Name
type
Default
Description
header[S]
String
''
Header of the Modal component. Supports inline markdown text.
footer
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. Note: Ensure id for each Modal is unique.
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.
Click <triggertrigger="click"for="modal:unused">here</trigger> to open a modal.
+
This is a trigger for a centered modal.
This is a trigger for a modal with a custom OK button.
More about triggers
Options
Name
type
Default
Description
header[S]
String
''
Header of the Modal component. Supports inline markdown text.
footer
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. Note: Ensure id for each Modal is unique.
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.
Click <triggertrigger="click"for="modal:unused">here</trigger> to open a modal.
<modalheader="Modal header"id="modal:unused"> Modal content
</modal>
-
The components in this page are the core presentational components you may want to use. Panels and tabs can be used to organise content sections, while badges and boxes can highlight small, specific pieces of information.
Use of markdown in content
As presentational components are HTML-based, you need to follow the HTML syntax when using markdown in the content of the components.
-More specifically, you should use either:
add a line break with no indentation before the markdown content
use the <markdown> (block level elements) or <md> (inline level elements) tags to wrap the markdown content.
For more information, please refer to this section.
The components in this page are the core presentational components you may want to use. Panels and tabs can be used to organise content sections, while badges and boxes can highlight small, specific pieces of information.
Use of markdown in content
As presentational components are HTML-based, you need to follow the HTML syntax when using markdown in the content of the components.
+More specifically, you should use either:
add a line break with no indentation before the markdown content
use the <markdown> (block level elements) or <md> (inline level elements) tags to wrap the markdown content.
For more information, please refer to this section.
Badges
Example:
CODE:
<spanclass="badge bg-primary">Some Plain Text
</span><spanclass="badge bg-primary"><md>_Some Markdown_</md></span>
-
+
@@ -51,9 +51,9 @@
-
OUTPUT:
+
OUTPUT:
Some Plain Text
-Some Markdown
You can choose from a variety of colors for your badges. You can also use the rounded-pill class to make the badges pill-shaped.
CODE:
Normal:
+Some Markdown
You can choose from a variety of colors for your badges. You can also use the rounded-pill class to make the badges pill-shaped.
<boxtype="info"> info
</box><boxtype="warning">
@@ -200,7 +200,7 @@
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
</box></box>
-
+
@@ -216,23 +216,23 @@
-
OUTPUT:
+
OUTPUT:
info
-
+
warning
-
+
success
-
+
important
-
+
wrong
-
+
tip
-
+
definition
-
+
dismissible info
-
Header π
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! π
+
Header π
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.
The built in types can be colored.
CODE:
<boxtype="info"theme="primary"> primary
@@ -258,7 +258,7 @@
<boxtype="info"theme="dark"> dark
</box>
-
+
@@ -274,21 +274,21 @@
-
OUTPUT:
+
OUTPUT:
primary
-
+
secondary
-
+
success
-
+
danger
-
+
warning
-
+
info
-
+
light
-
+
dark
MarkBind also supports a light color scheme for boxes
<boxbackground-color="#ffca6a"border-color="grey"border-left-color="#8b5a01">default type, styled as an orange box with a brown left border
@@ -421,7 +421,7 @@
You can use any inline markdown in the `icon` property.
</box>
-
+
@@ -437,16 +437,16 @@
-
OUTPUT:
+
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:
<boxno-iconno-backgroundtype="success">
+
π
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:
<boxno-iconno-backgroundtype="success"> success box without a tick icon and backgound
</box><boxno-bordertype="definition"light> definition type box, light style without border
</box>
-
+
@@ -462,11 +462,11 @@
-
OUTPUT:
+
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:
<boxtype="success"icon=":fas-camera:">
+
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:
<boxtype="success"icon=":fas-camera:"> Lorem ipsum dolor sit amet, consectetur adipiscing elit
</box><boxtype="warning"icon=":fas-camera:"icon-size="2x">
@@ -478,7 +478,7 @@
<boxtype="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>
-
+
@@ -494,18 +494,18 @@
-
OUTPUT:
+
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.
header[S]
String
null
Markdown text of the box header.
type
String
''
Supports: info, warning, success, important, wrong, tip, definition, or empty for default.
theme
String
''
Supports: primary, secondary, success, danger, warning, tip, light, dark 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-background
Boolean
false
Removes background, except if styled by background-color option.
no-icon
Boolean
false
Removes icon, except if icon is displayed via icon option.
<boxtype="warning"> warning
</box>
-
+
@@ -521,27 +521,27 @@
-
+
default
-
+
info
-
+
warning
-
+
success
-
+
important
-
+
wrong
-
+
tip
-
+
definition
Panels
Panel is a flexible container that supports collapsing and expanding its content. It is expandable by default.
CODE:
<panelheader="This is your header for a Panel, click me to expand!"><markdown>_markdown_</markdown><p>plain text ...</p></panel>
-
+
@@ -557,10 +557,10 @@
-
OUTPUT:
This is your header for a Panel, click me to expand!
With minimized attribute, panel is minimized into an inline block element. The alt attribute is for you to specify the minimized block header.
CODE:
<panelheader="How to cultivate a tomato plant at home"alt="Tomatoes"minimized>
+
OUTPUT:
This is your header for a Panel, click me to expand!
With minimized attribute, panel is minimized into an inline block element. The alt attribute is for you to specify the minimized block header.
CODE:
<panelheader="How to cultivate a tomato plant at home"alt="Tomatoes"minimized> Lorem ipsum ...
</panel>
-
+
@@ -576,10 +576,10 @@
-
OUTPUT:
Tomatoes
With expanded attribute, you can set the panels to be expanded when loaded in.
CODE:
<panelheader="Have your readers click less to see the Panel's contents"expanded>
+
OUTPUT:
Tomatoes
With expanded attribute, you can set the panels to be expanded when loaded in.
CODE:
<panelheader="Have your readers click less to see the Panel's contents"expanded> Lorem ipsum ...
</panel>
-
+
@@ -595,12 +595,12 @@
-
OUTPUT:
Have your readers click less to see the Panel's contents
+
OUTPUT:
Have your readers click less to see the Panel's contents
Lorem ipsum ...
-
With the expand-headerless attribute, you can hide the panel header when it is expanded.
CODE:
<panelheader="This header will only show when the Panel is collapsed"expand-headerless>
+
With the expand-headerless attribute, you can hide the panel header when it is expanded.
CODE:
<panelheader="This header will only show when the Panel is collapsed"expand-headerless> Lorem ipsum ...
</panel>
-
+
@@ -616,7 +616,7 @@
-
OUTPUT:
This header will only show when the Panel is collapsed
With the peek attribute, you may showcase part of your content without expanding the panel.
CODE:
<panelheader="Give your readers a peek of the content without expanding Panel"peek>
+
OUTPUT:
This header will only show when the Panel is collapsed
With the peek attribute, you may showcase part of your content without expanding the panel.
CODE:
<panelheader="Give your readers a peek of the content without expanding Panel"peek> 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.
@@ -627,7 +627,7 @@
dis parturient montes, nascetur ridiculus mus. Duis tincidunt diam eu dolor pellentesque, eget dignissim tortor
pellentesque.
</panel>
-
+
@@ -643,7 +643,7 @@
-
OUTPUT:
Give your readers a peek of the content without expanding Panel
+
OUTPUT:
Give your readers a peek of the content without expanding Panel
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.
@@ -653,7 +653,7 @@
eget tincidunt. Maecenas vel mauris mattis nisl tempor sollicitudin. Orci varius natoque penatibus et magnis
dis parturient montes, nascetur ridiculus mus. Duis tincidunt diam eu dolor pellentesque, eget dignissim tortor
pellentesque.
-
Panel provides many types that change its appearance.
CODE:
<panelheader="**light type panel (DEFAULT)**"type="light"minimized>
+
Panel provides many types that change its appearance.
CODE:
<panelheader="**light type panel (DEFAULT)**"type="light"minimized> ...
</panel><panelheader="**dark type panel**"type="dark"minimized>
@@ -683,7 +683,7 @@
<panelheader="**minimal type panel**"type="minimal"minimized> ...
</panel>
-
+
@@ -699,7 +699,7 @@
-
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, no-close, or no-minimized-switch.
CODE:
<panelheader="**This minimized panel does not have a switch button**"minimizedno-minimized-switch>
+
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, no-close, or no-minimized-switch.
CODE:
<panelheader="**This minimized panel does not have a switch button**"minimizedno-minimized-switch> ...
</panel><panelheader="This panel does not have a switch button"no-switch>
@@ -711,7 +711,7 @@
<panelheader="This panel does not have either buttons"no-closeno-switch> ...
</panel>
-
+
@@ -727,10 +727,10 @@
-
OUTPUT:
This minimized panel does not have a switch button
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).
If src attribute is provided, the panel will take content from the src specified and add it to the Panel body.
CODE:
<panelheader="Content loaded in from 'src'"src="extra/loadContent.html#fragment"minimized></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:
<panelheader="Content loaded in from 'src'"src="extra/loadContent.html#fragment"minimized></panel>
+
@@ -763,10 +763,10 @@
-
OUTPUT:
Content loaded in from 'src'
If popup-url attribute is provided, a popup button will be shown. If clicked, it opens the specified url in a new window.
CODE:
<panelheader="Try clicking on my pop-up button"popup-url="/userGuide/syntax/extra/loadContent.html">
+
OUTPUT:
Content loaded in from 'src'
Global Effects of the Script and Styles from the Imported Externals
Importing external resources that contains script or styles can inadvertently take global effects on your MarkBind website. Due to hoisting during processing, imported scripts and stylesheets affect the entire page. This could potentially alter its appearance and behavior beyond the intended scope.
For example, if a CSS file imported via such means styles headings to be red, this change will be reflected page-wide.
To safeguard against unintended consequences, consider directly incorporating the code or customizing styles to target specific elements or classes not used universally. This approach grants more precise control over your website's presentation and reduces the risk of unexpected changes.
If popup-url attribute is provided, a popup button will be shown. If clicked, it opens the specified url in a new window.
CODE:
<panelheader="Try clicking on my pop-up button"popup-url="/userGuide/syntax/extra/loadContent.html"> This panel has a popup.
</panel>
-
+
@@ -782,10 +782,10 @@
-
OUTPUT:
Try clicking on my pop-up button
If preload attribute is provided, the panel body will load the HTML when the page renders instead of after being expanded.
CODE:
<panelheader="Right click and inspect my HTML before expanding me!"src="extra/loadContent.html#fragment"preload>
+
OUTPUT:
Try clicking on my pop-up button
If preload attribute is provided, the panel body will load the HTML when the page renders instead of after being expanded.
CODE:
<panelheader="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>
-
+
@@ -801,9 +801,9 @@
-
OUTPUT:
Right click and inspect my HTML before expanding me!
You should be able to find this text before expanding the Panel.
+
OUTPUT:
Right click and inspect my HTML before expanding me!
You should be able to find this text before expanding the Panel.
Loading...
-
You can nest Panels or other components within a Panel.
CODE:
<panelheader="Parent Panel">
+
You can nest Panels or other components within a Panel.
CODE:
<panelheader="Parent Panel"><panelheader="Level 1 Nested Panel"><panelheader="Level 2 Nested Panel"><boxtype="success">
@@ -818,7 +818,7 @@
Some Text
</panel></panel>
-
+
@@ -834,10 +834,10 @@
-
OUTPUT:
Parent Panel
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.
expand-headerless
Boolean
false
Whether to hide the header text when the Panel is expanded.
peek
Boolean
false
Whether to show part of the content when the Panel is collapsed.
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.
<panelheader="primary type panel"type="primary" >
+
OUTPUT:
Parent Panel
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.
expand-headerless
Boolean
false
Whether to hide the header text when the Panel is expanded.
peek
Boolean
false
Whether to show part of the content when the Panel is collapsed.
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.
<panelheader="primary type panel"type="primary" > ...
</panel>
-
+
@@ -853,9 +853,9 @@
-
minimal type panel
seamless type panel
info type panel
+
minimal type panel
seamless type panel
info type panel
...
-
danger type panel
warning type panel
success type panel
light type panel (DEFAULT)
dark type panel
primary type panel
secondary type panel
Tabs
CODE:
<tabs>
+
danger type panel
warning type panel
success type panel
light type panel (DEFAULT)
dark type panel
primary type panel
secondary type panel
Tabs
CODE:
<tabs><tabheader="First tab"> Text in the first tab
<markdown>_some markdown_</markdown>
@@ -878,7 +878,7 @@
</tab></tab-group></tabs>
-
+
@@ -894,7 +894,7 @@
-
OUTPUT:
First tab
+
OUTPUT:
First tab
Text in the first tab
some markdown
Disabled second tab β
Tab not printed
This tab will not be printed.
@@ -902,7 +902,7 @@
Some stuff about 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.
Tabs, tab group and individual tab can be omitted during printing by adding Bootstrap's display property class="d-print-none" to the respective components.
<tabs>
+
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.
Tabs, tab group and individual tab can be omitted during printing by adding Bootstrap's display property class="d-print-none" to the respective components.
<tabs><tabheader="First tab"> Content of the first tab
</tab>
@@ -918,7 +918,7 @@
</tab></tab-group></tabs>
-
A site generated by MarkBind can be deployed by simply uploading the generated files to any Web server. In addition, MarkBind provides several convenient deployment options.
(Optional) Use the markbind serve command to stage the site locally and confirm the contents are as expected.
Use the markbind build command to generate the site from source files. That command puts the generated site files in a directory named _site (you can change the output directory using parameters supplied to the command).
Upload the site files to the Web server. The sections below explain how to automate this step if you are deploying to some online platforms.
Upload the site files to the Web server. The sections below explain how to automate this step if you are deploying to some online platforms.
Deploying to GitHub Pages
MarkBind can easily deploy a site to GitHub pages if the project root directory is also a GitHub repo.
Using the markbind deploy command
Running the markbind deploy command will deploy the most recent build of your site to the gh-pages branch of the repo origin and will be available.
Then, navigate to the Settings > Pages section on GitHub for that repository and set the source to the root of the gh-pages branch. You can read this source on GitHub Pages for more details.
If you are deploying the site to GitHub pages, the baseUrl setting in the site.json should be set to the "/<repositoryName>" for the links in the deployed site to work correctly.
Example If you are using GitHub Pages to host your deployed website at repo myorg/myproduct (i.e., the website is published at https://myorg.github.io/myproduct), then your baseUrl should be "/myproduct".
You can override the default deployment settings (e.g., repo/branch to deploy) in the site.json's deploy section:
User Guide: Configuring the Site β deploy
markbind deploy generates the static site from your source by default; hence, it is not necessary to run markbind build first to generate the site before deploying. To skip the site generation, you can use the --no-build option for markbind deploy.
More information can be found in the CLI Commands section.
Using CI Platforms
You can setup CI Platforms to automatically build and deploy your site on GitHub Pages every time your GitHub repo is updated.
Generating a GitHub Personal Access Token
With the exception of GitHub Actions, a GitHub Personal Access Token with repo permissions is required for deploying your MarkBind site to GitHub Pages via CI tools.
Take note of the generated token - you will not be able to see it again once you navigate away from the page.
Deploying via GitHub Actions
To instruct GitHub Actions to build and deploy the site when you push to the repository, add a GitHub Actions workflow file in your project repo at the location <PROJECT_ROOT>/.github/workflows/deploy.yml A sample workflow file is provided below:
A site generated by MarkBind can be deployed by simply uploading the generated files to any Web server. In addition, MarkBind provides several convenient deployment options.
(Optional) Use the markbind serve command to stage the site locally and confirm the contents are as expected.
Step 3:
Use the markbind build command to generate the site from source files. That command puts the generated site files in a directory named _site (you can change the output directory using parameters supplied to the command).
Step 4:
Upload the site files to the Web server. The sections below explain how to automate this step if you are deploying to some online platforms.
Upload the site files to the Web server. The sections below explain how to automate this step if you are deploying to some online platforms.
Deploying to GitHub Pages
MarkBind can easily deploy a site to GitHub pages if the project root directory is also a GitHub repo.
Using the markbind deploy command
Running the markbind deploy command will deploy the most recent build of your site to the gh-pages branch of the repo origin and will be available.
Then, navigate to the Settings > Pages section on GitHub for that repository and set the source to the root of the gh-pages branch. You can read this source on GitHub Pages for more details.
If you are deploying the site to GitHub pages, the baseUrl setting in the site.json should be set to the "/<repositoryName>" for the links in the deployed site to work correctly.
Example If you are using GitHub Pages to host your deployed website at repo myorg/myproduct (i.e., the website is published at https://myorg.github.io/myproduct), then your baseUrl should be "/myproduct".
You can override the default deployment settings (e.g., repo/branch to deploy) in the site.json's deploy section:
User Guide: Configuring the Site β deploy
markbind deploy generates the static site from your source by default; hence, it is not necessary to run markbind build first to generate the site before deploying. To skip the site generation, you can use the --no-build option for markbind deploy.
More information can be found in the CLI Commands section.
Using CI Platforms
You can setup CI Platforms to automatically build and deploy your site on GitHub Pages every time your GitHub repo is updated.
Generating a GitHub Personal Access Token
With the exception of GitHub Actions, a GitHub Personal Access Token with repo permissions is required for deploying your MarkBind site to GitHub Pages via CI tools.
Take note of the generated token - you will not be able to see it again once you navigate away from the page.
Deploying via GitHub Actions
To instruct GitHub Actions to build and deploy the site when you push to the repository, add a GitHub Actions workflow file in your project repo at the location <PROJECT_ROOT>/.github/workflows/deploy.yml A sample workflow file is provided below:
-
-
+
+
+ 5.453125 4.089844 L 13.453125 4.089844 Z M 13.453125 13.636719 " data-v-3602e6fc>
-
The sample deploy.yml workflow above uses the default GitHub Token secret that is generated automatically for each GitHub Actions workflow. You may also use a GitHub Personal Access Token in place of the default GitHub Token.
Once you have created the file, commit and push the file to your repo. GitHub Actions should start to build and deploy your MarkBind site. You can verify this by visiting www.github.com/<org|username>/<repo>/actions.
MarkBind provides a helper GitHub Action that you can use to simplify your workflow file. A sample workflow file utilizing the action is as follows:
The sample deploy.yml workflow above uses the default GitHub Token secret that is generated automatically for each GitHub Actions workflow. You may also use a GitHub Personal Access Token in place of the default GitHub Token.
Once you have created the file, commit and push the file to your repo. GitHub Actions should start to build and deploy your MarkBind site. You can verify this by visiting www.github.com/<org|username>/<repo>/actions.
MarkBind provides a helper GitHub Action that you can use to simplify your workflow file. A sample workflow file utilizing the action is as follows:
Accept the authorisation for Travis CI when you are redirected to GitHub.
Go to the Repositories page, and click on the green Activate button. If you are already using Travis CI, click on the white Manage Repositories on GitHub button instead.
Select the repository with the MarkBind site, and add the Travis CI GitHub App to the repository by clicking the green Approve and Install button.
Find the repository with the MarkBind site. If the organization/repository is not shown in the list, click on Review and add link at the bottom of the list of organization and follow the steps to give Travis access to the organization containing your repo. After that, come back to the Repositories page and use the Sync Account button to sync your Travis account with GitHub.
Activate the repo using the slider switch in front of it.
Add a .travis.yml file to instruct Travis CI to build and deploy the site when you push to the repository. An example .travis.yml file that can accomplish this is given below:
Accept the authorisation for Travis CI when you are redirected to GitHub.
Go to the Repositories page, and click on the green Activate button. If you are already using Travis CI, click on the white Manage Repositories on GitHub button instead.
Select the repository with the MarkBind site, and add the Travis CI GitHub App to the repository by clicking the green Approve and Install button.
Find the repository with the MarkBind site. If the organization/repository is not shown in the list, click on Review and add link at the bottom of the list of organization and follow the steps to give Travis access to the organization containing your repo. After that, come back to the Repositories page and use the Sync Account button to sync your Travis account with GitHub.
Activate the repo using the slider switch in front of it.
Add a .travis.yml file to instruct Travis CI to build and deploy the site when you push to the repository. An example .travis.yml file that can accomplish this is given below:
Once the build succeeds, your MarkBind site should be online at http://<username|org>.github.io/<repo> e.g., http://se-edu.github.io/se-book. Travis CI will automatically build and deploy changes to your site as you push new changes to the repository after a few seconds. You might have to go to the Settings of your repo and configure it to publish GitHub Pages from the gh-pages branch as MarkBind deploys to that branch by default.
Configuring Travis CI to only deploy from a specific repository
When Travis CI is set up as explained above, Travis CI will attempt to deploy the site from any repository it is in, including forks.
-If you want Travis CI to only deploy from a specific repository (eg. only from your main site repository), you can add to the deploy phase a repo condition in the form owner_name/repo_name.
For example, if you only want Travis CI to deploy the site when it is run from the se-edu/se-book repository, the following repo condition should be added to .travis.yml.
Once the build succeeds, your MarkBind site should be online at http://<username|org>.github.io/<repo> e.g., http://se-edu.github.io/se-book. Travis CI will automatically build and deploy changes to your site as you push new changes to the repository after a few seconds. You might have to go to the Settings of your repo and configure it to publish GitHub Pages from the gh-pages branch as MarkBind deploys to that branch by default.
Configuring Travis CI to only deploy from a specific repository
When Travis CI is set up as explained above, Travis CI will attempt to deploy the site from any repository it is in, including forks.
+If you want Travis CI to only deploy from a specific repository (eg. only from your main site repository), you can add to the deploy phase a repo condition in the form owner_name/repo_name.
For example, if you only want Travis CI to deploy the site when it is run from the se-edu/se-book repository, the following repo condition should be added to .travis.yml.
on:
+branch:master
+repo:se-edu/se-book
+
+
-
-
+
+
+ 5.453125 4.089844 L 13.453125 4.089844 Z M 13.453125 13.636719 " data-v-0eabf1c4>
-
The repo value can be changed to your specific repository as desired.
Navigate to the project settings page of your repository in AppVeyor CI.
On the left menu, click on Environment.
Under the heading Environment variables, add a custom environment variable named GITHUB_TOKEN, with the value set to the personal access token that was generated in the first step. Ensure that you toggle variable encryption by clicking on the padlock.
Remember to click Save at the bottom of the page.
Add a appveyor.ymlfile at the root of your MarkBind site's repository to instruct AppVeyor CI to build and deploy the site to GitHub Pages when you push to your repository. More information on customizing appveyor.yml can be found in AppVeyor documentation. An example appveyor.yml file is given below:
Navigate to the project settings page of your repository in AppVeyor CI.
On the left menu, click on Environment.
Under the heading Environment variables, add a custom environment variable named GITHUB_TOKEN, with the value set to the personal access token that was generated in the first step. Ensure that you toggle variable encryption by clicking on the padlock.
Remember to click Save at the bottom of the page.
Add a appveyor.ymlfile at the root of your MarkBind site's repository to instruct AppVeyor CI to build and deploy the site to GitHub Pages when you push to your repository. More information on customizing appveyor.yml can be found in AppVeyor documentation. An example appveyor.yml file is given below:
-
-
+
+
+ 5.453125 4.089844 L 13.453125 4.089844 Z M 13.453125 13.636719 " data-v-3602e6fc>
-
Commit and push appveyor.yml to your GitHub repository. Thereafter, AppVeyor CI should begin to run the build script. You are able to view the current build status by clicking on your repository in the AppVeyor projects page. Once the build succeeds, you should be able to view your MarkBind site, after a few seconds, at http://<username|org>.github.io/<repo> e.g., http://se-edu.github.io/se-book.
In the projects dashboard, click on the Set Up Project button beside the repo containing your MarkBind site.
Configuring your repository in Circle CI
Once you have set up your project, click on the Project Settings button.
On the left, click on the Environment Variables tab and add a custom Environment Variable, GITHUB_TOKEN, which contains the value of your GitHub Personal Access Token.
Commit and push a config.yml file to the repo containing your MarkBind Site that instructs Circle CI to build and deploy your MarkBind site to GitHub Pages whenever you push to your repository. Ensure that the config.yml file is located in the <PROJECT_ROOT>/.circleci/ directory. A sample config.yml file is shown below:
Commit and push appveyor.yml to your GitHub repository. Thereafter, AppVeyor CI should begin to run the build script. You are able to view the current build status by clicking on your repository in the AppVeyor projects page. Once the build succeeds, you should be able to view your MarkBind site, after a few seconds, at http://<username|org>.github.io/<repo> e.g., http://se-edu.github.io/se-book.
In the projects dashboard, click on the Set Up Project button beside the repo containing your MarkBind site.
Configuring your repository in Circle CI
Once you have set up your project, click on the Project Settings button.
On the left, click on the Environment Variables tab and add a custom Environment Variable, GITHUB_TOKEN, which contains the value of your GitHub Personal Access Token.
Commit and push a config.yml file to the repo containing your MarkBind Site that instructs Circle CI to build and deploy your MarkBind site to GitHub Pages whenever you push to your repository. Ensure that the config.yml file is located in the <PROJECT_ROOT>/.circleci/ directory. A sample config.yml file is shown below:
-
-
+
+
+ 5.453125 4.089844 L 13.453125 4.089844 Z M 13.453125 13.636719 " data-v-3602e6fc>
-
After you have pushed the config.yml file to your remote repo, you should see Circle CI starting to run the Deploy job in your projects dashboard. Once it is successful, you should be able to view your MarkBind site at http://<username|org>.github.io/<repo>.
Update the build settings as follows and hit Deploy site:
Build Command: npm i markbind-cli -g && markbind build --baseUrl
Publish directory: _site
Show advanced: Add a new variable with the key as NODE_VERSION and the value as 16 or higher
Now your site will be deployed on Netlify at the given address specified after deployment. It will be updated automatically when the default branch of your repo is updated.
Previewing Pull Requests for MarkBind sites
If you are hosting your MarkBind project on GitHub, you can setup in order to automatically build and deploy the modified MarkBind site based on the changes in the PR.
Previewing PRs using Netlify
By following the steps to deploy to Netlify in the previous section, you would automatically be able to preview PRs.
You can preview the updated site at the bottom of the pull request by clicking on details link in the PR:
For more information on previewing PRs with Netlify, you may refer to Netlify's docs.
Previewing PRs using Surge
You may also preview PRs using Surge, which is an NPM package that does static web publishing. Here are the steps to do so:
First install Surge using by typing npm install --global surge on your terminal.
Next, type surge in the terminal. You should see the following prompt:
Proceed to create a Surge account. After you have set up your account, you should see the following screen:
Hit CTRL-C on your keyboard to quit the current running Surge process.
The rest of the Surge setup is unnecessary for the purposes of setting up PR previews. You may still proceed with the rest of the setup such as setting the project directory and the domain name, if you wish to.
Next, type surge token to generate your surge token.
In the repo of your MarkBind site, create a new secret by going to "Settings"->"Secrets" and naming it as SURGE_TOKEN and setting its value to the value of the generated surge token.
After aquiring the surge token, you may want to utilize the provided MarkBind reusable workflows to conveniently set up your PR preview via Surge.sh.
If you would like to find out more about how it works behind the scene and how to do it yourself, read on to see the detailed steps that need to be specified in your workflow files.
Commit and push the following 2 files into your MarkBind site repo, in the directory <PROJECT_ROOT>/.github/workflows/.
receivePR.yml File
previewPR.yml File
Finally, you may open a PR to the repo of your MarkBind site. If everything is configured correctly, after a few minutes, you should be able to see a github-actions bot automatically commenting on the PR with a link to preview the updated MarkBind site.
For more information on Surge, you may refer to Surge's docs.
Relevant Tips & Tricks
Configuring Online Deployment platforms to use specific MarkBind version
After you have pushed the config.yml file to your remote repo, you should see Circle CI starting to run the Deploy job in your projects dashboard. Once it is successful, you should be able to view your MarkBind site at http://<username|org>.github.io/<repo>.
Update the build settings as follows and hit Deploy site:
Build Command: npm i markbind-cli -g && markbind build --baseUrl
Publish directory: _site
Show advanced: Add a new variable with the key as NODE_VERSION and the value as 16 or higher
Now your site will be deployed on Netlify at the given address specified after deployment. It will be updated automatically when the default branch of your repo is updated.
Previewing Pull Requests for MarkBind sites
If you are hosting your MarkBind project on GitHub, you can setup in order to automatically build and deploy the modified MarkBind site based on the changes in the PR.
Previewing PRs using Netlify
By following the steps to deploy to Netlify in the previous section, you would automatically be able to preview PRs.
You can preview the updated site at the bottom of the pull request by clicking on details link in the PR:
For more information on previewing PRs with Netlify, you may refer to Netlify's docs.
Previewing PRs using Surge
You may also preview PRs using Surge, which is an NPM package that does static web publishing. Here are the steps to do so:
First install Surge using by typing npm install --global surge on your terminal.
Next, type surge in the terminal. You should see the following prompt:
Proceed to create a Surge account. After you have set up your account, you should see the following screen:
Hit CTRL-C on your keyboard to quit the current running Surge process.
The rest of the Surge setup is unnecessary for the purposes of setting up PR previews. You may still proceed with the rest of the setup such as setting the project directory and the domain name, if you wish to.
Next, type surge token to generate your surge token.
In the repo of your MarkBind site, create a new secret by going to "Settings"->"Secrets" and naming it as SURGE_TOKEN and setting its value to the value of the generated surge token.
After aquiring the surge token, you may want to utilize the provided MarkBind reusable workflows to conveniently set up your PR preview via Surge.sh.
If you would like to find out more about how it works behind the scene and how to do it yourself, read on to see the detailed steps that need to be specified in your workflow files.
Commit and push the following 2 files into your MarkBind site repo, in the directory <PROJECT_ROOT>/.github/workflows/.
receivePR.yml File
previewPR.yml File
Finally, you may open a PR to the repo of your MarkBind site. If everything is configured correctly, after a few minutes, you should be able to see a github-actions bot automatically commenting on the PR with a link to preview the updated MarkBind site.
For more information on Surge, you may refer to Surge's docs.
Relevant Tips & Tricks
Configuring Online Deployment platforms to use specific MarkBind version
MarkBind supports a wide collection of Markdown-like basic content formatting syntax such as text styling, tables, lists, images, links, etc.
Headings
You can prepend the heading text with 1-6 # characters to indicate headings of levels 1-6.
CODE:
### Heading level 3...
###### Heading level 6
-
+
@@ -46,11 +46,11 @@
-
OUTPUT:
Heading level 3
...
Heading level 6
MarkBind auto-generates anchors for all headings.
+
OUTPUT:
Heading level 3
...
Heading level 6
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 omitted, joined by -).