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

Linkable Code References #123

Closed
KevinAst opened this Issue Apr 11, 2017 · 2 comments

Comments

Projects
None yet
2 participants
@KevinAst

KevinAst commented Apr 11, 2017

I am using jsdoc-to-markdown (ver: 3.0.0) to document the API in my project: https://astx-redux-util.js.org/1.0.0/.

Initially, my code references (function return types, and parameter types) were NOT linkable. These references were coded as follows (out-of-the-box):

**Returns**: <code>[reducerFn](#reducerFn)</code> - snip snip

My understanding of why this is not linkable, is that markdown does not honor a hyperlink inside a code block (i.e. the <code> element).

I created a custom partial of link.hbs), that removed the outer <code> tags, replacing them with in-line code backticks (within the link), like this:

**Returns**: [`reducerFn`](#reducerFn) - snip snip

With this enhancement, the references are linkable!

This seems so basic that I can't believe it is a bug. Am I missing something? If not, I believe this change should be incorporated in your library.

FYI: My markdown is interpreted through GitBook. Not sure if that is a variable in the equation or not.

Thoughts?

BTW: Great Library!

@75lb

This comment has been minimized.

Show comment
Hide comment
@75lb

75lb Apr 12, 2017

Member

there are so many different markdown parsers - all the main sites use different ones.. when you see oddities in the partials like <code> tags being used instead of backticks, you're seeing a "lowest common denominator" solution - i.e. a solution which works in the most amount of markdown parsers..

Maybe it's time to review all the partials against the latest versions of the various markdown parsers, but for now they may be ugly but they work..

Member

75lb commented Apr 12, 2017

there are so many different markdown parsers - all the main sites use different ones.. when you see oddities in the partials like <code> tags being used instead of backticks, you're seeing a "lowest common denominator" solution - i.e. a solution which works in the most amount of markdown parsers..

Maybe it's time to review all the partials against the latest versions of the various markdown parsers, but for now they may be ugly but they work..

@75lb 75lb closed this Apr 12, 2017

@KevinAst

This comment has been minimized.

Show comment
Hide comment
@KevinAst

KevinAst Apr 12, 2017

Thanks for the quick reply! This gives me more insight into your dilemma (i.e. so many markdown parsers).

Thanks again for the great library!

KevinAst commented Apr 12, 2017

Thanks for the quick reply! This gives me more insight into your dilemma (i.e. so many markdown parsers).

Thanks again for the great library!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment