v5.0.0

markbind-cli

User Facing Changes

Breaking Changes

1. Change scroll top button to component by @yucheng11122017 in #2170

Scroll to Top button is changed to a component to allow for more flexibility in its usage. This includes allowing users to

• Not use it if they want
• Change the icon
• Change the icon size and color
• Change the position

It is no longer automatically added to pages on the website. To add the Scroll to Top Button to a website, add the component to the layout page

In layout page

...
<scroll-top-button />
...

This button is still added to the default layout when users initialise a MarkBind project.

Example insertion:

<div id="flex-body">
  <div id="content-wrapper">
    {{ content }}
  </div>
  <scroll-top-button></scroll-top-button>
</div>

2. Update deploy command to build site before deployment by @lhw-1 in #2218

The markbind deploy command now builds and generates the site by default, and this automatic build step can be skipped using the newly introduced --no-build flag. This change is to accommodate the common use case consisting of the following steps:

markbind build
markbind deploy

The markbind build step can now be omitted.

It should be noted that if you have been generating your site with specified values for baseUrl or path to siteConfig.json, you should add the --no-build flag to the markbind deploy command to avoid re-building the site with default values.

If this was being done previously:

markbind build --site-config ./otherSiteConfig.json --baseUrl myDir
markbind deploy

It should now be changed to:

markbind build --site-config ./otherSiteConfig.json --baseUrl myDir
markbind deploy --no-build

3. Deprecate slots, attributes and syntax by @itsyme in #2208

Currently, there are quite a few attributes/slots/syntaxes that are deprecated. They may or may not be listed in the docs, implemented in the codebase, or log a warning when used. We now completely remove them.

Overview:

Component	Deprecated	In docs	In code	CLI warning?
Modals	modal-footer -> footer	yes	yes	yes
Modals	modal-header -> header	no	yes	yes
Question	has-input -> type="text"	yes	yes	no
Question	invalid question types[1]	no	yes	no
Icons	{{ prefix_name }} -> :prefix_name:	yes	no	no

^[1] This seems a bit more complex compared to the others - it looks like there is some backwards compatibility intentionally preserved (#1274, #1293)

To migrate:
Modal:

• modal-header -> header
  • modal-header attribute has been fully deprecated
  • To migrate, replace the modal-header attribute with just header with the text in the attribute unchanged
  • e.g. <modal modal-header="HEADER TEXT"> to <modal header="HEADER TEXT">
• modal-footer -> footer
  • modal-footer attribute has been fully deprecated
  • To migrate, replace the modal-footer attribute with just footer with the text in the attribute unchanged
  • e.g. <modal modal-footer="FOOTER TEXT"> to <modal footer="FOOTER TEXT">

Question:

• has-input -> type="text"
  • has-input attribute has been fully deprecated
  • To migrate, replace the has-input attribute with type="text"
  • e.g. <question has-input> to <question type="text">
• Invalid question types (invalid type attribute) now not supported
  • To migrate, give the question a valid type: mcq, checkbox, blanks, text

Icons:

• {{ }} -> : :
  • To migrate, replace all {{ and }} to :
  • e.g. {{emoji-name}} to :emoji-name:

4. Deprecate theme attribute in site config JSON by @itsyme in #2235

Fully deprecates theme attribute in site config JSON.

theme attribute in site config JSON has been fully deprecated.

To migrate:
Use "style": {"bootstrapTheme": "..."} instead of "theme": "...".

For example,
Original (in site.json):

{
"theme": "bootswatch-cerulean"
}

Updated (in site.json):

{
  "style": {
    "bootstrapTheme": "bootswatch-cerulean"
  }
}

5. Upgrade to use node 16 by @yucheng11122017 in #2233

Node.js version 14 is no longer supported by Markbind as it is due to reach it's end of life in 30 April 2023. The minimum required version of Node.js is now 16. Users are to upgrade to at least version 16 of Node.js.

6. Upgrade PlantUML version to 1.2023.10 by @lesterong in #2311

The PlantUML plugin has been updated from 1.2020.7 to 1.2023.10.

Changes
(For detailed changes, please view them on plantuml website)

1. The default theme has been updated in this version of PlantUML. To use the old theme, use the skin rose directive.

2. There is a slight shift in the layout with the new default theme, and the position of annotations on PlantUML diagrams may have to be updated.
3. PlantUML now separates namespaces by default. This behavior can be disabled using the set separator none command.

4. PlantUML no longer allows for two elements with the same name. A possible workaround is to provide an alias to one of the elements, so their names do not conflict.

'alias as c provided
rectangle checkout as c {
  (checkout) .> (payment) : include
}

5. PlantUML does not render underlines in class diagrams using the Creole syntax. A possible workaround is to use the HTML syntax to define underlines. For example, <u>Class Name</u> will render an underline, but not __Class Name__.

6. The font used in Gantt Charts has been updated. As a result, some of the text may appear outside of the bars.

7. Clean up docs & tests for variables by @tlylt in #2301

A newly generated site (e.g. via markbind init) will no longer contain the following erroneous line in _markbind/variables.md:

<variable from="variables.json" />

This way of importing variables from an external file within the global variables.md is not supported.

For existing sites migrating to the latest version, please check that you do not have the above line in your _markbind/variables.md file as it will not work as expected and will log a warning. Please remove such a line if found.

8. Replace jQuery with vanilla JS by @yucheng11122017 in #2130

jQuery is no longer supported in Markbind. This is because jQuery is no longer as relevant since it can be replaced with modern DOM APIs.

If jQuery is used in your website, either

• import jQuery
• refactor jQuery usage in favour for modern DOM APIs. This website is useful when refactoring jQuery usages.

9. Generate .gitignore on init command by @lhw-1 in #2248

A .gitignore file is now added by the markbind init command by default.

Default rules for the .gitignore file:

# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
lerna-debug.log*
_markbind/logs/

# Dependency directories
node_modules/

# Production
_site/

# Env
.env
.env.local

# IDE configs
.vscode/
.idea/*
*.iml

This file is only generated when initializing a new MarkBind site from scratch, and not when converting a set of pre-existing documents into a MarkBind site using markbind init --convert. As such, this does not require any additional actions from the user.

10.Upgrade fontawesome version to latest (v6) from v5 Resolves #2242 by @SPWwj in #2326

We upgraded from [email protected] to [email protected].
The current icons will be preserved (i.e. you don't have to make any changes if you don't want to) due to Font Awesome's backward compatibility.
With Version 6

• new icons are available
• some icons have been renamed
• syntax/usage has changed slightly

For details please refer to Font Awesome's changelog

Features

• Contact form plugin by @yucheng11122017 in #2191
• Add autogenerated bread...

v4.1.0

markbind-cli

User Facing Changes

Features

• Add <page-nav-print /> to allow printing (#2069)
• #1899 Add template for 404 page (#1955)
• #1475 Support a simple font colouring markdown syntax (#1988)

Enhancements

• #1764 Include repeated attributes warning for panel elements (#2053)

Fixes

• Fix parsing for code highlight rules (#2138)
• #2083 Update Question/Quiz component design (#2131)
• #242 Remove override of title in the init site (#2128)
• Fix bug to allow highlighting of code with '-' (#2132)
• #2055 Fix bug with dangling separator in pageNav when no title and nav headings given (#2058)
• #2026 Fix search bar to include frontmatter keywords (#2056)
• #1954 Fix hasPageNav logic to only apply data-bs attributes if there are navigable headings (#2054)
• #1891 Configure Webpack output path for markbind serve -d (#2044)
• #2045, #2028 Fix image linkify and alt attribute (#2046)
• #1830 Nunjucks embeds override variables defined in the file it is called in (#2047)
• #1804 Deprecate TipBox (#2121)
• Use absolute URLs for assets (#2032)

Documentation

• #2124 Fix misaligned block in UG (#2127)
• #1835 Update Tips and Tricks documentation for raw / endraw tags (#2118)
• #2087 Rephrase "Creating Custom Fragments" Section (#2122)
• Fix broken link in UG (#2110)
• #2070 Add CS3203 website to showcase (#2102)
• #1859 Update to frontmatter in docs (#2049)
• #2033 Update CLI build command description (#2042)
• #1975 Add navigation documentation for previous/next page navigation (#2048)
• #1997 Create onboarding BootCamp (#2063)
• #2071 Update placement of Onboarding in dev docs (#2086)
• #2144 Update TypeScript Migration documentation on git hooks (#2151)

Other Changes

Code Quality

• Migrate most of NodeProcessor dependencies to TS (#2136)
• Migrate template to TypeScript (#2143)
• #2147 Convert Template function to class (#2148)
• Migrate Plugin and PluginManager to TypeScript (#2133)
• Migrate MarkdownProcessor and related files to TS (#2111)
• Migrate CodeBlockButtons plugins to TypeScript (#2135)
• Migrate scriptAndStyleTagProcessor to Typescript (#2113)
• Migrate core/src/External to TypeScript (#2103)
• Migrate PageVueServerRenderer to TypeScript (#2098)
• Migrate nunjucks wrappers to typescript (#2036)

DevOps Changes

• Update bug-report template (#2123)
• #2040 Fix annotation warnings in GitHub Actions (#2041)
• #1966, #2021 Running tests/lints before commit and push (#2035)

Dependencies

• #2039 Update webpack 4 to webpack 5 (#2153)
• Use @types/node at ^17.0.22 (#2158)

Miscellaneous

• #1945 Migrate vue-components README (#2104)

v4.0.2

markbind-cli

User Facing Changes

1. Revert migration to day.js (#2027)

Due to day.js not fully supporting all the formats of moment.js, it is considered a breaking change. As this was introduced in v4.0.1, it will break backward compatibility with the affected formats. Hence we decided to revert this change and postpone it to v5. For full discussion: #2007 (comment)

---

Enhancements

#1998 Remove empty keywords clause from essay questions (#2023)
#311, #1972 Avoid duplicating search results (#1968)

---

Documentation

#1982 Update outdated code block images in UG (#2019)
#1995 Add notes on unit tests in developer guide (#2022)
Update contributors table and remove unnecessary margin top (#2031)

Other Changes

Code Quality

#1913 Migrate Site/Page config classes to typescript (#2030)
#1913 Migrate nodeprocessor and its minor dependencies to typescript (#2029)

---

Dependencies

Bump lerna to v4 (#2017)

---

Miscellaneous

#1989 Update PR template content (#2016)

v4.0.1

markbind-cli

User Facing Changes

Features

Add new question type for questions with multiple blanks (#1958)

---

Enhancements

#665 Set search bar width to placeholder text (#1959)

---

Fixes

#1969, #1985 Downgrade floating-vue to 1.0.0-beta.14 (#1999)
#1979 Fix minimal panel close button on next line (#2000)
#2002 Fix searchbar overflowing for mobile (#2009)
#2003 Fix FOUC in navbar (#2004)
#2010 Fix Algolia search on mobile view (#2011)
#2008, #1909 Remove modals with duplicate id (#2012)

---

Documentation

#1932 Fix broken link in user guide (#1963)
#1879 Add previous/next page feature for Developer Guide (#1971)
Update Algolia documentation (#2014)

Other Changes

Code Quality

#1855 Update regex to enable prefer-regex-literals rule (#1956)
#792 Update test_site to test file ignore (#1978)
#1986 Pass SiteConfig to reduce duplication within PageConfig (#1990)
Reorganize constants in packages/core (#1987)
#1937, #1130 Handle generated plantuml files in functional testcases (#1993)
#2005 Clean up eslint warnings by disabling the checks inline (#2006)
Migrate moment to dayjs (#2007)
#1944 Update all references of deprecated URL parse to use parse from a new dependency url-parse (#2001)

---

DevOps

Run CI checks for all-contributors' PRs (#1973)
Update post-checkout hook to auto build backend (#1994)

---

Miscellaneous

#1846 Remove seg tags (#1962)

v4.0.0

markbind-cli

User Facing Changes

Breaking Changes

1. Algolia plugin update (#1730)

Algolia plugin has been updated from v2 to v3. Under plugin context, the option debug has been removed and algoliaOptions has been changed to searchParameters . More details on the supported search parameters can be found on the Algolia's Search API Parameters page.

Old pluginContext in site.json:

"pluginsContext": {
   "algolia": {
     "apiKey": "25626fae796133dc1e734c6bcaaeac3c", // required
     "appId": "R2IYF7ETH7", // required
     "indexName": "docsearch", // required
     "algoliaOptions": { "hitsPerPage": 10 }, // changed to searchParameters
     "debug": false // removed
   }
 }

New pluginContext in site.json:

"pluginsContext": {
   "algolia": {
     "apiKey": "25626fae796133dc1e734c6bcaaeac3c", // required
     "appId": "R2IYF7ETH7", // required
     "indexName": "docsearch", // required
     "searchParameters": { "facetFilters": ["site:yoursite.com"] } // optional
   }
 }

Note that in v3, the search box requires a <div> and an <input> is no longer supported.

Old custom search bar:

<input id="algolia-search-input">

New custom seach bar:

<div id="algolia-search-input"></div>

When using the new Algolia's plugin, the UI has changed from a dropdown to a modal (screenshots of the UI changes can be seen in #1730). This does not require any additional actions from the user.

2. Removal of .mbdf and .mbd file type support (#1762)

.mbdf was created to easily exclude fragments from page generation and .mbd was created with the intent of making our own extension called .markbind. Since the addition of pagesExclude in #1328, the definition of fragments can be described by the user using specific file name patterns. Furthermore, simply sticking to the canonical default .md ensures familiarity and does not require additional configurations to the IDEs for syntax highlighting. For these reasons, the two extensions seem obsolete and hence are removed.

Previously, to exclude fragment files, .mbdf, from rendering, the user could do something like the following in site.json:

"pages": [
   {
     "glob": ["**/*.md"]
   }
]

The same can be acheived using the pageExclude attribute with .md files, provided the user named their fragment files with the pattern *-fragment.md:

"pagesExclude": ["**/*-fragment.md"]

3. Upgrade to Bootstrap 5 (#1882)

text-dark must be manually applied for bg-warning, bg-info, bg-light (previously text would automatically be dark for these classes).

If you have been using Bootstrap classes in your MarkBind sites, do refer to the migration guide for the full list of breaking changes on Bootstrap 5.

4. Change fixed header to sticky header (#1939)

Since no assumptions of the user's header's height can be made at build time, runtime style detection is required to calculate the header height used in the fixed-header-padding class. This causes a flash of unstyled content briefly before this detection is done (the content is hidden behind the header).

To resolve the issue, a sticky header has been implemented to replace the current fixed header, which "natively" offsets content below it.

It should be noted that header height detection is still required however, particularly for offsetting the sticky positioning of the navigation menus on the side (top: var(--sticky-header-height)), since they are (usually) much shorter than the main content element.

This header height is now exposed using the css variable var(--sticky-header-height) for use in the user layout files.

With the above changes, fixed header has been changed to a sticky header. Users currently with fixed header will need to change their headers' fixed attribute to use the sticky attribute.

Old fixed header:

<header fixed>
  ...
</header>

New sticky header:

<header sticky>
  ...
</header>

The generated main.css in the stylesheets folder will also need to be updated for the site and page navigation to work properly. The differences between the original and updated main.css file can be found in this commit, Implement sticky header (#1939).

Note: If users have not make any changes to their main.css since initializing the site, users can simply replace their current main.css file with the updated v4.0.0 main.css file.

Old main.css:

...
#content-wrapper {
   flex: 1;
   margin: 0 auto;
   min-width: 0;
   max-width: 1000px;
   padding: 0.8rem 20px 0 20px;
   transition: 0.4s;
   -webkit-transition: 0.4s;
}

#site-nav,
#page-nav {
   position: sticky;
   top: 0; /** Updated **/
   flex: 0 0 auto;
   padding-top: 1rem; /** Removed **/
   max-width: 300px;
   width: 300px;
}

#site-nav {
   display: flex; /** Removed **/
   flex-direction: column; /** Removed **/
   border-right: 1px solid lightgrey;
   padding-bottom: 20px;
   z-index: 999;
   max-height: 100vh; /** Removed **/
}

...

#page-nav {
   display: block; /** Removed **/
   border-left: 1px solid lightgrey;
   max-height: 90vh; /** Removed **/
}

#page-nav .nav-component {
   max-height: 90vh; /** Removed **/
}

...

New main.css:

...
#content-wrapper {
   flex: 1;
   margin: 0 auto;
   min-width: 0;
   max-width: 1000px;
   overflow-x: auto; /** Added **/
   padding: 0.8rem 20px 0 20px;
   transition: 0.4s;
   -webkit-transition: 0.4s;
}

#site-nav,
#page-nav {
   display: flex; /** Added **/
   flex-direction: column; /** Added **/
   position: sticky;
   top: var(--sticky-header-height); /** Updated **/
   flex: 0 0 auto;
   max-width: 300px;
   max-height: calc(100vh - var(--sticky-header-height)); /** Added **/
   width: 300px;
}

#site-nav {
   border-right: 1px solid lightgrey;
   padding-bottom: 20px;
   z-index: 999;
}

...

#page-nav {
   border-left: 1px solid lightgrey;
}

...

Removal of fixed-header-padding class

The class fixed-header-padding has been removed. Users can safely remove this class from their MarkBind sites.

Non-sticky announcement

Users are also able to create a "non-sticky" announcement that does not follow the sticky header as the page is scrolled down.

Example usage:

<div class="w-100 p-1 bg-warning text-center">
  **This is a temporary "non-sticky" announcement that does not follow the header as you scroll down!**
</div>

<header sticky>
  ...
</header>

5. Line numbers for code blocks are hidden by default (#1734)

For most of the use cases, there is a slight preference to hide the line numbers on code blocks. To make it simpler for the users, line numbers are hidden by default so that the users do not have to manually disable the line numbers on each code block. For users that still prefer to have line numbers enabled by default, they can still to do it easily by following the description below.

If user wants to have line numbers enabled globally, they can still achieve this by adding the following to the style attribute in site.json file:

...
"style": {
   "codeLineNumbers": true // optional, false if omitted
 },
...

User can also enable line numbers for individual code blocks by adding the {.line-numbers} to the code block:

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

If line numbers has been enabled globally, user can hide the line numbers for individual code blocks by adding the {.no-line-numbers}:

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

---

Features

#1754 Support $$ as a delimiter for math formulae (#1824)
#1660 Add <tree> component for folder structure visualisations (#1807)
#898 Add Annotation Feature (#1858)
#1946 Add support for title suffix (#1947)

---

Enhancements

#1201 Enhance appearance of minimised panels (#1694)
#59 Allow for reactivity in popover and tooltip contents (#1748)
#1773 Add badges to README.md (#1785)
#59 Implement src attribute for popovers (#1780)
#1418, #1723 Report broken links only once (#1819)
#1466 Add GitHub reusable workflows for PR preview via surge (#1853)
#1842 Update copy/wrap button to be visible on mouse hover (#1949)

---

Fixes

#1736 Fix backslash bugs in convert feature (#1742)
#1726 Fix extra newline in convert feature (#1746)
#1774 Disable fuzzy link and include autolink feature in UG (#1779)
Fix tipBox content overflow (#1787)
#1429 Fix search sizing on mobile (explore navbar overflow) (#1760)
#1745 Make pop-ups accessible (#1833)
#671 Update markdown-it-linkify-images to v2.0.0 (#1838)
#1803 Better default titles in search: Remove file format ending (#1826)
#1845 Fix MarkBind internal package dependencies (#1848)
#1820, #1874 Fix edge cases of link validation and conversion (#1875)
#1903 Update steps in CI to set up Graph...

v3.1.1

markbind-cli

User Facing Changes

Features

#897 Improve hr styles (#1685)

Fixes

#1124 Fix missing margin above code blocks (#1706)
#1725 Add relative links to the convert template file (#1728)
#1729 Add appId to Algolia plugin (#1733)
#1720 Apply v-pre to all anchor elements in pageNav (#1732)

Documentation

#1710 Fix missing images from Plugin page of user guide (#1711)
#1015 Add documentation on indentation support for components (#1719)

Other Changes

Dependencies

#1676 Update markdown-it version and relevant patches (#1701)

Miscellaneous

#1504 Deprecate some component attributes (#1722)

Remove implementation of already deprecated attributes in v3.0.0

v3.1.0

markbind-cli

User Facing Changes

Breaking Changes

Change top nav from accordion to two rows on mobile (#1690)

Any existing custom styling relying on the old accordion-style navbar in mobile view will need to be updated.

Features

#1581 Add theme prop for <box> components (#1647)
#900 Give an easy syntax to center-align (#1657)
#1289 Wrap fenced code blocks on-demand (#1668)
#1505 Support Google Fonts Icons (#1681)

Enhancements

Dial down header hiding sensitivity (#1636)
#1669 Adjust margins and padding for better readability (#1686)

Fixes

#1667, #1680 Fix premature declaration of link in deploy command (#1679)
#1634 Fix default layout footer issue on medium viewports (#1692)
Fix navbar child highlighting mode (#1700)
#1682 Fix default html index page not detected by watchers (#1696)
#1703, #1704 pin colorsjs at 1.4.0 (#1705)

Documentation

#1669 Adjust margins and padding for better readability (#1686)
#1457 Convert logo to svg (#1689)
Reorganise usingComponents page (#1698)

Other Changes

DevOps Changes

#1678 Fix LF text normalisation rules (#1683)

Dependencies

Update Commander.js version (#1650)
#1639 Update octicon version (#1652)
#1549 Fix Highlight Deprecation (#1691)

Miscellaneous

#1644 Fix bug-report issue template file path (#1658)
#1655 Update workflow docs on managing dependencies (#1659)
#1673 Update setup instruction (#1674)
Add Contributors list (#1662)
#1599 Update Project Structure Description & Fix Code Style (#1695)
#781 Include unit tests for default plugins (#1684)

v3.0.6

markbind-cli

User Facing Changes

Fixes

#1607 Move all heading id assignment to after postprocess (#1635)

v3.0.5

markbind-cli

User Facing Changes

Features

Adopt lazy loading for Pic component (#1626)

Enhancements

Support opt-out of printing certain tabs (#1612)

Fixes

Add left padding to page nav title (#1625)
Fix warning for coerced boolean props (#1630)

Other Changes

Miscellaneous

Implement span.anchor in panel to replace id (#1609)

v3.0.4

markbind-cli

User Facing Changes

Fixes

Fix warning for active prop in tab (#1613)
Add missing site-nav tag to html special tags (#1622)

Documentation

Update UG to include double quotes for diagram example (#1624)