Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Add missing Markdown links for [ShorthandLinkStyle][] #199

Conversation

happycollision
Copy link
Contributor

There are links missing in the current documentation that are formatted
like [HTMLElement][].

I originally tried to add them by just appending
the corresponding markdown to the documentation.yml file.
Unfortunately, when built, the link keys were all .toLowerCase()ed.
So I have added a very simple node script to append all necessary
links to the API.md file.

This script has been added to the yarn docs command, so
introduces no new dependencies.

There are links missing in the current documentation that are formatted
like `[HTMLElement][]`.

I originally tried to add them by just appending
the corresponding markdown to the `documentation.yml` file.
Unfortunately, when built, the link keys were all `.toLowerCase()`ed.
So I have added a very simple node script to append all necessary
links to the `API.md` file.

This script has been added to the `yarn docs` command, so
introduces no new dependencies.
@Turbo87
Copy link
Collaborator

Turbo87 commented Nov 19, 2018

This seems like a hot fix that's just hiding the actual bug. Is this a reported bug with documentation.js? If not, have we configured something wrong which makes this not work automatically?

@happycollision
Copy link
Contributor Author

I couldn't find any bad configs anywhere, but did not delve into the workings of documentation.js. As such, I am guessing this is the current behavior (whether expected or not) from documentation.js. So yes, this is a fix for undesired behavior of other tooling.

I assumed (perhaps wrongly) that if documentation.js is behaving in a way that breaks your documentation, that you'd rather have correctly linked docs while that issue is unresolved. I can totally understand if the threshold of this issue is low enough that you don't actually want to address it.

In any case, I do not personally have the time to also go looking into documentation.js right now.

The other way of getting correct link behavior in your documentation without a hot fix would be to (rather verbosely) replace every instance of implicit style links with the longer regular markdown syntax in all the jsdoc blocks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants