v5.0.0

[tlylt]

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.

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 fontawesome-free@5.15.4 to fontawesome-free@6.4.0.
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 Contact form plugin #2191
• Add autogenerated breadcrumbs component by @itsyme in Add autogenerated breadcrumbs component #2193

Enhancements

• Remove panel closing transition by @yucheng11122017 in Remove panel closing transition #2159
• Add shake effect for none selected in MCQ by @itsyme in Add shake effect for none selected in MCQ #2195
• Tweak sitenav design by @itsyme in Tweak sitenav design #2204
• Clean up default init template by @lhw-1 in Clean up default init template #2165
• Update default template with UG links and useful information by @lhw-1 in Update default template with UG links and useful information #2225
• Update Breadcrumb icons by @itsyme in Update Breadcrumb icons #2265
• Reduce Bottom Spacing for Seamless Panels by @EssWhyy in Reduce Bottom Spacing for Seamless Panels #2319
• Standardise size of tabgroup buttons in tabset to match that of non-tabgroup buttons. by @yucheng11122017 in Standardise size of tabgroup buttons in tabset to match that of non-tabgroup buttons. #2202
• Create alternative syntax for frontmatter by @EltonGohJH in Create alternative syntax for frontmatter #2145

Fixes

• Fix handling of empty segment includes by @jovyntls in Fix handling of empty segment includes #2180
• Support iconColor in box when light/seamless is used by @yucheng11122017 in Support iconColor in box when light/seamless is used #2178
• Fix Quiz expanding between questions by @itsyme in Fix Quiz expanding between questions #2184
• Fix panel transition abruptly snapping to the end by @yucheng11122017 in Fix panel transition abruptly snapping to the end #2200
• Update anchor navigation with scroll margin top by @elroygohjy in Update anchor navigation with scroll margin top #1953
• Fix backslash not working on non-windows machine by @EltonGohJH in Fix backslash not working on non-windows machine #2255
• Fix minor UI issues with default.md by @lhw-1 in Fix minor UI issues with default.md #2278
• Fix unexpected closing of longer modal when clicking on scrollbar by @WillCWX in Fix unexpected closing of longer modal when clicking on scrollbar #2322
• Fix bug with quiz next button skipping questions by @lesterong in Fix bug with quiz next button skipping questions #2312

Documentation

• Add details to the release process in devGuide by @tlylt in Add details to the release process in devGuide #2168
• Update headings to match sidebar by @itsyme in Update headings to match sidebar #2152
• Fix broken links in UG by @yucheng11122017 in Fix broken links in UG #2173
• Update Typescript migration documentation for Merging by @ong6 in Update Typescript migration documentation for Merging #2134
• Document cyclical error in include in UG by @yucheng11122017 in Document cyclical error in include in UG #2198
• Change format of nunjucks code and output by @yucheng11122017 in Change format of nunjucks code and output #2175
• Support horizontal layout in code and output boilerplates by @yucheng11122017 in Support horizontal layout in code and output boilerplates #2194
• Add missing slots-info modal to pages in UG by @yucheng11122017 in Add missing slots-info modal to pages in UG #2223
• Rephrase MarkBind Vue components and Bootstrap by @itsyme in Rephrase MarkBind Vue components and Bootstrap #2205
• Fix wrong link in typescript docs in DG by @yucheng11122017 in Fix wrong link in typescript docs in DG #2227
• Add tags to links in docs by @itsyme in Add tags to links in docs #2183
• Update examples for CLI Commands in UG by @lhw-1 in Update examples for CLI Commands in UG #2247
• Remove includes with variables by @yucheng11122017 in Remove includes with variables #2252
• Add tip on solving merge conflicts in functional tests by @yucheng11122017 in Add tip on solving merge conflicts in functional tests #2261
• Update expanded siteNav description by @itsyme in Update expanded siteNav description #2263
• Add documentation on migrating node.js by @yucheng11122017 in Add documentation on migrating node.js #2256
• Remove line numbers from code blocks by @Yvad60 in Remove line numbers from code blocks #2269
• Fix broken links in migratingNodeJs by @itsyme in Fix broken links in migratingNodeJs #2275
• Add intra-site link instructions to docs by @itsyme in Add intra-site link instructions to docs #2276
• Update DG to be consistent with default template by @lhw-1 in Update DG to be consistent with default template #2288
• Add missing page links to sitenav and workingWithSites overview by @EssWhyy in Add missing page links to sitenav and workingWithSites overview #2307
• Add code block copy plugin to docs by @WillCWX in Add code block copy plugin to docs #2305
• Replace set-output with $GITHUB_OUTPUT in documentation by @yucheng11122017 in Replace set-output with $GITHUB_OUTPUT in documentation #2259
• Add tag to fix Vue warning in frontmatter docs by @EltonGohJH in Add <tbody> tag to fix Vue warning in frontmatter docs #2274

Developer Facing Changes

Code Quality

• Migrate linkProcessor and SiteLinkManager to TypeScript by @jovyntls in Migrate linkProcessor and SiteLinkManager to TypeScript #2149
• Migrate includePanelProcessor to TypeScript by @jovyntls in Migrate includePanelProcessor to TypeScript #2160
• Migrate Page/index.js to TypeScript by @jovyntls in Migrate Page/index.js to TypeScript #2169
• Integrate TS classes in core package by @jovyntls in Integrate TS classes in core package #2176
• Migrate core/src/html tests to TypeScript by @jovyntls in Migrate core/src/html tests to TypeScript #2192
• Migrate default plugins to TypeScript by @jovyntls in Migrate default plugins to TypeScript #2199
• Migrate core/src/lib/markdown-it to TypeScript by @yucheng11122017 in Migrate core/src/lib/markdown-it to TypeScript #2231
• Migrate plugin tests to Typescript by @jovyntls in Migrate plugin tests to Typescript #2213
• Migrate non-default plugins to TypeScript by @jovyntls in Migrate non-default plugins to TypeScript #2230
• Remove empty title tags in generated tests by @lhw-1 in Remove empty title tags in generated tests #2186
• Create unified types for nodes by @jovyntls in Create unified types for nodes #2201
• Refactor core package to use Node types by @jovyntls in Refactor core package to use Node types #2221
• Fix typo in Dropdown.spec.js by @itsyme in Fix typo in Dropdown.spec.js #2243
• Clean up & standardise TypeScript conventions by @jovyntls in Clean up & standardise TypeScript conventions #2234
• Refactor cli/index.js by @lhw-1 in Refactor cli/index.js #2239
• Refactor initSite method in Site/index.js by @lhw-1 in Refactor initSite method in Site/index.js #2267
• Migrate Site/index.js to TypeScript by @jovyntls in Migrate Site/index.js to TypeScript #2270
• Migrate lib/nunjucks-extensions to TypeScript by @yucheng11122017 in Migrate lib/nunjucks-extensions to TypeScript #2321
• Remove un-used renameSlot method by @bibhu107 in Remove un-used renameSlot method #2286

DevOps Changes

• Update release note format to align with GitHub generated list by @tlylt in Update release note format to align with GitHub generated list #2254
• Add CI check for warnings & errors when building docs by @tlylt in Add CI check for warnings & errors when building docs #2287

Dependencies

• Upgrade lerna to version 6.5.1 by @EltonGohJH in Upgrade lerna to version 6.5.1 #2196

Miscellaneous

• add Yvad60 as a contributor for doc by @allcontributors in add Yvad60 as a contributor for doc #2271
• add WillCWX as a contributor for doc by @allcontributors in add WillCWX as a contributor for doc #2306
• add WillCWX as a contributor for code by @allcontributors in add WillCWX as a contributor for code #2328
• add EssWhyy as a contributor for doc by @allcontributors in add EssWhyy as a contributor for doc #2310
• add EssWhyy as a contributor for code by @allcontributors in add EssWhyy as a contributor for code #2329
• add SPWwj as a contributor for doc, and code by @allcontributors in add SPWwj as a contributor for doc, and code #2330
• add lesterong as a contributor for code by @allcontributors in add lesterong as a contributor for code #2318
• add bibhu107 as a contributor for code by @allcontributors in add bibhu107 as a contributor for code #2289
• Disable flaky quiz and scroll-to-top button tests by @itsyme in Disable flaky quiz and scroll-to-top button tests #2244
• Specify Netlify build settings by @tlylt in Specify Netlify build settings #2277

(We reverted the implementation below due to further discussion required)

• Add CollapseExpandButtons component by @itsyme in Add CollapseExpandButtons component #2206
• Revert expand collapse all buttons by @itsyme in Revert expand collapse all buttons #2303

Full Changelog: v4.1.0...v5.0.0

---

This discussion was created from the release v5.0.0.

[tlylt]

Hey everyone (& @MarkBind/active-devs)

I just wanted to send a quick message to express my heartfelt thanks to all of you for your incredible contributions that made our latest release possible. Lots of work culminated in this huge release!!! 🚀 🚀

For any discussions on migration issues, please comment below.