Markbind: Best-in-class support for code blocks

[damithc]

With the addition of partial code highlighting feature, most likely MarkBind is the static website generator that has the _best support for fenced code blocks_. We can compare with other similar tools to see if are inferior in any way, and can improve those too.

What do you think of the possibility of more advanced features such as tooltips (inside code blocks)? not feasible at all?

[raysonkoh]

We can compare with other similar tools to see if are inferior in any way, and can improve those too.

We can also explore the possibility of having something similar to Vuepress's code-group feature: https://vuepress.vuejs.org/theme/default-theme-config.html#code-groups-and-code-blocks , which is showing code in different languages that accomplishes the same result. This might be useful for students who are perhaps more comfortable in another language (eg python) and can use that as reference to learn the main language that is being taught (eg c++) better?

[jonahtanjz]

We can compare with other similar tools to see if are inferior in any way, and can improve those too.

I believe we can also explore having the ability or an easy way for the users to import code from an external file. Since MarkBind already has the <include> feature, we can extend this to code blocks as well. Maybe something along the lines of
````

<include src="example.js" />

``` We can also take this further by having auto syntax highlighting based on the extension of the external file. I have not really seen this feature anywhere else on other static site generators but I think this would be useful and convenient, especially for pages with large amount of example codes. This way, MarkBind users can also keep their.mdor.mbd` files less cluttered when developing the pages.

[ang-zeyu]

What do you think of the possibility of more advanced features such as tooltips (inside code blocks)? not feasible at all?

👀

We can also explore the possibility of having something similar to Vuepress's code-group feature: https://vuepress.vuejs.org/theme/default-theme-config.html#code-groups-and-code-blocks , which is showing code in different languages that accomplishes the same result. This might be useful for students who are perhaps more comfortable in another language (eg python) and can use that as reference to learn the main language that is being taught (eg c++) better?

Hmm this sounds similar to tabs. Might be missing something there though.

I believe we can also explore having the ability or an easy way for the users to import code from an external file. Since MarkBind already has the feature, we can extend this to code blocks as well. Maybe something along the lines of

This can be done using nunjucks'
````

{% include ... %}

````

auto syntax highlighting sounds good, it might be in the form of just <include src="...js" /> without the backticks then. But I think we'd need a few more suggestions surrounding this form of including external code files to make it worthwhile.

[ryoarmanda]

A minor idea that I have is to make line highlighting more expressive with diff-style background coloring (e.g. green for addition, red for deletion, the color that we have right now for "neutral" highlight to indicate something to take note of). Users can define themselves which parts are to be colored which.

I think this is helpful in the scope of educational websites, particularly step-by-step code tutorials with each step builds on from the work of the previous one. With this, authors can have better signposting on which lines are newly introduced during a step. Signposting on deletions are something that can be discussed on (not sure if there are many users who want to do that).

Even though highlight.js supports the diff language, specifying that would not actually syntax highlight the code, more like just coloring the added/removed lines with green/red (see it in action here, just find the Diff demo). Language-aware diff is a problem that even GitHub is facing (though they somewhat are able to do it on diffs in PRs), but as our highlights are user-defined and our line-highlight system is separate from syntax-highlight, we can leverage those to be able to emulate diff while keeping the syntax highlight.

[damithc]

Even though highlight.js supports the diff language, specifying that would not actually syntax highlight the code, more like just coloring the added/removed lines with green/red (see it in action here, just find the Diff demo). Language-aware diff is a problem that even GitHub is facing (though they somewhat are able to do it on diffs in PRs), but as our highlights are user-defined and our line-highlight system is separate from syntax-highlight, we can leverage those to be able to emulate diff while keeping the syntax highlight.

Yes, might be worth exploring 👍

[ang-zeyu]

https://rust-lang.github.io/mdBook/format/mdbook.html

The show hidden lines function seems really useful as well, and should be very compatible with our line slice syntax.

[damithc]

https://rust-lang.github.io/mdBook/format/mdbook.html

The show hidden lines function seems really useful as well, and should be very compatible with our line slice syntax.

In fact, the features mentioned in there seem to assume the code examples are coming from separate source files. We haven't paid much attention to that use case so far. Worth exploring.