Is it possible to have the same document render different content based on the url link?

[rrousselGit]

Hello!

My documentation uses a pattern similar to that of VueJS's website, where the docs have toggles to enable/disable certain features.
This slightly changes the content of the articles (such as changing code snippets).

The challenge I'm currently facing is that I want it to:

• not require duplicating the content. I don't want to maintain two .mdx files with slightly different contents
• be SEO/search-bar friendly. At the moment, I've implemented it client-side in a React component. But that implies all of that content doesn't get picked by Google or Agolia. So I'm trying to fix this

For reference, at the moment I write my docs as follows:

---
title: Hello world
---
import {When} from './when'

This is some shared _markdown_

<When myToggle={true}>
This text is visible only when "myToggle" is enabled
</When>

<When myToggle={false}>
If myToggle is disabled, we instead see this text
</When>

This approach works great for me in terms of maintainability. But it breaks the sidebar/SEO and content table (if a heading is only conditionally enabled, it always shows up in the content table even if disabled).
I could have two markdown files. But then I would have to duplicate the frontmatter & the This is some shared _markdown_ text (which usually is the largest part of documents)

Are you aware of a possible solution that wouldn't involve duplication while also fixing those SEO/searchbar/content table issues?

[slorber]

I'm not an SEO expert but what I understand is that Google is able to index content in tabs and accordions when it's "done properly" (not sure yet what this means).

I can't tell if it would work with a less-standard setup of toggles, and even wonder how the VueJS site implements this and if it even works as you would want it to?

How did they implement that exactly, and does it work well in practice?

---
title: Hello world
---
import {When} from './when'

This is some shared _markdown_

<When myToggle={true}>
This text is visible only when "myToggle" is enabled
</When>

<When myToggle={false}>
If myToggle is disabled, we instead see this text
</When>

This is not clear to me how that boolean condition is actually updated. I assume in practice it's dynamic and the way it's toggled probably matters a lot for SEO.

---

Regarding the TOC, considering our HTML pages are static and support progressive enhancement, the TOC should also be static and work well before JS loads/runs, so we can't have a "dynamic TOC" easily without introducing hydration layout shifts. Related to #8764

---

I'm not sure if it's what you want but I think it could be better if one doc would be able to be rendered into 2 distinct pages (with different URL pathnames like /docs/doc1/variant-a and /docs/doc1/variant-b) instead of trying to make it work into a single static page.

Related issues:

• Allow a single docs folder to be consumed by 2 docs plugin instances (use-case: normal vs embed/iframe docs) #7480
• Docs version aliases #9049

You might also find useful to remove/hide sections thanks to a remark plugin: #6201 (comment)

[slorber]

We don't have support for that ATM but we should build it later once Docusaurus v3 is out (now in alpha).

If you want to dynamically link to it from the sidebar, this probably requires support in the docs sidebar too.
I'm not sure how to properly implement that yet, but we could enable you to register custom sidebar item types and implement the extra logic yourself. We already offer this workaround for custom navbar items: #7231

[rrousselGit]

No problem. Is there any possible workaround? I don't mind having to maybe make a custom plugin or fork Docusaurus if necessary

[slorber]

If you can add 2 docs plugins instances that support the same docs, that could be possible to build 2 variant pages for each doc.

#7480 reports that it doesn't work unfortunately, and I didn't have time to investigate. If you understand where the problem comes from and send a PR, I appreciate your help troubleshooting this and it might solve your problem.

Once your doc is successfully rendered by 2 distinct plugins on 2 different pages, it should be easy to have conditional logic based on current path (useLocation()), current plugin id (useRouteContext().plugin.id) or by implementing different Remark plugins for each docs plugin instance.

[rrousselGit]

Nice! I'll give it a try. Although I have never made a Docusaurus plugin before. Any recommendations on what would be involved for this?

[slorber]

I didn't say you should create a brand new Docusaurus plugin, but to use 2 instances of the existing docs plugin, so that you can render twice each docs of your ./docs folder:

https://docusaurus.io/docs/docs-multi-instance

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'variant-1', 
        path: 'docs',
        routeBasePath: '/docs/variant-1/',
        sidebarPath: require.resolve('./sidebars.js'),
      },
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'variant-2', 
        path: 'docs',
        routeBasePath: '/docs/variant-2/',
        sidebarPath: require.resolve('./sidebars.js'),
      },
    ],
  ],
};

Unfortunately according to #7480 this setup doesn't work while it should: it is a bug in Docusaurus to fix! 😅

---

Otherwise, if you want to create:

• A docusaurus plugin: https://docusaurus.io/docs/api/plugin-methods
• A remark plugin: https://docusaurus.io/docs/markdown-features/plugins#creating-new-rehyperemark-plugins

Creating a remark plugin can be helpful so that the same doc Markdown is interpreted differently depending on the plugin instance. This is one way you could maybe achieve what you want, but require investing time to understand how all this Remark/unified/MDX ecosystem works and there's a bit of a learning curve.