[addon-docs] Deep linking to "kind" in JSDoc comments

[kamranayub]

Is your feature request related to a problem? Please describe.

In JSDocs for components, we may want to link to another component but it seems the "selectedKind" syntax may not work nicely when specifying | characters, like so:

/**
 * See other component {@link /?selectedKind=Header|Menu | Header Menu}
 */

/**
 * See other component [Component](/?selectedKind=Header|Menu)
 */

The @link JSDoc will not translate to a link anyway, so perhaps that's out-of-scope for this request.

The syntax is also a bit awkward, it would be great to take a page out of something like TypeDoc and support a shorthand:

/**
 * See other component [[Header|Menu]]
 */

The main issue is the pipe (|) character again, as it denotes what the link text will be vs. the path.

The approach probably also needs to take into account props table documentation, not just component documentation.

Describe the solution you'd like

Somehow being able to translate the kind syntax to something compatible with @link or a shorthand notation. It should ideally link to the /docs/ path, not the raw story, since this is within the addon-docs context.

/**
 * See other component [[Header|Menu]]
 */

This would render:

See other component <a href="?path=/docs/header-menu--*">Header | Menu</a>

If it were able to perhaps detect the exported component tied to the stories, you could use the component type itself:

export default {
  title: "Header | Menu",
  component: HeaderMenu
}

/**
 * See other component [[HeaderMenu]]
 */

Storybook build would fail when component/kind doesn't match any known values, to ensure links are kept up-to-date.

Describe alternatives you've considered

You can kind of work around this in an awkward fashion by encoding the pipe using %7C and spaces with %20:

/**
 * See [Menu](/?selectedKind=Header%7CMenu)
 */

This links to the stories, not the docs and it loses any benefits of potential warnings/checks of broken component links.

Are you able to assist bring the feature to reality?

Maybe

Additional context

Using the workaround looks like this when rendered:

[shilman]

Related #8184

[mririgoyen]

This would be a very welcome addition. 👍

[shilman]

@kamranayub the only separator character is / as of 6.0 (available as opt-in in 5.3). does that solve the problem?

[kamranayub]

Thanks, I will have to test that!

…

On Sun, Mar 15, 2020, 5:05 AM Michael Shilman ***@***.***> wrote: @kamranayub <https://github.com/kamranayub> the only separator character is / as of 6.0 (available as opt-in in 5.3). does that solve the problem? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#8296 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAEJU26RPLKS7UFYAJYBR4TRHSR57ANCNFSM4I5R2UQA> .