feat(v2): siteMetadata

[slorber]

🚀 Feature

Currently, as far as I know, a site can't know which docusaurus version it is currently using

It would be useful to be able to get some metadata about the framework.

Algolia/DocSearch devs have expressed the need to be able to track which version of Docusaurus uses which version of DocSearch.

I think this does not belong to the site config: it is a new docusaurus context item that we should create.

const {siteMetadata} = useDocusaurusContext();

For now we could keep it simple and just add the version, as it's been asked by Algolia.

{
  docusaurusVersion: "2.0.0-alpha.58"
}

This could be enhanced later, and include all plugins versions, the site version, and other useful things that we'd find useful.

We could also add these data to docusaurus-plugin-debug , @SamChou19815 do you think of additional data that could be useful to display?

[SamChou19815]

We could also add these data to docusaurus-plugin-debug , @SamChou19815 do you think of additional data that could be useful to display?

I think it can be useful. The version information can also be included in all official plugins, and the debug plugin can help detect out-of-sync versions (e.g. core at alpha-58, theme-classic at alpha-56)

[slorber]

Yes that's what I think too

The version information can also be included in all official plugins

For official plugins or not, I think we could do this in a generic way, to add plugin versions to this siteMetadata file:

• if plugin is in node modules, read the version from its package.json
• if plugin is a local js file, maybe fallback to the package.json version of the site (or null if no version specified)

The file could look like

{
  "docusaurusVersion": "2.0.0-alpha.58",
  "siteVersion": "1.0.0",
  "pluginVersions": {
    "docusaurus-plugin-pwa": "2.0.0-alpha.58",
    "custom-site-plugin": "1.0.0"
  }
}

I think we should use plugin name like docusaurus-plugin-pwa, and not plugin package name @docusaurus/plugin-pwa because local plugins don't necessarily have a package name, yet we could enforce them to have a name attribute.

Does someone want to work on this?

[SamChou19815]

if plugin is in node modules, read the version from its package.json

Detecting existence of node_modules in plugin's resolved path might not be a good idea, since it might give surprising result for monorepo setup. For example, this is the resolved path for all plugins in docusaurus repo:

/Users/sam/Desktop/workplace/docusaurus/packages/docusaurus-plugin-content-docs/lib/index.js
/Users/sam/Desktop/workplace/docusaurus/packages/docusaurus-plugin-content-blog/lib/index.js
/Users/sam/Desktop/workplace/docusaurus/packages/docusaurus-plugin-content-pages/lib/index.js
/Users/sam/Desktop/workplace/docusaurus/packages/docusaurus-plugin-debug/lib/index.js
/Users/sam/Desktop/workplace/docusaurus/packages/docusaurus-theme-classic/src/index.js
/Users/sam/Desktop/workplace/docusaurus/packages/docusaurus-theme-search-algolia/src/index.js
/Users/sam/Desktop/workplace/docusaurus/packages/docusaurus-plugin-client-redirects/lib/index.js
/Users/sam/Desktop/workplace/docusaurus/packages/docusaurus-plugin-ideal-image/lib/index.js
/Users/sam/Desktop/workplace/docusaurus/packages/docusaurus-theme-live-codeblock/src/index.js

There are no node_modules in the path, but they clearly belong to some package.

Therefore, I think all we can reliably do is to recursively walk up along the plugin resolved path until we hit a directory that contains package.json, and try to resolve version info from there.

Then there comes to the question of local plugins. I think it will almost always be the case that they share the same package.json with the root project. If we detect this is the case, we probably should just say it's local without giving a confusing version.

I will probably try to work on it tomorrow.