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)

v3.0.2

markbind-cli

User Facing Changes

Fixes

Fix site config live reload for custom site config names (#1579)
Fix ENOENT errors with panels referencing the same boilerplate (#1587)

v3.0.1

markbind-cli

User Facing Changes

Fixes

Fix dropdown highlight applying to all links (#1574)
Fix SSR hydration with <disqus> plugin (#1569)

v3.0.0

markbind-cli

User Facing Changes

Breaking Changes / Migration Guide

This section details the breaking changes resulting from the major version bump, and how to migrate to the newer versions.

However, in general, you may upgrade to the latest v2 release (currently v2.18.1) and deal with the deprecation warnings in the command line. Such breaking changes are mostly syntactic changes, and offer the same things functionality wise.

Breaking changes that cannot be dealt with in prior versions as such and require more attention will be delimited with ❗.

1. Layouts system shift ❗

We found that the old layout system based on combining multiple, separate files was very limiting in terms of creating expressive dom structures. It is also more difficult to use, as layouts consisted of individual layout files in their respective folders (_markbind/header / _markbind/navigation) and potentially a copy of the same files for compound layouts inside the _markbind/layouts folder.

In V3, the old layouts is completely discarded for a simpler, one file layout system.

Each page is now only ever tied to one layout file.

What about navigation?

We wanted to allow configuring the placement of navigation components (site nav and page nav) as well. These are now extracted into the <site-nav> and <page-nav> elements, but otherwise functions the same as before.

What about content reuse?

If you wish to reuse common sections (e.g. headers, navbars) across different layouts, this is very much still possible. We highly recommend using the old MarkBind's WYSIWYG <include /> system here to achieve this.

Migrating

If you are unsure where to start, first have a look at the documentation.

You may also rerun markbind init to create a separate template project with the new layout system used, then copying and adapting it over for use.

2. Removal of page <variable />s and <import>s

In v3, usage of <variable> elements as an alternative to nunjucks' {% set %} is completely removed. The rationale is simple, in that this introduces confusion as to how it functions compared to nunjucks' variants.

For <variable> elements referencing external json files, this is replaced with our {% ext %} nunjucks extension.

Note however, that the usage of <variable> tags inside variables.md (site variables) and <include><variable>...</variable></include> context variables are preserved, as they serve a different purpose from regular page variables.

3. Change of markdown underline syntax

Bigger (++... text ...++) and smaller (--... text ...--) text styles are introduced in V3 as a terser syntax for the very common use case of enlarging and minimising certain portions of text.

In doing so, the existing ++... underlined text ...++ syntax was changed to !!... underlined text ...!!.

4. Giving our prefab components proper markdown definitions ❗

The default behaviour of the markdown rendering library we use was to treat unrecognised html tags as "inline" elements, in that they generally functioned the same as <span> tags.

In V3, we gave some of the components "block" definitions in accordance with their use case. The exact definitions of "block" (note this is our coined up term) behind this are complex, and is better left to the CommonMark document itself.

A very common example is the termination of a markdown paragraph:

This is rendered into a `<p>...</p>` tag
<div>
This div element is a "block" element, and will "terminate" the paragraph above.
That is, the div element is put **after** the `<p>...</p>` element, and not inside, unlike `<span>` elements for example.
</div>

Suffice to say, things that should behave like how <div>s behave now do, these include:

• <box>
• <panel> elements without the minimized attribute
• <modal>
• <navbar>
• <question> and <quiz>
• <searchbar>

Migrating

Ironing out issues from this may be tedious depending on how far your existing project relies on the "inline" behaviour of these elements previously. We recommend going through every page to make sure that nothing is out of place.

5. Miscellaneous breaking changes

• We decided to standardise the attribute names of several markdown-in-attributes having similar placement and functionality here.
• The site configuration theme key is moved under the style.bootstrapTheme key.

---

Features

• Add expand-headerless attribute to <panel> (#1417)
• Add a per link attribute for disabling intralink validation (#1419)
• Add global disable intralink validation site configuration option (#1428)
• Add peek attribute to <panel> (#1425)
• Add omit-frontmatter attribute to <include> (#1448)
• Add disqus plugin (#1449)
• Add support for numerous CI platforms in `markbind deploy (#1453, #1460, #1471)
• <dropdown> elements can be recursively used as sub-menus (#1455)
• <site/page-nav> Navigation components are automatically accessible on smaller screens on pages with a <navbar> element (#1445)
• Many new options for targeted highlighting of text in code blocks (#1478)
• Most site.json attributes now reflect changes during markbind serve (#1514, #1529)
• BETA: Add -b option to markbind serve to be used with -o option. This option enhances the -o option with background building of pages that are not currently open in the browser, versus building pages only when they are navigated to (a small amount of loading time). (#1539)

---

Enhancements

• markbind serve -o now tracks all opened pages, enabling multi tab development! (#1513)
• Pages are now compiled by Vue and server-side rendered at build time, resolving FOUC (#1512, #1534, #1565)
• All tabs are now shown in print mode (#1498)
• Fixed headers now auto hide on scroll on smaller screens (#1474)
• Remove the opacity from <panel type="minimal"> components (#1469)
• Add animation to caret icon for panel expansion (#1465)
• Current link highlighting for <navbar> now highlights dropdown links (#1414)
• Add support for .csv files to {% ext %}

---

Fixes

• Fix highlight js deprecation warnings (#1521)
• Intralink conversion correctly converts links with fragments (#1493)
• Fix escaped html characters in search results (#1501)
• Fix <dropdown>s text colors in themes (#1451)
• Remove scroll to top button from print view (#1439)
• <markdown>, <md>, <include> tags are now parsed like <script / style> tags (#1434, #1540)
• Allow custom <script / style> - like special tags to be self closing (#1408)
• Inline markdown code in dark mode now prints as light mode (#1404)

---

Documentation

• Many more documentation fixes and updates in accordance with the new features and enhancements

v2.18.1

markbind-cli

User Facing Changes

Breaking Changes

(#28) Switch to !!...!! syntax for underline text (#1510)

It was highlighted that $$...$$ syntax may conflict with existing markdown documents using the same notation for latex math.
For better compatibility with existing documents, the underline text syntax is again switched to !!...!! syntax,
which may cause issues for documents that display raw !!...!! text.

The existing ++...++ and $$...$$ syntax is still retained, and deprecation warnings will be logged for these.

v2.18.0

markbind-cli

User Facing Changes

Breaking Changes

(#28) Add $$...$$ syntax for underline text (#1476)

In moving toward a markdown syntax for #28, v3 will be shifting completely toward $$...$$ delimiters for underline text,
discarding the existing ++...++ underline syntax.

This addition facilitates the migration process to v3, logging out warnings where the old underline syntax is used.

Existing content that displays raw $$...$$ symbols may be rendered into underlined text with this change.

v2.17.3

markbind-cli

User Facing Changes

Features

(#1387) Add a per-link attribute for disabling intralink validation (#1419)

Fixes

(#1437) Fix live preview for variables.md

v2.17.2

markbind-cli

User Facing Changes

Fixes

(#1424) Fix algolia search plugin initialisation

v2.17.1

markbind-cli

User Facing Changes

Fixes

(#1401) Fix dark mode inline code when printing (#1404)
(#1416) Disable intralink checks for <pic> elements

Other Changes

Dependencies

(#1396) Bump highlight js to v10.4.1

v2.17.0

markbind-cli

User Facing Changes

Breaking Changes

#1353 Fix nunjucks variables incorrectly overriding <variable>s provided in <include> tags (#1369) (BREAKING)

This fixes a bug where <variable>s provided in <include> tags did not override page variables set using nunjucks' tags ({% set / import %}). There should be no use case for such behaviour. However, this may cause breaking changes if your project accidentally relied on this behaviour before.

To rectify this, simply use a different variable name in the included page in order not to override it.

Features

#1227 Auto convert .md links to .html (#1362)
#1219 Add dark style for fenced and inline code (#1355)
#824 Validate intrasite links (#1382)
#561 Highlight current page link in navbar (#1379)
#1353 Add {% ext %} nunjucks extension as replacement for <variable type="json"> (#1391)

Enhancements

Add some vertical padding for the content wrapper (#1356)
#1278 Make copy-code block plugin button subtler (#1373)
Consolidate bootstrap theme config under style key (#1399)

Fixes

#1243 Fix running redundant puml processes referencing the same diagram (#1360)
#1354 Fix for undefined cname during markbind deploy (#1368)
Fix some edge cases with relative links in layouts #1371
#1266 Fix incorrect octicon name crashing live preview (#1377)
#1295 Fix markbind serve -o for index.mbd homepage files (#1378)
#970 Remove incorrect log message during asset removal in live preview (#1383)
#1353 Fix nunjucks variables incorrectly overriding <variable>s provided in <include> tags (#1369) (BREAKING)
#1394 Fix incorrect resource path for bootstrap themes (#1398)
#672 Add live preview support for nunjucks dependencies (#1361)

Documentation

Fix some broken links in user guide and dev guide (#1388)

Other Changes

Code Quality

Remove internal panel _header slot #1363
Move heading and keyword collection into Page (#1364, #1365)
Always generate dummy anchors for headings regardless of whether a fixed header is used (#1367)
Reorganize html processing files and methods (#1393)

DevOps Changes

#1130 Disable puml metadata output (#1359)
Output debug logs to console when using markbind serve -d (#1384)

Dependencies

#1264 Bump PlantUML to v1.2020.17 (#1358)
#1194 Migrate from fs-extra-promise back to fs-extra (#1351)

Miscellaneous

#1353 Add deprecation warnings for page variables and imports (#1397)