Skip to content

v3.0.0
Compare
Choose a tag to compare
@ang-zeyu ang-zeyu released this 06 Jun 05:45
· 532 commits to master since this release
v3.0.0
b106ce2

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
Assets 2
Loading