Current Information Architecture Incompatible with Versioned Docusaurus Website

The UNTP specification website, powered by the JavaScript documentation framework Docusaurus, has recently undergone a significant update in which versioning was enabled within the website itself.

This change complements the existing version control provided by Git/GitLab. Docusaurus’s built-in versioning allows users to select and view specific release versions directly through the website interface.

When a new version is released in Docusaurus, it creates a physical snapshot of the contents within the documentation site (files within the /docs directory), placing it in a dedicated version directory (e.g., /versioned_docs/version-0.6.0/...). The latest changes, not yet officially released, reside in the /docs directory and are exposed as a work-in-progress (wip) version. This enhancement provides implementers direct, self-service access to documentation specific to the version they are using.

However, not all content currently hosted on the website is suitable for versioning. For example, extensions, implementations, and working group pages.

The Problem

Given the content on the website, we now require two subsets of documentation: one versioned and one unversioned, to coexist within a unified website structure. Given our current information architecture, it is critical that the primary method of navigation (the sidebar) harmoniously reflects both sets of documentation (versioned and unversioned).

Here we encounter a technical limitation within the Docusaurus framework. Docusaurus requires that versioned and unversioned content be entirely separated. In practice, this means versioned documentation (such as the business case, specification, and implementation guidance contents) must reside under a separate directory of our choosing, e.g. /docs/versioned. In contrast, unversioned documentation (such as extensions, implementations, and working group pages) must reside under a separate directory of our choosing, e.g. /docs/unversioned.

At first glance, this separation might seem manageable, but configuring the website to handle versioned and unversioned documentation independently essentially creates two entirely separate websites within a single site. For example, the sidebar navigation is contextually bound to the documentation currently viewed (in our case, versioned or unversioned). If a user is viewing the versioned content, the sidebar only displays links within the context of the versioned documents, and similarly for unversioned content.

Currently, all our content is versioned. While temporarily manageable with just one active version, this setup is not scalable. Every time we update documents meant to remain unversioned, such as extensions, implementations, and working group pages, we must manually update these files within the core documentation and each subsequent version directory. This approach is unsustainable and highly prone to human error, potentially leading to inconsistencies.

Attempted Workarounds

I've explored potential workarounds to maintain our existing information architecture. This included manually crafting sidebar structures. However, this resulted in further issues, such as sidebars disappearing when navigating between versioned and unversioned pages.

Docusaurus acknowledges this constraint within its documentation, recommending that users maintain separate websites for versioned and unversioned documentation. The official Docusaurus website implements this by placing versioned documentation under /docs and unversioned documentation under /community. However, as noted previously, sidebars remain contextually bound to the documentation currently viewed.

Next Steps

We must determine a sustainable and scalable approach to managing versioned and unversioned documentation within our chosen framework (Docusaurus). Without an appropriate solution, we risk ongoing maintenance issues and data inconsistencies.