Allow to set custom path for versioned docs

[felipecrs]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Motivation

This issue is a continuation of the discussion started in #10852 (comment).

I would like to generate my own versioned_docs and versions.json out of my release branches like v1 and v2 instead of maintaining them all in the main branch.

Take my sample repository: https://github.com/felipecrs/docusaurus-sample-branched-versions

$ git clone https://github.com/felipecrs/docusaurus-sample-branched-versions
$ cd docusaurus-sample-branched-versions
$ npm install
$ npm start

npm start will also execute ./prepare_versioned_docs.sh which in turn will generate versioned_docs/ and versions.json.

Each directory inside versioned_docs/ will be a copy of the current repository at the specific release branch.

Right now, it does not work because it expects the docs directory to be the root of the versioned doc.

And even if it worked, edit URLs would not, as they are not within the same branch as the current docs.

Thus, I think the only thing I really need to make this work is being able to override the versioned docs path and their edit URLs through the versions.json. Something like:

[
  "v2": {
    "docsPath": "./versioned_docs/version-v2/docs",
    "editUrl": "https://github.com/felipecrs/docusaurus-sample-branched-versions/tree/v2/"
  },
  "v1": {
    "docsPath": "./versioned_docs/version-v1/docs",
    "editUrl": "https://github.com/felipecrs/docusaurus-sample-branched-versions/tree/v1/"
  }
]

Self-service

• I'd be willing to do some initial work on this proposal myself.

[slorber]

Each directory inside versioned_docs/ will be a copy of the current repository at the specific release branch.

This is not something you are supposed to do. The versioned_docs is supposed to only contain docs, and not full Docusaurus sites.

You should adjust your content according to our conventions.

One possibility is to use symlinks so that you don't lose the GitHub history data of worktrees:

rm -rf worktrees
mkdir worktrees
rm -rf versioned_docs
mkdir versioned_docs

for branch in "${branches[@]}"; do
  worktree_dir="worktrees/version-${branch}"
  git worktree add "${worktree_dir}" "origin/${branch}" --detach --force
  versioned_dir="worktrees/version-${branch}"
  ln -s "../worktrees/version-${branch}/docs" "versioned_docs/version-${branch}"
done

I tested and it works, but you have to link to your Yaml file with @site/yamls/example.yaml instead of using relative paths. If the Yaml changes per version, then it should probably be inside your docs folder, or you'd have to use symlinks or copy the worktree files to the correct location.

EDIT: the site builds with symlinks but then there's a rendering error (Cannot read properties of undefined (reading 'id')) because the symlinked docs live outside of a content dir and are considered as MDX partials to import. Not sure how to fix that easily 😅

Repro: https://github.com/slorber/docusaurus-sample-branched-versions

Right now, it does not work because it expects the docs directory to be the root of the versioned doc.

Yes

And even if it worked, edit URLs would not, as they are not within the same branch as the current docs.

The global docs editUrl also takes a function form letting you code your own logic:

editUrl: ({version, ...otherUsefulParams}) => {
  return "my custom edit URL"
},

Thus, I think the only thing I really need to make this work is being able to override the versioned docs path and their edit URLs through the versions.json. Something like:

[
"v2": {
"docsPath": "./versioned_docs/version-v2/docs",
"editUrl": "https://github.com/felipecrs/docusaurus-sample-branched-versions/tree/v2/"
},
"v1": {
"docsPath": "./versioned_docs/version-v1/docs",
"editUrl": "https://github.com/felipecrs/docusaurus-sample-branched-versions/tree/v1/"
}
]

The versions.json is a convention file I'd eventually like to remove in the future, in favor of passing versions through explicit plugin options, and reading them from versioned_docs directly by default. Note that nothing would prevent existing users from re-creating that file.

So the only place could be a new versions["v1"]. attribute in the plugin config options.

Or eventually a function form for the existing path option: path: ({version}) => 'docs'

---

This is not easy to design such a feature

We have to take into consideration future goals, I'd like to explore:

• removing versions.json
• moving versioned_sidebars within the docs folder so that it gets versioned automatically

Also, for consistency it would be weird to be able to configure the docs folder, and not the sidebars folder (that we probably want to remove), for those that use explicit sidebar files (unlike you but many people have explicit sidebars for versioned docs)

Also we must think about the experience of using the docs CLI to create new docs versions

Unless there's clear traction to have this feature from the community (ie, not just you), it's likely better that you find a good enough workaround and adhere to the existing conventions

[felipecrs]

EDIT: the site builds with symlinks but then there's a rendering error (Cannot read properties of undefined (reading 'id')) because the symlinked docs live outside of a content dir and are considered as MDX partials to import. Not sure how to fix that easily 😅

Maybe this has something to do with #11080. It would be nice to have full support for all sorts of symlinks. I wonder if Docusaurus could resolve the import references to their real files before delegating to webpack.

The versions.json is a convention file I'd eventually like to remove in the future, in favor of passing versions through explicit plugin options, and reading them from versioned_docs directly by default. Note that nothing would prevent existing users from re-creating that file.

I have no esteem for versions.json either. I'd much rather prefer not having to handle it. I completely agree inferring it from versioned_docs is the best, and if override is needed, plugin options is the best place.

So the only place could be a new versions["v1"]. attribute in the plugin config options.

Or eventually a function form for the existing path option: path: ({version}) => 'docs'

Yes! That would be perfect.

• moving versioned_sidebars within the docs folder so that it gets versioned automatically

This looks reasonable to me, but I don't use custom sidebars anyway, so my opinion shouldn't count much.

---

All that said: thanks a lot for spending your time on this. I would love to see better flexibility in Docusaurus in versioned docs perspective (i.e. the only thing I need is being able to specify the versioned docs path).

I am evaluating these and other options to work around this for now. I will reply back once I have news.

[felipecrs]

Ok, I have reached a major roadblock now:

Looks like only the main docs can be versioned. If I defined additional doc instances, they cannot be versioned.

See: https://github.com/felipecrs/docusaurus-sample-branched-versions/tree/not-main-docs-versioned

This is big deal for me because the repository which is versioned is not the same repository of my website. I clone it during build process to a separate directory. The docs directory of my website is not to be versioned.

[slorber]

Looks like only the main docs can be versioned. If I defined additional doc instances, they cannot be versioned.

I'm not sure to understand what you mean here

This definitively works on our website, run this command to see:

yarn workspace website docusaurus docs:version:community v2.0

See: felipecrs/docusaurus-sample-branched-versions@not-main-docs-versioned

What am I supposed to look at? I only see files.

Help me understand how I am supposed to understand what "cannot be versioned" means by looking at those files. Do you get an error message or something?

[felipecrs]

Sorry, @slorber, I just didn't it through well enough when writing the last comment.

You are absolutely correct; there is no issue with versioning for additional doc instances.

I keep forgetting I should always mimic the CLI's docs:version behavior.

My confusion was that I assumed versioned_docs would need to reside beside the docs directory, but that is not actually true. versioned_docs should always reside at the root of the website repository, regardless of the docs directory location.

• moving versioned_sidebars within the docs folder so that it gets versioned automatically

This future improvement you suggested would help avoid a confusion like this one I had.

---

I was able to fix that specific example with felipecrs/docusaurus-sample-branched-versions@ff057bb.

You also made me realize that creating the sidebar files is always needed, regardless of whether the default sidebars would work (because versioned docs apparently do not inherit default sidebars when none is set).

[felipecrs]

@slorber, good news, I was able to build a complete workaround based on your symlinks suggestion and everything we discussed:

felipecrs/docusaurus-sample-branched-versions@773536f

Highlights:

1. I symlinked yamls directory to docs/assets/yamls directly in git.
2. I added webpack resolve.symlinks: false to make the above work (not great, refs Support for symbolic linked .md files #11080, but works for now)
3. I implemented a proper editUrl function
4. Fixed my script to generate default versioned sidebars (required as realized in the comment above)

Thanks a lot! I am already updating my production website to leverage it.

[slorber]

Great!

I'll keep this issue open and see if we can ship improvements to make your life easier.

There's probably a way to get rid of the mandatory versioned sidebars thing. I don't remember exactly all the details from a few years ago, but I think it wasn't that simple and I had good reasons to keep it 😅

[slorber]

Related use-case to consider: #11345

[PhilStollery50Hertz]

Simplifying the versioning would be great for me. So if versioned_sidebars and versions.json could be removed and the versioned_docs folder moved to non-root locations would solve my use-case in a large multi-instance site that also needs versioning on many of the sub-sites.

[slorber]

Just realized that something similar has already been requested in the past,

• Output directory of versioning - {PLUGIN_INSTANCE_ID}_versioned-docs should be configurable #8061
• feat(content-docs): versionedDocsPath config for docs plugin #8076