Docusaurus: [Enhancement] Improved code blocks

[hramos]

In this issue I want to collect some ideas for improving our fenced code block widget. 1.0 will launch without this.

• [ ] Language toggling
  A good example of this can be found in the Parse docs.
• [ ] Sub-language toggles
  (e.g. ES6, ES5)
• [ ] Line highlighting
  Support ```javascript{3,5-7} syntax for highlighting (#105 @rickyvetter)

(There may be other ideas for features to implement in this issue https://github.com/facebook/react/issues/10991)

[Glavin001]

What would be a good syntax for code blocks with language toggling?

I am very interesting in trying to make a Pull Request for this. Before I get started, I'd appreciate some collaboration on the design :).

[ForbesLindesay]

I like the idea of just having multiple code blocks, one after another, with no text between them:

[stevenzeck]

A toggle would be very helpful. The one in the parse docs is great if you have a small list of languages, but if you have more than 5 it's hard to make it work. Perhaps use that if the number of languages is 3 or fewer and a select list otherwise?

[jonathaningram]

I actually hacked together a plugin called "file tabs" to do this. I just wanted to use docusaurus to quickly prototype something, so the plugin was meant to be quick and dirty. Source is here: https://github.com/govau/platforms-alpha/blob/master/lib/shared/fileTabs.js

Install into your site like this: https://github.com/govau/platforms-alpha/blob/master/tell/website/siteConfig.js#L52

And here's how you use it in your .md file:

````md

file=website/blog/2018-06-13-docusaurus-file-tabs-plugin/example.cs lang=csharp label=C#
file=website/blog/2018-06-13-docusaurus-file-tabs-plugin/example.go lang=go label=Go
file=website/blog/2018-06-13-docusaurus-file-tabs-plugin/example.inline parser=md label=Java
file=website/blog/2018-06-13-docusaurus-file-tabs-plugin/example.js lang=js label=Node.js
file=website/blog/2018-06-13-docusaurus-file-tabs-plugin/example.php lang=php label=PHP
file=website/blog/2018-06-13-docusaurus-file-tabs-plugin/example.py lang=python label=Python
file=website/blog/2018-06-13-docusaurus-file-tabs-plugin/example.rb lang=ruby label=Ruby

````

And how it ends up looking:

Edit:

One problem as it stands is that this doesn't account for versioning:

1. docs/** are not copied when versioning. Hoping that https://github.com/facebook/Docusaurus/pull/705 resolves this
2. the versioned_docs/**/*.md files are going to have filetabs fences that refer to the latest/master set of files. Need to figure out how this would be handled. Ideally filetabs would work by having files be relative to the current file, but from memory when I tried doing that originally it didn't work and I needed to make the file relative to the project root.

[yangshun]

@jonathaningram This looks amazing! I also like that the code is stored outside of the Markdown file. We'll look into including it! 😄

[jonathaningram]

@yangshun thanks! Yeah we'd probably publish as an npm package and then it could just be imported like any other old package, but for my case I didn't want to bother publishing a new package so I just needed to hack together a way to import it from multiple docusaurus instances.

And of course the tabs HTML and CSS would need to be cleaned up, verify accessibility, and so on.

Finally, I think the fence syntax is pretty neat, but would be good to validate that it's scalable too.

Oh, it actually lets you embed another MD file like this:

[fiennyangeln]

Hi I'm interested in this issue. Is it an appropriate bug to work on?

[JoelMarcey]

@fiennyangeln - I think this is quite appropriate. Language Toggling would be great and a feature that people really have asked for. And anything else you feel could improve the code blocks too.

I will mark this issue as claimed by you 😄