VCS API feedback

[slorber]

In Docusaurus v3.10, we introduced a new experimental VCS API to integrate Docusaurus with Version Control Systems.

Historically, Docusaurus only integrates with Git, and the implementation was previously hardcoded.

Our official Docusaurus plugins are now using this new API to implement features such as:

• Displaying the last update date/time in the docs plugin
• Displaying the blog creation date in the blog plugin
• Computing the <lastmod> value in the sitemap plugin

This new API makes it possible to integrate Docusaurus with other VCS, such as SVN, Mercurial, a CMS, or any other external system.

Here's an example implementation using hardcoded data:

export default {
  future: {
    experimental_vcs: {
      initialize: ({siteDir}) => {
        // You can initialize and cache VCS data here, if needed
      },
      getFileCreationInfo: async (filePath: string) => {
        return {timestamp: 1490997600000, author: 'Slash'};
      },
      getFileLastUpdateInfo: async (filePath: string) => {
        return {timestamp: 1490997600000, author: 'Slash'};
      },
    },
  },
};

You can also take a look at the original PR, which highlights 2 distinct ways to integrate with a VCS: #11512

For example, you could implement an "svn-ad-hoc" strategy. It's simply but might overflow your system with one CLI call per file and might not scale well:

const siteConfig = {
  future: {
    experimental_vcs: {
      initialize: ({siteDir}) => {
		// nothing to initialize	
      },
      getFileCreationInfo: async (filePath: string) => {
        return getFileCreationInfoFromSVN(filePath)
      },
      getFileLastUpdateInfo: async (filePath: string) => {
        return getFileLastUpdateInfoFromSVN(filePath);
      },
    },
  },
};

Or implement an "svn-eager" strategy, which reads the whole VCS log ahead of time and cache it for further plugin usage:

function() {
  let svnRepo = null; 
  return {
    initialize: ({siteDir}) => {
      svnRepo = readFullSvnRepo(siteDir)
    },
    getFileCreationInfo: async (filePath: string) => {
      return svnRepo.getFileCreationInfo(filePath)
    },
    getFileLastUpdateInfo: async (filePath: string) => {
      return svnRepo.getFileLastUpdateInfo(filePath);
    },
  };
}

const siteConfig = {
  future: {
    experimental_vcs: createSvnEagerStrategy()
  },
};

In our experience, the 2nd strategy (eagerly reading the whole VCS log) performs much better for large repositories.

This is also why we implemented a new git-eager strategy that we plan to enable by default in Docusaurus v4.

---

Community feedback wanted

Although the API works for our official plugins and Git, we'd like the community to share feedback on how this works for other Version Control Systems and third-party plugins:

• Did you implement a custom VCS strategy on your site?
• Did you choose the ad-hoc or eager strategy?
• Did you face any particular challenge?
• Did you implement a Docusaurus plugin that calls the VCS API?
• Did you encounter any issues in the built-in VCS strategies we provide?
• Did you use the built-in Git Eager strategy with a complex Git repository setup? (nested Git repositories, submodules...)

We'll handle the feedback we receive and adjust the API design accordingly before marking this API as stable.

Until this is officially stable, it might be better for open-source plugin authors not to leverage this new API.

Thanks 👋