[v2] Support javascript src files (among others) in multi-version mode

🚀 Feature

Hey there! We’re in the process of setting up Docusaurus v2 at Rasa and we’ve hit a roadblock. The basic use case is the following:

1. we want to build variables (from the code, code is in python) and include them in the doc
2. we want to require source files from the doc

Everything works fine until multi-version kicks in. For 1., we initially built variables into a JS file under the src/ folder, but realised that the src/ folder was shared across versions of the docs. The same applies to 2. (nothing seems to be copied inside the different versions).

Here is how we implemented it:

• add a pre-build step (before calling docusaurus build or docusaurus start)
• this pre-build step generates files under the docs/sources/ folder; this allows to support multiple versions (everything under docs/ seems to be copied to versions)

This use case doesn’t seem too exotic, wondering if this is something you planned to support and/or if there is an undocumented way of doing that.

Have you read the Contributing Guidelines on issues?

yes

Motivation

We’re moving from Sphinx to Docusaurus (v2).

Pitch

⬆️ See above 🙃

[slorber]

Yes that seems appropriate even if I don’t understand everything ^^ anything in /docs will be versioned, everything outside will not

[m-vdb]

we use MDX so anything supported by MDX is kind of official

Thanks for pointing that out @slorber. If you feel that we’re using Docusaurus v2 as intended, then we’re good 👍

For reference, here is an example of our folder structure:

docs/docs/
├── index.mdx
├── sources
│   ├── data
│   ├── examples
│   ├── rasa
│   ├── rasa_data_convert_nlu___help.txt
│   ├── rasa_data_split_nlu___help.txt
│   ├── rasa_data_validate___help.txt
│   ├── rasa_export___help.txt
│   ├── rasa_interactive___help.txt
│   ├── rasa_run___help.txt
│   ├── rasa_run_actions___help.txt
│   ├── rasa_shell___help.txt
│   ├── rasa_test___help.txt
│   ├── rasa_test_core___help.txt
│   ├── rasa_test_nlu___help.txt
│   ├── rasa_train___help.txt
│   ├── rasa_visualize___help.txt
│   ├── rasa_x___help.txt
│   └── tests
...
└── variables.json

Everything under sources/ + the variables.json is generated outside of the docusaurus build system and gitignored. We have custom plugins to include them in the docs. When we cut a new version, we assume that everything under docs/ is moved to a new version folder (and it seems to work).

The variables.json looks like this:

{
    "release": "2.0.0a1",
    "rasa_sdk_version": "2.0.0a1"
}

and is version-dependant.