Custom code toggle labels

[BenParizek]

The Code Toggle feature works great. We can easily show code in Twig and PHP side by side.

As many of our plugins are a lot simpler than the Craft application, it doesn't really make sense for us to create a whole different set of docs for each version of Craft. Instead, we often have a documentation page where we explain to a user how a feature works and then offer two different code examples of how it works in Craft 3 and another of how it works in Craft 2.

This creates the scenario where it would be nice to have a Code Toggle where we could show two Examples in Twig or two Examples in PHP and just let a user pick which version of Craft they are using.

http://share.barrelstrength.co/1g1t1r1D1H2g

I can kind of get this to work by adding Craft 2 and 3 to the codeLanguages array in config.js

codeLanguages: {
  twig: 'Twig',
  php: 'PHP',
  craft2: 'Craft 2',
  craft3: 'Craft 3'
},

However, I lose syntax highlighting as the class that gets added to the code block just falls back to text.

I don't know if it makes sense to request this feature to be added to the Craft Docs theme. Where do you feel the best place to explore adding support for this would be?

While I'm not proposing this as a solution, I could image an updated syntax for codeLanguages:

codeLanguages: {
  craft2php: {
    language: 'PHP'
    label: 'Craft 2'
  },
  craft3php: {
    language: 'PHP'
    label: 'Craft 3'
  }
},

Or, would it be possible for me to intercept those default values somewhere and update how they behave via config.js or enhanceApp.js? My knowledge of Vue is limited so I'm not sure where the best place might be to dig in.

[BenParizek]

Another possible implementation of this could be where the first token in the code example is processed as the language type and a second, optional text string could be added to update what the Code Toggle name displays for that particular tab.

In this example, php would be recognized as the language and the optional "Craft 3" or "Craft 2" strings would be displayed as the tab heading for each respective code example:

::: code

``` php "Craft 3"
echo "Hey, $name";
```

``` php "Craft 2"
Hey, {{ name }}
```
:::

[brandonkelly]

I'd be fine with that latter approach, perhaps without the quotes (or at least make those optional), to be consistent with how you override tip/warning labels (https://vuepress.vuejs.org/guide/markdown.html#custom-containers).

Feel free to PR it.

[BenParizek]

In a conversation in Craft Slack, Brandon pointed to a few specific files that may be necessary to adjust for this update. For anybody tackling this, I'll add a lightly edited version those notes here for reference:

[This] would be a change to the theme's markdown-it plugin.

[The solution] would need to parse out the label from the language, and then pass that on to the code-toggle component somehow.

$site.themeConfig.codeLanguages[language] is where the "default" language label is getting pulled in

[brandonkelly]

It just occurred to me that this is already possible, if you manually write out the Vue component tags yourself, rather than relying on the ::: code block syntax.

First, in your .vuepress/config.js, make sure that you are specifying the custom labels in themeConfig.codeLanguages:

codeLanguages: {
    craft2: 'Craft 2',
    craft3: 'Craft 3',
    // ...
}

Then in your docs, do this:

<code-toggle :languages="['craft2', 'craft3']">
<template slot="craft2">

```php
// Craft 2 code...

Not quite as elegant, but considering this is such an edge case (I think most people would write separate documentation sets for different versions of their plugin/library/etc.), I think that’s reasonable.

[brandonkelly]

@BenParizek This is fully implemented now, similar to your second suggestion, but without the quotes. There’s an example of it in the readme.

https://github.com/pixelandtonic/vuepress-theme-craftdocs/blob/a38d46f85242add96ee59b4e17a5c35a906e2213/README.md#L59-L69