implementing uniform doc page `id` for all documentation

[iamayushdas]

Actual Behaviour

The page id is not uniform for any of the documentations present in website

Expected Behaviour

There should be a uniformity in id for all docs of our sub projects.

1. you can see here in screenshots that id is random for every page
2. having uniform id's are very useful for developers to play with the DOM and implementing new features

Screenshots of the issue

Proposed solution Making uniform subheadings to every documentation.

Would you like to work on the issue?

Yes i would like to work on it

@juzhiyuan @Yiyiyimu please share your opinion

[juzhiyuan]

Not sure exactly what you mean 😳😳 Could you please describe more clearly?

[iamayushdas]

I have used subheading id as get selector to Manipulate DOM in naming the doc dropdown

But newly added commit in "apisix helm chart" has changed the subheading and therefore id is also changed

[iamayushdas]

Go to:

1. Apisix website
2. Choose apisix helm chart from doc dropdown You will see that docs is no longer renamed to what it was supposed to be. @juzhiyuan

[juzhiyuan]

Oh yes, I see what happens.

[juzhiyuan]

Just do it

[iamayushdas]

After new features from V2 i have got a way to fix this, I am fixing this please reopen it, @juzhiyuan @Yiyiyimu

[spacewander]

@iamayushdas First of all, you should discuss this in the mail list dev@apisix.apache.org before sending a bunch of PRs. It seems only a few people know this purpose.

Secondly, please modify the doc in a repo first, and evaluate the effect. Don't change a lot of things. Change it step by step.

Thirdly, it is not a good idea to put a visible mark on an obvious place. I just spend some time on this issue and get an idea:

Since the doc is pulled from other repo before building it on the website, we can introduce a preprocessor that converts the invisible mark to the mark that can be recognized by the render.

I am not sure if it works but at least there is way to achieve the goal with a better solution.

[juzhiyuan]

Agree with @spacewander, please have 1 repo test, or your bunch of PRs will confuse people who don't know this case :)

[iamayushdas]

okay we could first go with apisix-dashboard @juzhiyuan

[iamayushdas]

@iamayushdas First of all, you should discuss this in the mail list dev@apisix.apache.org before sending a bunch of PRs. It seems only a few people know this purpose.

Secondly, please modify the doc in a repo first, and evaluate the effect. Don't change a lot of things. Change it step by step.

Thirdly, it is not a good idea to put a visible mark on an obvious place. I just spend some time on this issue and get an idea:

Since the doc is pulled from other repo before building it on the website, we can introduce a preprocessor that converts the invisible mark to the mark that can be recognized by the render.

I am not sure if it works but at least there is way to achieve the goal with a better solution.

I understood sir, thank you for making me understand

[juzhiyuan]

Thirdly, it is not a good idea to put a visible mark on an obvious place. I just spend some time on this issue and get an idea:

As for this, because I haven't experienced this case, then it's ok for me to do this (is Docusarus using this? @iamayushdas) Waiting for more suggestions :)

cc @liuxiran @bzp2010 @lilien1010 @tokers @Yiyiyimu

[iamayushdas]

cc @liuxiran @bzp2010 @lilien1010 @tokers @Yiyiyimu yes docusaurus is using this now on @juzhiyuan

Docusaurus has opted this way for adding id's to be more precise. they have changed the md style in such a way that we can add precise id without harming our website reference md file - https://github.com/facebook/docusaurus/blob/master/website/docs/api/plugins/plugin-content-blog.md

screenshot:

website created from above md file: https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog

screenshot: https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog

[spacewander]

Are we discussing the "invisible mark way"? We should use a better way to solve the issue. A visible scar is unacceptable.

[iamayushdas]

If we change the subtitle with the name of sub-project then, then that name will automatically become the id

For example- if i name the sub title

APISIX-dashboard

This will automatically attach an id to the subtitle

apisix-dashboard

Also i am discussing about the invisible mark manner in docusaurus mailing list. @spacewander

[iamayushdas]

[iamayushdas]

Thirdly, it is not a good idea to put a visible mark on an obvious place. I just spend some time on this issue and get an idea:

As for this, because I haven't experienced this case, then it's ok for me to do this (is Docusarus using this? @iamayushdas) Waiting for more suggestions :)

cc @liuxiran @bzp2010 @lilien1010 @tokers @Yiyiyimu @gxthrj