Skip to content

v4.0.0
Compare
Choose a tag to compare
@jonahtanjz jonahtanjz released this 11 Jul 12:23
· 335 commits to master since this release
v4.0.0
9653054

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 Graphviz and Java for PlantUML support (#1905)
Fix undefined source path reported in the console warning (#1917)
#1903 Warn users if PlantUML diagrams are found but Graphviz is not installed (#1912)
#1844 Exclude node_modules from copying and page rendering in default site.json (#1925)
#1922 Use event listener to restore header on expand window (#1933)
#1895 Remove padding top from navbar site logo (#1935)
#1723 Update logger to work with progress bar (#1907)

Documentation

Fix docs formatting and typo (#1750)
Fix typo in docs for Tooltips (#1758)
Fix typo in deployingTheSite.md (#1766)
Update outdated information in docs (#1777)
Improve documentation for deployment (#1789)
update workflow and project structure of devGuide (#1786)
Replaced the use of deprecated <big> tag (#1802)
Remove index.md files from being searched (#1805)
Fix broken link in About Us (#1801)
Improve SettingUp documentation (#1795)
Update pop-up docs (#1832)
Improve devGuide to follow style guide (#1829)
Fix unexpected behavior in UG due to invalid HTML markup (#1837)
Add Components page to developer guide (#1865)
Add an explanation on how to use JavaScript chart libraries in MarkBind (#1872)
Fix UG display issues when using the outputBox boilerplate (#1889)
Fix typos in docs (#1902)
Fix modal positioning in panel headers (#1910)
Include screenshot of dark themed code (#1827)
Improve User Guide - Adding Pages (#1923)
Improve User Guide - Getting Started and .gitignore file (#1924)
Fix incorrect locale examples in user guide (#1943)
Update dev guide - merging PRs (#1951)

Other Changes

Code Quality

Remove effect attribute from tests (#1783)
#1812 MarkBind name change (#1828)
#1702 Migrate modals from bootstrap-vue to vue-final-modal (#1849)
#1702 Migrate popovers and tooltips to floating-vue (#1868)
Remove bootstrap-vue (#1873)
#1817 Refactor MdAttributeRenderer and includePanelProcessor (#1896)
Remove package.lock file in packages/core (#1908)
#1421 Adopt TypeScript for core package (#1877)
#1862 Upgrade nodejs to v14 (#1920)
#1921 Add clean script in setup and build (#1927)
#1560 Use css variables for fixed header style updates (#1928)
#1921 Discontinue the use of TypeScript project references (#1934)
#1754 Refactor math formulae support (#1940)

Dependencies

Bump font-awesome from 5.14.0 to 5.15.4 (#1822)
Bump jest from 26.1.0 to 27.5.1 (#1823)
Bump ESLint dependencies (#1852)
Bump babel-jest from 26.1.0 to 27.5.1 (#1864)

DevOps

#1386 Update CI to test on all major OS and remove Appveyor (#1757)
#1386 Move docs deployment from Travis CI to GitHub Actions (#1759)
#1816 Set concurrency property to cancel unnecessary workflow runs (#1821)
#1857 Improve existing GitHub issue templates (#1860)
#1461, #1004 Update GitHub Action for MarkBind (#1880)
#1876 Update CI to run on all PR events (#1878)
#1871 Update GitHub issue template checkbox to dropdown (#1897)
Update PR template (#1941)

Assets 2