Add anchor ids to md doc headings

[bluetidepro]

I'll probably look at building it out myself, but wanted to make a record of the idea just in case someone beats me to it.

Basically, the idea is that anytime in your component docs that you use a header (ex: ## Blah) it would auto add anchor id's to it so you could ref it in the url. This is a similar concept to what GitHub auto does for .md files. For example, I can link to https://github.com/styleguidist/react-styleguidist#usage and it will auto scroll to the Usage header in that .md file.

To expand, if you had a header in the Button component docs, you could link to it to like https://react-styleguidist.js.org/examples/basic/#!/Button#example4 or something similar without going into isolation mode, but still linking to that part of the page in the doc.

We could also look at doing some fancy styling like GitHub has that shows an icon (on hover) of headers to get that url:

What is everyone's thoughts on this? Do you all think it would be worth having this feature? Would it conflict with the current routing at all, by any chance?

[seivan]

@bluetidepro You mean, keep the sidebar around when linking to e.g http://localhost:6060/#!/Button/1 ?

[bluetidepro]

@seivan No, I mean like if you were to go to https://react-styleguidist.js.org/examples/basic/#!/Button first, then in the examples you had various headers in the markdown (making the page extremely long possibly), you would be able to add an anchor link to your url (https://react-styleguidist.js.org/examples/basic/#!/Button#Headername for example) to auto scroll to that section on the long component docs.

Again, the best example I have is something like this: https://github.com/styleguidist/react-styleguidist#third-party-tools - Where when you click that link it auto scrolls all the way down to the "third-party tools" section because the header has the anchor id on it.

Really, think should be fairly simple to do. Just need to add id's to the component that generates the headers from the markdown and then make sure it works with the routing in place.

[seivan]

Oh ok, you want your markdown tags have anchor links generated for them?
Because there are links right now for each example of a component.
It just hides the side bar. Not sure if you knew or not.

[bluetidepro]

@seivan Right, but that doesn't work in this use-case because sometimes you write markdown notes, headers, and comments above the examples, but the isolation mode for each example that you are referring to is just for the example part. So, if I wanted to link to a certain header of the component's page docs then I wouldn't be able to today. This is esp useful if you have long docs for a component, and that's the use-case that came up for me.

Here is a screenshot of what I mean for my use-case: http://bluetide.pro/2cl4JB - As you can see, that's just a small portion of the long page of docs for the Grid component I made. Setting one column width in my screenshot is an h3 (I believe), it would be nice to link someone directly to that part of the docs for the Grid component if I'm referencing that or need to show them something, rather than them digging through that whole page to find it.

[seivan]

Understood! 👍

[bluetidepro]

@seivan Sweet! Yeah, it should be fairly straight forward to build out, since it's just added an id in the markdown generator for the headers, but I will take a closer look this week to see if it's as easy as I think it should be! :) haha

[sapegin]

That’s a good idea! Feel free to send a PR for that ;-) You’ll probably need to prefix IDs to avoid clashes with already existing IDs that we generate on the backend. We already have github-slugger in dependencies to generate slugs.

[okonet]

AFAIK github-slugger takes care of repetitions but in order for that to work all heading needs to be "exposed" globally.

[Spenc84]

How's this coming along? Our team has opted to have each section and component displayed on it's own page, but some of those pages can get quite extensive and the inability to create anchors to the various parts of an individual page has started to become problematic. I've spent half a day now trying to find a way to create and link to anchors on an individual page but have not as of yet found a way to do it.

Is support for page anchors still something that's being considered?

[sapegin]

It will be in Styleguidist as soon as someone submits a pull request.