Docusaurus: Doc for @theme-original and @theme-init

[slorber]

📚 Documentation

I think this D2 feature is currently not documented.

If we want to override an existing comp, yet reuse the original comp (like, if you want to wrap it), there's a special import alias we can use.

It's worth trying if the following work and document this feature

import OriginalDocItem from "@theme-original/DocItem";

export default function CustomDocItem(props) {
  return (
    <>
      <div>
         before doc
      </div>
      <OriginalDocItem {...props} />
      <div>
         after doc
      </div>
    </>
  );
}

That could be nice to find a tiny usecase for this feature on D2 website, for dogfooding and ensuring this behavior does not break over time.

[FocalChord]

@slorber Could we have more detail about this one, I'm still confused as to what is required

[slorber]

Sorry I probably didn't explain this well :)

if you swizzle a comp, like the Footer, to customize it, sometimes you want to be able to import the original comp of the theme to wrap it.

The following does not work:

 // this does not import original code, it creates some kind of infinite loop, as the file imports itself
import OriginalDocItem from "@theme/DocItem";

export default function CustomDocItem(props) {
  return (
    <>
      <div>
         before doc
      </div>
      <OriginalDocItem {...props} />
      <div>
         after doc
      </div>
    </>
  );
}

So I think we have a special import:

import OriginalDocItem from "@theme-original/DocItem";

instead of

import OriginalDocItem from "@theme/DocItem";

Unfortunately I don't think we have more details about that feature, it's something I know about because I inspected the code.

Actually, looking back, the only place where this is used is in the live-codeblock plugin

import CodeBlock from '@theme-init/CodeBlock';

And it's not even @theme-original, but @theme-init.

Seems like at some point we renamed one to the other or something, and tried to keep retrocompatibility.

@yangshun do you know more about the history of this feature? what about keeping only one alias instead of having 2? That seems like an acceptable breaking change.

[yangshun]

@theme-original was added by me for the purposes you mentioned. @theme-init was added by @lex111 for reducing code duplication for the code blocks. They serve different purposes.

[slorber]

Still not sure to understand the difference @yangshun 😅 why can't @theme-original be used for the CodeBlock comp?

[yangshun]

Alexey explained here - https://github.com/facebook/docusaurus/pull/2464#issuecomment-603802459. We definitely need better naming and better docs for this.

[Jonathannsegal]

This does seem like an straightforward clarification to add to the docs. Started a PR with proposed changed based on Alexey's explanation. Let me know if this is something that is close to what is wanted or if this needs to be changed.

[slorber]

Unfortunately the docs have been added to v1 instead of v2.

Will port these docs to v2, and also make it more idiomatic to know that ./docs is v1 as it's confusing.