feat(v2): add @theme-original alias to give access to pre-swizzled components

[yangshun]

Motivation

Provide an alias for theme components so that they can be semi-swizzled. Meaning you swizzle a component but only to wrap things around it, possibly to call new lifecycle logic or have components above/below it.

For example, I can now do this

import React from 'react';

import DocItemOriginal from '@theme-original/DocItem';

function DocItem(props) {
  return (
    <div>
      <p>Wrapper</p>
      <DocItemOriginal {...props} />
      <p>Wrapper</p>
    </div>
  );
}

export default DocItem;

and get this

This is partially inspired by VuePress (although Endi and I already had this idea long ago when we were building themes). Libra docs is moving to v2 and wants this level of customization.

This @theme-original alias will also allow us to specify slot props (components as props) which serve to inject components somewhere into a component. We could do this for the various doc and blog items.

Follow Up

• Add docs
• Add slot props to doc and blog

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

Modified unit tests and added example.

Related PRs

(If this PR adds or changes functionality, please take some time to update the docs at https://github.com/facebook/docusaurus, and link to your PR here.)

[yangshun]

I rewrote this part to make it slightly easier to read (IMO).

[docusaurus-bot]

Deploy preview for docusaurus-2 ready!

Built with commit c92e715

https://deploy-preview-2455--docusaurus-2.netlify.com