hardhat.org mangles anchor navigation for plugins docs

[aspiers]

This is a documentation bug specific to https://hardhat.org/plugins/hardhat-deploy.html - at the top of that plugin's documentation you will see a table of contents. But clicking on many of the items within that TOC will fail to jump to the correct section. For example, click on 2. hardhat node within the TOC and nothing will happen because the target anchor link doesn't exist.

This is not an issue with the hardhat-deploy third-party docs. If you visit their README, you can see the TOC navigation working fine:

https://github.com/wighawag/hardhat-deploy/tree/master

The problem appears to be that hardhat.org is mangling the link targets. For example, the item 2. hardhat node has the hyperlink:

• https://hardhat.org/plugins/hardhat-deploy.html#2-hardhat-node

but the link target is actually:

• https://hardhat.org/plugins/hardhat-deploy.html#_2-hardhat-node

so following the link fails to navigate anywhere.

For comparison, the original README has the correct anchor both in the TOC link and the target section:

• https://github.com/wighawag/hardhat-deploy/tree/master#2-hardhat-node

[drortirosh]

This is but a problem with the hardhat.org sure itself, but with the markdown parser of vuepress, which is slightly different than the markdown parser of github..

[aspiers]

Thanks for the info! I see that https://vuepress.vuejs.org/guide/markdown.html says:

Headers automatically get anchor links applied. Rendering of anchors can be configured using the markdown.anchor option.

So the problem seems to be that vuepress automatically generates anchors with a different algorithm to GitHub. Looking further, the "Advanced Configuration" section says:

VuePress uses markdown-it as the Markdown renderer. A lot of the extensions above are implemented via custom plugins. You can further customize the markdown-it instance using the markdown option in .vuepress/config.js

and looking at markdown-it's GitHub issue tracker reveals markdown-it/markdown-it#28 (Header anchors [needs discussion]) which has been open since 2015, even though there are plugins available for markdown-it to automatically generate header anchors. I'm not sure which one hardhat.org uses, but https://github.com/valeriangalliat/markdown-it-anchor is one example, the author of which is already aware of compatibility issues between different header anchor generation schemes.

[aspiers]

Ahah! I just noticed https://github.com/nomiclabs/hardhat/blob/master/docs/.vuepress/config.js, which configures markdown to use a custom slugify function which wraps around this default slugify:

https://github.com/nomiclabs/hardhat/blob/619034bfe33b96141dd504bf98dda847878259bf/docs/.vuepress/config.js#L1

and VuePress's Config Reference confirms that slugify is indeed the config option responsible for generating header anchors. (There also seems to be anchor, but I'm not sure what the difference is.)

(It's also worth noting that slugify may be used for generation of other things like file paths, not just header anchors.)

But I was wrong when I previously wrote:

So the problem seems to be that vuepress automatically generates anchors with a different algorithm to GitHub.

Of course it doesn't matter what algorithm is used, as long as it is consistent between the generation of the links in the TOC and the generation of the anchor targets for the headers.

Looking at the implementation of the default slugify from @vuepress/shared-utils, I previously thought this was the culprit line:

but I was wrong: the problem is not just with the _ prefix; there appear to be multiple inconsistencies between how the TOC links are generated and how the header anchors are generated. As an example of a different inconsistency, with a header whose text contains the / symbol:

• https://hardhat.org/plugins/hardhat-deploy.html#hardhat-tasks-availableupdated is the link used by the TOC, but
• https://hardhat.org/plugins/hardhat-deploy.html#hardhat-tasks-available-updated is the actual working anchor link

I've filed https://github.com/vuejs/vuepress/issues/2913 to report this.

[fvictorio]

Wow, thanks a lot @aspiers, this is incredibly useful. At some point we are going to stop rendering third-party plugins's readmes on the site, but if I'm understanding correctly this would also affect the core plugins if we add tables of contents to them (and some of them should probably have TOCs)

[aspiers]

Yeah I don't think this is specific to third-party plugins - you're probably right that we'd see the same problem with TOCs on any page within the site's VuePress.

[github-actions[bot]]

This issue was marked as stale because it didn't have any activity in the last 30 days. If you think it's still relevant, please leave a comment indicating so. Otherwise, it will be closed in 7 days.

[fvictorio]

@aspiers I think this is no longer relevant because we no longer show third-party plugins under hardhat.org (we just redirect to the npm page). Can you confirm if this is the case?

(The reason we did this change is to prevent users from thinking that these are official plugins.)