Markbind: Use a simpler syntax for glyphicons/fontawesome

[damithc]

Current syntax: {{ fas_home }}
Suggested: :fas-home:

Inspired by https://www.npmjs.com/package/markdown-it-fontawesome
Not sure if it is possible though.

[damithc]

@Chng-Zhi-Xuan what do you think? Not urgent though.

[Chng-Zhi-Xuan]

• If we are using the library as given in npm
  
  Then it creates a syntax divide between Glyphicons and Font-Awesome icons.

• If we are implementing it ourselves (using some other library for custom syntax variables or via regex)
  
  It might not be a good time investment to implement this just for a minor syntax change.

But I think the biggest issue is, the :name: syntax is synonymous with emojis within Markdown already. So I do not think it is worthwhile.

[damithc]

As we are using markdown-it ourselves, we can extend the plugin to cover both fontawsome and glyphicons and then plug it into our parsing chain? Based on this, it doesn't seem to be a complicated plugin.

But I think the biggest issue is, the :name: syntax is synonymous with emojis within Markdown already. So I do not think it is worthwhile.

We can use patterns :fas-*: and :glyphicon-*: to distinguish?

[Chng-Zhi-Xuan]

We can use patterns :fas-*: and :glyphicon-*: to distinguish?

Looking at the Markdown emojis, none of the names use -, but rather _ inbetween words. So the regex shouldn't have a conflict if we were to use :fas-*: and :glyphicon-*:.

Then I would say its ok to implement it 👍

[Xenonym]

Are we keeping the current {{ fas_name }} synatax _alongside_ this new :fas-name: syntax? It would be cleaner if we removed the {{ }} syntax, but existing sites might break.

[damithc]

Are we keeping the current {{ fas_name }} synatax _alongside_ this new :fas-name: syntax? It would be cleaner if we removed the {{ }} syntax, but existing sites might break.

Yes, cleaner to remove. ATM, all existing sites are under our control; that's why we need to do this sooner rather than later, if we are going to do it at all.

[acjh]

Can deprecate in the next minor version and remove in the following minor version.

My response from https://github.com/MarkBind/markbind/pull/240#issuecomment-394239860:

if it is a breaking change, should that make the version become 2.0.0? According to the semantic versioning scheme, since our new setup.js in this PR breaks existing websites if the authors do not make any changes to their HTML code on their navbar, it qualifies as not having a backwards-compatible feature.

A minor version will do. 1.x is still not production-ready for now.
We can follow those guidelines when we are ready for 2.0.

We should probably put that bolded part in the README.md.

[Xenonym]

How do we normally handle the use of deprecated behaviour? Do we show a warning, or do we just write it in the user guide?

[yamgent]

Do we show a warning, or do we just write it in the user guide?

I don't mind doing both of them, although a warning would require you to know that the deprecated icon syntax is being used in the source.

[acjh]

Previously, we showed a warning in https://github.com/MarkBind/markbind/commit/ab050a15bd56afb7c23b1e558c8af3a46adf4f85.

However, nunjucks variables are more complicated as there is no hook for when a variable is used iirc.

[Xenonym]

Previously, we showed a warning in ab050a1.

However, nunjucks variables are more complicated as there is no hook for when a variable is used iirc.

Yes, issue is that we render Nunjucks variables in several locations (when rendering the page, header, footer, sitenav and variables). While it would be possible to check manually in each of these locations, this seems like a lot of modification to surface a warning that would only be visible for one minor revision which we would have to undo afterwards. In this case, I think just documenting the deprecation would be more efficient.