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)

v3.0.3

markbind-cli

User Facing Changes

Features

Add hamburger animations to page/site nav icon (#1596)

Fixes

Add appFactory to Vue initialization for setup without search (#1592)
Add whitelist of tags to validate (#1593)
Handle baseUrl in live-preview reload check (#1594)
Fix unresponsive fixed header padding
(#1595)
Parse <md> tag in Markdown as inline (#1598)
Fix blocking ::before pseudo element in panel
(#1603)

Documentation

Fix PlantUML typo in diagrams.mbdf of User Guide
(#1600)