Latest Docfx version v2.70.0 code-snippet color issue

[kavinkumarrajendran2000]

Hi Everyone,

Currently I have been facing an issue(code-snippet color issue and the language detection in code-snippet) while generating a code-snippet in API pages using latest docfx version v2.70.0.

But while using my older docfx version v2.56.1 the code-snippet color is perfect and language detection for code-snippet also works perfectly.

using older version(v2.56.1) output:

using latest version(v2.70.0) output:

Is this the issue or it was deprecated in the latest version(v2.70.0)?

How to achieve the older(v2.56.1) code-snippet color effect using my latest docfx version(v2.70.0) if it was deprecated? Could you please help me to overcome this issue.

Regards,
Kavin

[filzrev]

It seems auto-detected language by highlight.js is something wrong value selected.
What's language is selected on your environment?
It can be confirmed by code element's CSS class. (e.g. <code class="lang-xml)

If language is not selected properly.
It need to create custom template. to customize Highlight.js settings.

How to customize template
https://dotnet.github.io/docfx/docs/template.html?tabs=modern#custom-template

Example of public/main.js

export default {
    configureHljs: (hljs) => {
        // Customize [hightlight.js](https://highlightjs.readthedocs.io/en/latest/api.html#configure) options
        hljs.configure({ languages: ["xml", "csharp"] })
    }
}

[kavinkumarrajendran2000]

Hi Filzrev,

Thanks for the update.

The language has been generated as "csharp" even my code lang is XAML.

I have used the above main.js code in my default template of docfx v2.70.0, but still I got the below output with lang "csharp".

Could you please help me to overcome this issue?

Regards,
Kavin

[filzrev]

Is it able to provide reproducible sample code?
I've tested with following steps. but can't reproduce the behaviors. (Xaml content is resolved to language-csharp)

Environment

• docfx 2.70.0
• OS: Windows
• Browser: Chrome

Steps

1. Create docfx project with docfx init -q
2. Edit index.md with following contents
3. Run docfx build --serve & confirm rendered HTML.

Tested Markdown contents

# This is the **HOMEPAGE**.
## [Xaml](#tab/xaml)

```
<!-- Eliminated for simplicity -->
<chart:AreaSeries ItemsSource="{Binding Data}"
                  XBindingPath="XValue"
                  YBindingPath="YValue">
    <chart:AreaSeries.DataLabelSettings>
        <chart:CartesianDataLabelSettings />
    </chart:AreaSeries.DataLabelSettings>
</chart:AreaSeries>
```

## [.NET](#tab/csharp)

```
internal class Program
{
    internal static void Main(string[] args)
    {
    }
}
```

---

Results

1. By default xaml content is resolved to language-dust.
2. When configuring languages with public/main.js. it is resolved to language-xml.

Other

I've tested with following Code Snippet syntax also.
But results are same as above.

## [Xaml](#tab/xaml)

[!code[](Sample.xaml)]

## [.NET](#tab/csharp)

[!code[](Sample.cs)]

[kavinkumarrajendran2000]

Hi Filzrev,

Please find the xml used for generating the below output.

 <example>
             # [Xaml](#tab/tabid-1)
             <code><![CDATA[
                 <chart:SfCartesianChart>
            
                 <!-- ... Eliminated for simplicity-->
            
                      <chart:AreaSeries ItemsSource="{Binding Data}"
                                        XBindingPath="XValue"
                                        YBindingPath="YValue">
                          <chart:AreaSeries.DataLabelSettings>
                              <chart:CartesianDataLabelSettings />
                          </chart:AreaSeries.DataLabelSettings>
                      </chart:AreaSeries>
            
                 </chart:SfCartesianChart>
             ]]>
             </code>
             # [C#](#tab/tabid-2)
             <code><![CDATA[
                 SfCartesianChart chart = new SfCartesianChart();
                 ViewModel viewModel = new ViewModel();
            
                 // Eliminated for simplicity
            
                 AreaSeries series = new AreaSeries();
                 series.ItemsSource = viewModel.Data;
                 series.XBindingPath = "XValue";
                 series.YBindingPath = "YValue";
                 series.DataLabelSettings = new CartesianDataLabelSettings();
                 chart.Series.Add(series);
            
             ]]>
             </code>
             ***
             </example>

output:

How the language is being generated as lang-csharp?

[KalleOlaviNiemitalo]

Is the example element part of an XML documentation comment in a C# source file, or is it in a Markdown file?

Possibly relevant "csharp" default from #8607:

docfx/src/Docfx.Dotnet/Parsers/XmlComment.cs

Line 145 in 78b4679

code.SetAttributeValue("class", $"lang-{lang ?? "csharp"}");

[filzrev]

I can reproduce the problem by setting supplied text to doc comment.
As noted above comment. Latest docfx explicitly set lang-csharp when generating metadata from XML comment.

Currently it seems there is no way to avoid this behaviors.
I've created issue #9156 on this issue.

[filzrev]

Latest docfx (v2.70.2) include features to specify code element language. (#9156)

Try to explicitly specify following language attribute on doc comments that contains xaml code.
<code language="xaml"> or <code language="xml">

When setting language attribute as xaml.
It need to specify language alias (xaml -> xml) in public/main.js.
(Because highlight.js don't have build-in support for xaml).

export default {
  configureHljs: function (hljs) {
    // Customize [hightlight.js](https://highlightjs.readthedocs.io/en/latest/api.html#configure) options
    hljs.registerAliases('xaml', { languageName: 'xml' });
  }
}

[filzrev]

@KalleOlaviNiemitalo
Sorry it's my misunderstanding. I've removed above comments.

[kavinkumarrajendran2000]

@filzrev ,

Thanks for the update, the code-snippet color issue has been fixed in latest version v2.70.2 when using code language="xml" in the XML documentation.

Is there any way to make latest docfx to auto detect the language by customizing the template without mentioning the language="xml" in code tag?

[KalleOlaviNiemitalo]

Maybe it could be done with JavaScript; search for code snippets that have language "csharp", check whether the first non-whitespace character is a less-than sign, and flip the language to "xml".

[filzrev]

Is there any way to make latest docfx to auto detect the language by customizing the template without mentioning the language="xml" in code tag?

Currently there is no way to revert old docfx behaviors without source code modification.

If there is specific reason that require auto language detection by highlighs.js .
It needs to create feature request issue.

Another option is removing css class by following steps.

1. Run docfx metadata command
2. Remove class=lang-charp class from generated yaml files.
3. Run docfx build to build document

[kavinkumarrajendran2000]

@filzrev ,

It is working when we remove class=lang-csharp class from generated yaml files. But there are many yaml files, I can't remove manually.

So, I tried to remove using replace action in docfx.json file in two ways, but it is not working. can you suggest how to do it using docfx.json.

1)Docfx.json
"globalMetadata": {
"script": {
"type": "script",
"value": "for (var file in files) { if (file.endsWith('.yml')) { var content = files[file].content; content = content.replace(/<code class="lang-csharp">/g, ); files[file].content = content; } }"
}
}