Support multiple versions and languages of documentation

[bitbonk]

Is there guidance or documentation somewhere how I can support API and conceptual documentation for multiple versions of the same library? I am looking for a behaviour that is similar to docs.microsoft.com where you can select the the version of .NET for an API or conceptual article.

Also docs.microsoft.com has multi-language support (e.g. docs.microsoft.com/de-de/). How could I use docfx to add a similar support for multiple languages?

[R0Wi]

Would also be interested in this :+1:

[dotMorten]

I wish there was better support for this too. I at least figured out how to make an "Applies to" table with target frameworks and versions. See bottom of this page for an example: https://dotmorten.github.io/NmeaParser/api/netfx/NmeaParser.NmeaDevice.html

All of this is on github for you to see how I did it: https://github.com/dotMorten/NmeaParser/tree/main/docs Main trick is I save the .manifest files for each version and target framework (this is the list of available APIs), then run the little tool in the AppliesToGenerator to generate a list of APIs that are supported.

It basically generates a big file like this using the appliesToList.json file:

---
uid: NmeaParser.BufferedStreamDevice
appliesTo:
  - platform: .NET Standard 1.4
    versions: GitHub, v2.0, v2.1, v2.2
  - platform: .NET Framework
    versions: GitHub, v2.0, v2.1, v2.2
  - platform: .NET Core
    versions: GitHub, v2.0, v2.1, v2.2
  - platform: Xamarin.Android
    versions: GitHub, v2.0, v2.1, v2.2
  - platform: Xamarin.iOS
    versions: GitHub, v2.0, v2.1, v2.2
  - platform: UWP
    versions: GitHub, v2.0, v2.1, v2.2
---
---
uid: NmeaParser.BufferedStreamDevice.#ctor
appliesTo:
  - platform: .NET Standard 1.4
    versions: GitHub, v2.0, v2.1, v2.2
  - platform: .NET Framework
    versions: GitHub, v2.0, v2.1, v2.2
  - platform: .NET Core
    versions: GitHub, v2.0, v2.1, v2.2
  - platform: Xamarin.Android
    versions: GitHub, v2.0, v2.1, v2.2
  - platform: Xamarin.iOS
    versions: GitHub, v2.0, v2.1, v2.2
  - platform: UWP
    versions: GitHub, v2.0, v2.1, v2.2
---

That file is then used as an overwrite: https://github.com/dotMorten/NmeaParser/blob/be3b7aeafaaa08110fc7d4f6cd42fd31ea89cdf4/docs/docfx.json#L118-L123

Lastly this is added to a template override here: https://github.com/dotMorten/NmeaParser/blob/main/docs/template_overrides/partials/class.tmpl.partial#L63-L78

I haven't figured out how to create a version and target framework filter of the TOC based on all of this, but at least the above is a step in the right direction.

[guardrex]

I'm having trouble finding a clear explanation on how to do it, too. I was told by another doc author (a MSFT) to emulate the approach taken on the PowerShell repo. I might have some luck with Versioning Test DO NOT MERGE! (dotnet/AspNetCore.Docs #22776) on that basis, but our setup for ASP.NET Core docs is a bit different from the PS doc set config. It would be nice to have a full topic/explanation on the setup from a DocFX engineer.

[FOWind]

I think multilanguage support is very important too. The issue https://github.com/dotnet/docfx/issues/803 has raised six years ago.

[josesimoes]

Very interested in this feature too. Any updates please?

[niltor]

The newBing told me use metadata.language,but it didn't working and I can't find any official document about it!

It told me that config the json file like:

 "build": {
    "content": [
      {
        "files": [
          {
            "src": "*.md",
            "dest": "."
          }
        ],
        "exclude": [
          "**/bin/**",
          "**/obj/**"
        ],
        "src": ".",
        "dest": ".",
        "filter": {
          "include": [
            "*.md"
          ]
        },
        "metadata": {
          "language": [
            {
              "name": "en-us",
              "value": {
                "name": "English",
                "href": "/"
              }
            },
            {
              "name": "zh-cn",
              "value": {
                "name": "\u4e2d\u6587",
                "href": "/zh-cn/"
              }
            }
          ]
        }
      }
    ],
    ...
  },

[yufeih]

Aha, ChatGPT now becomes a good source of feature inspirations!

[niltor]

@FOWind @josesimoes @bitbonk I temporarily use a workaround for multilingual support.

Separate directory for each language

every language has it's own dir and docfx.json,like:

• zh
  • docs
  • docfx-zh.json
    • config like: "dest": "../_site/zh",
  • index.md
  • toc.ym
• en
  • docs
  • docfx-en.json
    • config like: "dest": "../_site/en",
  • index.md
  • toc.ym

Now, the _site as the root dir of the static website, it looks like::

• _site
  • en
  • zh

Add The Index.html for redirect

Then we need index.html to redirect to the default language index.

the index.html looks like:

<!DOCTYPE html>
<html>
<head>
  <!-- some metas -->
  <script>
    location.href = "/zh/"
  </script>
</head>
<body>
</body>
</html>

Change Language

Ok, when we publish the static website, it will redirect to the default language doc site. And we can use the index.md to change the language site.

just like:

## support language

- [The English documentation](/en/index.html)

Build Website

And I have a build.ps1 script:

docfx build .\zh\docfx-zh.json
docfx build .\en\docfx-en.json

Copy-Item .\src\index.html .\_site\

Complete Example

• My Docs Repository
• My Docs Website

[josesimoes]

@niltor this looks great! Thanks for sharing. @Ellerbach let's try this on nanoframework docs, shall we?

[Ellerbach]

@niltor this looks great! Thanks for sharing. @Ellerbach Laurent Ellerbach FTE let's try this on nanoframework docs, shall we?

We can, still for the best experience, missing or non existing pages in one language should be copied/automatically translated in the other folder. I've been using this pattern quite some time ago and build companions tools to help creating the missing documents. See https://github.com/Ellerbach/docfx-companion-tools And more specifically the DocLanguageTranslator which ensure you have a proper symetry and translate missing docs in the various folders.

[wlclass]

@niltor this looks great! Thanks for sharing. @Ellerbach let's try this on nanoframework docs, shall we?

I like nanoframework.