Docusaurus: Allow linking to hrefs for Sidebars

[ericnakagawa]

Pain point

For developers that generate API documentation from their code, it would be useful for Docusaurus to allow linking to these pages from a sidebar.

How it currently works

Normally we only allow links to hrefs via the top level navigation. This feature would allow for more flexibility on single navigation pages.

How it would work

Use a similar for processing-method for sidebar.json as the one we use to handle external links in siteConfig.js headerLinks. This would add a new branch of code when processing sidebar.js and encountering an href and no associated id field. If an id field is present, then it should take precedence.

Scope of impact: Low to Mid

Any project that uses documentation generation from code could benefit from this feature.

[JoelMarcey]

Claimed by @SleepWalker

[yangshun]

Removing the "issue: claimed" label due to inactivity.

With the changing of sidebar format in #1026, we now can easily add external links type into the sidebar. This issue should be now a little simpler.

[syn228]

Could I try taking on the issue? I'm looking for an opportunity to contribute to an open source project for the first time!

[SleepWalker]

Hello @syn228, I was busy a few weeks, but I want to finish with the issue, I've claimed.. I'm planning to return to this issue today or tomorrow.

[endiliey]

892 and #1026 should be super related to this

Sidebar item - subcategory

{
  type: 'subcategory',
  label: 'My Subcategory',
  ids: []
}

Sidebar item - url/href

{
  type: 'url'
  label: 'GitHub',
  href: 'github.com'
}

Sidebar item - doc id (default)

Eventually we have

'Second Category': [ 
  'doc3',
  {
    type: 'url',
    label: 'Github',
    href: 'github.com'
  },
  {
    'type': 'subcategory', 
   'label': 'my subcategory',
    'ids': ['doc4'],
  }, 
'doc5', 
],

[SleepWalker]

@endiliey, I've come up with the following format:

{
  "docs": {
    "Category 1": [
      {
        "type": "link",
        "label": "Github",
        "href": "http://github.com"
      },
      {
        "type": "ref",
        "id": "intro"
      },
      {
        "type": "category",
        "label": "Subcategory 1",
        "items": [
          "foo/bar",
          "foo/baz"
        ]
      },
      {
        "type": "category",
        "label": "Subcategory 2",
        "items": [
          "hello"
        ]
      }
    ],
    "Category 2": ["code"]
  },
  "test": {
    "test": [
      {
        "type": "doc",
        "id": "intro"
      },
      {
        "type": "ref",
        "id": "code"
      }
    ]
  }
}

• doc — low level name for simple link to doc
• ref — link to some docId, but without binding this doc to current sidebar
• link — the type used to render any link in sidebar (doc and ref are converted to this type too). Should contain href and label fields
• category — category :) should contain label and items fields (I think this should be a better name, because we will handle not only ids in this array)

[SleepWalker]

@yangshun should this feature implemented for v1 too? I've read, that you're not accepting new features for v1

[yangshun]

@SleepWalker If it's easy to support this for v1, I think we should do it. Seems like it should be doable on v1 too.

I added the issue: claimed label back.

[yangshun]

@syn228 Sorry about this, could you try looking for other issues to work on? Facebook has other open source projects as well which would be glad to receive your contributions.

[plaa]

Any idea when this would be coming?

I'd prefer also the possibility to link to custom pages (though of course I can do that with href as well). We are generating our API documentation using ReDoc, which would be well suited to be a custom page.

[BrendanThompson]

Would like to be able to reference Pages in the SideBar too. Feel like this might be a good place for this.

[sriramgroot]

Hi Folks,
Whether this feature/issue can we addressed in version 1 of docusaurus. This could be helpful if this issue is fixed in version 1 itself

[JoelMarcey]

@yangshun @slorber -- is this something we should still try to fix for v1? Sounds like it may not be the most trivial fix for v1, but maybe I don't have enough context?

[yangshun]

Probably not too hard to fix in v1.

[slorber]

Hi, will take a look.

For v1, should it be fixed on master or there's another branch?

[JoelMarcey]

@slorber master is 👍 - we would cut another release with the fix if it goes through.

[JoelMarcey]

@sriramgroot The solution to this problem may not be trivial. Could you move to v2? Or is something stopping you from that?