Using Dev Langs

The DevLangs and Langs metadata define the content of the programming language selector and translate into BI data. Additionally the data is used to determine whether to hide or show specific code blocks.

Defining dev_langs

If you want code switching in a conceptual document, use dev_langs. You can define dev_langs on a per-page-basis by adding a dev_langs property to your page metadata:

dev_langs:
- csharp
- vb

This enables the effects discussed below for that page. Additionally, you can use your docfx.json file to configure this more broadly. Here's an excerpt from a docfx.json file that turns this on for a specific set of files:

"fileMetadata": {
  ...
  "dev_langs": {
    "get-started/**.md": ["csharp", "vb", "cpp"]
  },
  ...
}

Defining langs

If you want code switching on reference documents, use langs. Use your docfx.json file to configure this. Here's an excerpt from a docfx.json file that turns this on for a specific set of files:

"fileMetadata": {
  ...
  "langs": {
    "api/**.yml": ["csharp", "vb", "cpp"]
  },
  ...
}

Important

Be careful with the order that you define your glob patterns. You will need to set them up from more generic to more specific.

The Toggle Effect

When a devLang is selected, different UI elements are hidden and then displayed, based upon their CSS class name.

Toggle All Off

  • H1 span elements. On a Managed Reference page, the content of the H1 is directly tied to the selected devLang.
  • code elements with devLang css and is togglable. And show all parent pre elements.
  • div elements with devLang css and is togglable

Toggle Specific On

  • all elements with devLang css
  • hide all pre elements with no visible children

It may seem backwards, but pre elements are displayed first in order to give code elements a chance to be counted as visible.

code markdown and markdown extensions that are authored use the following format:

<pre>
  <code></code>
</pre>
<pre>
  <code></code>
</pre>

code rendering written via templates may use the same pre parent element.

<pre>
  <code></code>
  <code></code>
  <code></code>
</pre>

No DevLangs Defined

No devlang selector is rendered and all code samples are displayed.

One DevLang Defined

No devlang selector is rendered and all code samples are displayed.

Multiple DevLang Defined

A devLang selector is rendered and code samples are hidden if their language is an option in the selector and it is not the currently selected language.

Language selection on page load is discovered in the following order:

  1. User - Read from a cookie which is stored after they manually change the selector. Will change to default lang if user lang is not in the devLang selector.
  2. Default - Set by content authors in metadata
  3. First item - If no user or default, the first lang in the selector is selected.

Default DevLang Meta Tag

This tag allows content authors to set the default selected devLang.

"globalMetadata": {
        "defaultDevLang": "csharp"
}

Display Lang Override

The values found in this meta tag will cause DocFX to only render an intersection of devLangs and displayLangs.

Important

Currently this meta tag is only observed during Managed Reference page generation.

The example below would only render csharp code samples.

langs:
  - csharp
  - vb
"globalMetadata": {
        "_displayLangs": ["csharp"]
}

Managed Reference Properties

The following properties are dev_lang aware.

  • name(.xx)
  • nameWithType(.xx)
  • fullName(.xx)
  • modifiers(.xx)
  • syntax.content(.xx)
  • spec(.xx)